Values and errors¶
A native receives HQL values and returns one. This page covers the Rust type that holds them, arguments written by name, records of a type the package declares, and the two ways a call fails.
Value¶
Every HQL value is a hql::ext::Value, an enum with one variant per kind
of value. The ones a package meets most:
| HQL type | Variant | Holds |
|---|---|---|
Int |
Value::Int(i64) |
a 64-bit integer |
Float |
Value::Float(f64) |
a double |
Bool |
Value::Bool(bool) |
|
String |
Value::Str(Arc<str>) |
text |
List<T> |
Value::List(Arc<Vec<Value>>, TypeRef) |
the elements and the element type |
| a record type | Value::Record(Arc<Record>) |
the type and the fields in declaration order |
Option<T>, present |
Value::Present(Arc<Value>) |
the value |
Option<T>, absent |
Value::Absent(TypeRef) |
the type of what is absent |
| a function | Value::Function(…) |
applied through the context, never by hand |
A list is built with Value::list(elements, element_type), and the common
types are constants: TypeRef::INT, TypeRef::FLOAT, TypeRef::STR.
A native matches on the variant the contract promises. shout is declared
on a String and on a Greeting, so its one function reads both:
fn shout(
_cx: &mut dyn EvalCx,
input: Value,
_arguments: &[TypedArg],
span: Span,
) -> Result<Value, Diagnostic> {
let said = match &input {
Value::Record(record) => match record.field("text") {
Some(held) => text(held, &span)?,
None => return Err(ext::failure(span, "expected a `Greeting`")),
},
other => text(other, &span)?,
};
Ok(Value::Str(said.to_uppercase().into()))
}
Arguments¶
input is evaluated when the function is called. The other arguments are
not: each is a TypedArg, the argument's expression with the name it was
written with. A function finds the ones it wants and evaluates them:
| Function | Gives |
|---|---|
ext::named(arguments, "punctuation") |
the argument written punctuation = …, if the call wrote it |
ext::positional(arguments, 0) |
the first argument written without a name, after the input |
ext::value_of(cx, argument) |
the argument's value |
An argument with a default that the call leaves out is not in
arguments. The function supplies the default the contract states:
let punctuation = match ext::named(arguments, "punctuation") {
Some(argument) => text(&ext::value_of(cx, argument)?, &span)?,
None => "!".to_owned(),
};
import hello
g = Greeting("Ada", punctuation = "?")
[g.text, str(g.length)]
["Hello, Ada?", "11"]
Records¶
A value of a record type the contract declares is built with
ext::record: the type by its name, then the fields in the order the
contract declares them.
Ok(ext::record(
ext::ty("Greeting", []),
[
("text", Value::Str(said.into())),
("length", Value::Int(length)),
],
))
ext::ty("Greeting", []) is the type Greeting with no type arguments.
The name is the one the contract declares; the contract is where the
fields and their types are stated, and the Rust follows it. An optional
field, target? : List<Float>, holds a Value::Present or a
Value::Absent.
Failures¶
A function that cannot give a result returns a diagnostic.
ext::failure(span, message) makes one that points at the call:
let length = i64::try_from(said.chars().count())
.map_err(|_| ext::failure(span.clone(), "the greeting is too long"))?;
The message is one sentence for the person who wrote the program. It says
what was wrong with the value, in the program's terms: row 1 has 2
features; row 0 has 1, not the name of a Rust error.
A failure is an ordinary failure of the program. Under collect, or
handled by the steps of chapter 12, it behaves as a failure
of a standard function does.
Panics¶
A Rust panic inside a native does not end hql. hql::native! runs each
function under a guard that catches a panic and returns it as a failure
of the call, naming the function:
import hello
hello.fail("boom")
execute failure[invalid-argument]: the extension function `fail` panicked: boom
--> <expression>:3:1
|
3 | hello.fail("boom")
| ^^^^^^^^^^^^^^^^^^
The guard is a net, and a failure is the intended path. A panic reports a
defect of the package: an index out of range, an unwrap on nothing. A
value a program can pass is refused with ext::failure.