Skip to content

Functions and the context

Some declarations take a function, as map and filter do. The function belongs to the program, so the native cannot run it: it asks the running hql to. Everything a native asks of the running program goes through its first parameter, the context, cx: &mut dyn EvalCx.

Applying a function argument

fn total<T>(self: List<T>, weight: T -> Int) : Int sums a function over a list:

fn total(
    cx: &mut dyn EvalCx,
    input: Value,
    arguments: &[TypedArg],
    span: Span,
) -> Result<Value, Diagnostic> {
    let Value::List(elements, _) = input else {
        return Err(ext::failure(span, "expected a `List`"));
    };
    let Some(weight) = ext::positional(arguments, 0) else {
        return Err(ext::failure(span, "`total` takes a function"));
    };
    let mut sum = 0_i64;
    for element in elements.iter() {
        match cx.apply_lambda(weight, element.clone())? {
            Value::Int(weighed) => {
                sum = sum
                    .checked_add(weighed)
                    .ok_or_else(|| ext::failure(span.clone(), "numeric overflow"))?;
            }
            _ => return Err(ext::failure(span, "`weight` gives an `Int`")),
        }
    }
    Ok(Value::Int(sum))
}

cx.apply_lambda(weight, element) applies the function written as the argument weight to one element and gives its result. A failure inside the program's function comes back through ? as the call's failure.

import hello

[[1, 2, 3].total(x => x * 10), ["ab", "cde"].total(word => word.size())]
[60, 5]

The contract's T -> Int is what lets the program write x => x * 10 without a type: the checker gives x the element type of the list, and checks that the body is an Int, before total is ever called.

What the context offers

Method What it does
evaluate(&argument.value) the value of an argument; ext::value_of calls it
apply_lambda(argument, element) an argument that is a function, applied to one value
apply_function(argument, values) an argument that is a function, applied to several values
call(&function, values, &span) a function value, applied to values: an element of a list of functions, for example
compare_values(&a, &b, &span) the order of two values, by the type's own Ord where it has one
equal_values(&a, &b, &span) whether two values are equal as == says
draw(&span) 64 bits from the evaluation's random seed, which --seed fixes
warn(diagnostic) a diagnostic that does not fail the call
vault() the vault the program runs against

call differs from apply_lambda in what it is given. apply_lambda takes an argument of the call, still unevaluated. call takes a value that already is a function, which is what a list of functions holds once the list is evaluated:

let readers = ext::value_of(cx, features)?;          // a List of functions
for reader in elements(&readers) {
    let feature = cx.call(reader, vec![row.clone()], &span)?;
}

draw is how a function without a seed argument of its own stays reproducible: its draws follow the program's seed, so hql --seed 7 repeats them. A function that draws this way is declared effectful fn (purity).

Why everything goes through the context

A package's library holds its own compiled copy of the hql crate (chapter 35). The running program's state, its bindings, its seed, its clock, its diagnostics, lives in the copy inside the hql binary. The library's copy has state of its own, which no program ever set.

The context is a reference into the running copy. A native that calls cx.draw reads the program's seed. A native that reached for the hql crate's random functions directly would read its own copy's, which is unseeded. For that reason hql::ext exposes values, diagnostics and the context, and a native uses nothing else of the crate.