Skip to content

Natives

A native is a Rust function that implements the declarations of one name. This page writes the simplest one, lists it in a table, and exports the table as the package's extension. All of it is src/lib.rs.

One function

fn greet(name: String) : String is implemented by:

use hql::ext::{self, Diagnostic, EvalCx, Operation, Span, TypedArg, Value};

fn greet(
    _cx: &mut dyn EvalCx,
    input: Value,
    _arguments: &[TypedArg],
    span: Span,
) -> Result<Value, Diagnostic> {
    match input {
        Value::Str(name) => Ok(Value::Str(format!("Hello, {name}!").into())),
        _ => Err(ext::failure(span, "expected a `String`")),
    }
}

Every native has this signature.

Parameter What it is
cx the running program: what the function may ask of hql while it runs (Functions and the context)
input the value the call is made on: the receiver, or the first argument where the declaration has no self
arguments the call's other arguments, unevaluated, each with the name it was written with, if any
span where the call is in the program's source, for a diagnostic to point at

The result is a Value or a Diagnostic.

By the time greet runs, the call was checked against the contract, so input is a String. The second arm of the match cannot be reached by a program. It is there because Rust requires every case, and a failure is a better answer to an impossible case than a panic.

The table

The functions of a module are listed in a table, each under the name its declarations use:

static HELLO: &[Operation] = &[
    hql::native!("Greeting", greeting),
    hql::native!("greet", greet),
    hql::native!("shout", shout),
    hql::native!("total", total),
    hql::native!("fail", fail),
];

hql::native! makes an Operation from a name and a function. A name with several forms, shout, has one entry. The table has an entry for every name the contract declares and no others: a declaration without an entry, or an entry without a declaration, refuses the package.

An operation built this way is pure and a barrier, which is what a declaration written plain fn states. A declaration written effectful fn takes .effectful() on its entry, and one written with a shape word takes .shaped(…):

hql::native!("split", split).effectful(),
hql::native!("double", double).shaped(hql::ext::Shape::Elementwise),

The extension

One line states the package and exports it:

hql::extension!(ext::extension(
    "hello",
    env!("CARGO_PKG_VERSION"),
    &[ext::provided("hello", HELLO)],
));

ext::extension takes the package's name, the crate's version, and one ext::provided per module: the module's name with its table. The names and their order are those of provides in Cargo.toml.

hql::extension! is written once in the crate. It defines the one function hql looks for when it loads the library, hql_extension_v1 (chapter 35).

Building and trying it

hql package install --path hello
installed hello 0.1.0 (hello) in /home/ada/.hql/packages/hello

The command runs cargo build --release on the crate, copies the library and the module root into the HQL home, and loads the result. A package that builds and does not bind is reported here, by the defect binding found, and not when a program later imports it.

import hello

hello.greet("Ada")
"Hello, Ada!"