Skip to content

How the standard library is built

The standard library is a package named std. Its modules are HQL files of declarations, and its extension is Rust compiled into the hql binary. A package you write has the same two halves; the one difference is where its Rust is kept (chapter 35).

The contract

A module's file of declarations is its contract. This is the head of the contract of math, the file lib/std/math/mod.hql:

module math

import core

/// `self` without its sign, at its own type: `abs(-3)` is `3`,
/// `abs(-1.50)` is `1.50`, and `abs(Duration("-PT1H"))` is `PT1H`.
fn abs(self: Int) : Int
fn abs(self: Float) : Float
fn abs(self: Decimal) : Decimal
fn abs(self: Duration) : Duration

/// The square root of `self`: `sqrt(2.0f)` is `1.4142135623730951`.
fn sqrt(self: Float) : Float

The file opens with module and its name, imports the modules whose types it writes, and declares. A /// doc string above a declaration is what help prints for it. The contract is the whole of what a program is checked against: the checker never reads Rust.

The implementation

Beside the contract is one Rust function per declared name, and a table that lists them by that name:

pub(crate) static STEPS: &[Operation] = &[
    declared("abs", eval_abs),
    declared("sqrt", eval_sqrt),
    // …
];

fn eval_abs(
    _: &mut dyn EvalCx,
    input: Value,
    _: &[TypedArg],
    span: Range<usize>,
) -> Result<Value, Diagnostic> {
    match number(&input, "abs", &span)? {
        Value::Int(n) => n.checked_abs().map(Value::Int).ok_or(Diagnostic::overflow(span)),
        Value::Float(x) => Ok(Value::Float(x.abs())),
        Value::Decimal(x) => Ok(Value::Decimal(x.abs())),
        _ => unreachable!("number() answers a number"),
    }
}

eval_abs takes the value the call is made on, the call's other arguments, and the place of the call in the source, and gives a value or a diagnostic. It serves all four forms of abs and reads which one it was given from the value. The Rust states no HQL type: the types are the contract's.

Binding

Binding joins the two halves, once, before the first program is checked. For each module of each package it pairs every declaration with the function of the same name in that module's table, and it refuses the package where the halves disagree:

Defect What binding reports
a declaration with no function the declaration is declared, and the extension implements no such function
a function with no declaration the extension implements a name no contract declares
effectful fn over a function marked pure, or the reverse the two markings differ
a shape word that differs from the function's marking the two markings differ
a type the contract writes and no module declares the declaration states no signature

Because binding runs before any program does, a package is never half usable: either every declaration of its modules has its function, or the package is refused whole.

Reading the result

hql builtins prints what binding produced: each module, the package and version that provide it, and each declared name with its forms, its purity and its shape.

hql builtins
math (std 0.7.1, prelude)
  abs
    Int | abs() -> Int
    Float | abs() -> Float
    Decimal | abs() -> Decimal
    Duration | abs() -> Duration
    pure, barrier

Int | abs() -> Int reads: on an Int, abs with no further arguments gives an Int. The value before | is the receiver.