Skip to main content

Crate htl

Crate htl 

Source
Expand description

htl — Holistic Typed Lua.

Umbrella crate: everything from htl_core plus, with the default macros feature, the proc macros from htl-macros. Generated code from the macros refers to ::htl::..., so depend on this crate (not on htl-core directly) when you use include_tl! / include_tl_bytes! / teal_types! / #[derive(TealRecord)] / #[host_module].

§Embedding

ⓘ
use htl::{Htl, TealRecord, host_module, include_tl, include_tl_bytes};

#[derive(TealRecord, Clone)]           // Teal record <-> plain table (IntoLua / FromLua)
pub struct Point { pub x: f64, pub y: f64 }

pub struct Host { started: std::time::Instant }

#[host_module(name = "host", dts = "scripts/host.d.tl", records = [Point])]
impl Host {
    pub fn uptime_ms(&self) -> u64 { self.started.elapsed().as_millis() as u64 }
    pub fn scale(&self, p: Point, k: f64) -> Point { Point { x: p.x * k, y: p.y * k } }
    pub fn greet(name: &str) -> String { format!("hello, {name}") }            // static
    pub fn parse(s: &str) -> Result<i64, std::num::ParseIntError> { s.parse() } // Err -> Lua error
}

const MAIN: &str = include_tl!("scripts/main.tl");              // checked at cargo build
const UTIL: &[u8] = include_tl_bytes!("scripts/util.tl");       // same, as stripped bytecode

fn main() -> anyhow::Result<()> {
    let h = Htl::new()?;
    Host { started: std::time::Instant::now() }.htl_preload(&h)?;
    h.preload_bytes("util", UTIL)?;
    h.exec(MAIN, "@scripts/main.tl", &[])?;         // frames read scripts/main.tl:<line>
    Ok(())
}

include_tl! checks the file with the search path htl check gives it (project::file_view); a crate whose Teal lives in scripts/ says [layout] source = "scripts". A script that reads arg[1] needs Htl::set_arg before Htl::exec. What crosses between Rust and Teal, and as what, is dts; what holds the runtime to the declaration is teal::Strict and Htl::strict_strings; a host running Teal it did not write builds the Lua itself and hands it to Htl::with_checker_lua. A crate that registers a module for other people’s projects ships the declaration (dep_dts); a crate whose Teal has dependencies ships them as a patched copy (Htl::apply_project). A host that serves modules at run time describes its directories once (model::Project::for_host) and derives the checker and the run from that (pkg::TealResolver).

The crates htl is built against are re-exported, so a host names the versions htl links rather than adding its own: mlua, mlua_isle, serde (with derive) and serde_json. A host with no serde dependency of its own derives through htl::serde and writes #[serde(crate = "htl::serde")] on the type, because serde’s derive writes ::serde paths; one that has the dependency changes nothing.

The macros run the checker inside the proc macro, under [profile.dev.build-override] — htl new --embed writes opt-level = 3 into that section, and a host that predates it adds the two lines by hand (one rebuild of the macro’s dependencies, then every build after); see htl_macros.

§Features

With the ffi feature there is a fourth way out, for a caller that is not written in Rust: the C ABI runtime — the handle, the error slot, the panic guard — and an attribute that writes one extern "C" wrapper per method and the C header, from the same impl block #[host_module] reads. Off by default, so a host with no C caller compiles as it did before. A host that turns it on adds crate-type = ["rlib", "cdylib"] (plus "staticlib" for Unity on iOS); cargo build then writes the header, and the library exports the <prefix>_* functions and nothing else. The two are named and linked in the paragraph this page shows when the feature is on; without it there is nothing on this page to link to, and a link to an item that is not compiled is a broken one. That way out is ffi and c_export.

The async feature is off by default for the same reason: it turns on mlua’s own async and mlua-isle’s executor, and a host with no async method should be built as it was without it. With it, an async fn in a #[host_module] is a call Teal can await, Htl::run_async / Htl::run_blocking run a program as a root on the executor, and htl.task (Htl::install_task_lib) is the task library the async / await syntax desugars to, with the channels, timers and select a loop in Teal waits on and the typed host channels (htl::task::RecvChannel / SendChannel) a host feeds it through; the README’s Async section is the tour.

A host whose Lua lives on a thread of its own — mlua-isle’s AsyncIsle reaches that state only from closures that run on its own thread (init, exec, and the builder’s own .lua factory); init is the one that runs once, before any request — still reaches Htl::with_checker_lua from inside init: lua.clone() (mlua’s Lua is a cheap handle to the state, not a copy) is the owned Lua it asks for, and the Htl this builds, and the checker it borrows, are used and dropped inside init, never crossing a thread — which is what a non-Send value captured from outside could not do, so the checker is built fresh here too. Once init returns, both are gone: the state runs only what was compiled ahead of it (a bundle’s modules, preloaded source or bytecode) — nothing on it can check or resolve a .tl file, which needs a live checker (htl::pkg’s resolvers take one).

ⓘ
use htl::Htl;
use htl::bundle::Bundle;
use htl::mlua::Lua;
use htl::mlua_isle::AsyncIsle;

fn install(lua: &Lua, bundle: &Bundle) -> Result<(), htl::mlua::Error> {
    let checker = Htl::new().map_err(htl::mlua::Error::external)?;
    let h = Htl::with_checker_lua(&checker, lua.clone()).map_err(htl::mlua::Error::external)?;
    h.install_task_lib().map_err(htl::mlua::Error::external)?;
    h.install_bundle(bundle).map_err(htl::mlua::Error::external)
}

let (isle, driver) = AsyncIsle::spawn(move |lua| install(lua, &bundle)).await?;
let answer: i64 = isle.coroutine_eval("return require('entry').answer()").await?;
driver.shutdown().await?;

requireing the bundle and running what it set up are two different coroutine turns: a module whose own top-level body awaited a task would be yielding across the bundle loader’s Function::call, which is not a yield point — Lua’s own “attempt to yield across a C-call boundary”, not mlua-isle’s “sync requests cannot spawn”. entry’s module above only requires at its own top level; whatever spawns and awaits a task — here answer() — runs on its own coroutine turn, once require has already returned. AsyncIsle::coroutine_eval / coroutine_call run the way Vm::run does, so that works the same way a program run through Htl::run_async would.

with_checker_lua’s attach runs inside init, before the isle attaches its own copy afterward; with no .config(...) on the builder, that second attach keeps whatever is already there, so the isle’s cancel grace ends up at htl’s default (one second) rather than mlua-isle’s own default (zero). A project’s [async] section still reaches the state: call Htl::configure_async from inside init, once h is built.

§Against an unpublished htl

A consumer building against a checkout of htl before a change is published patches all three crates in its [patch.crates-io], not this one alone: htl re-exports htl-core, and the proc macros in htl-macros run htl-core at expansion time, so patching only htl builds two versions of the same code into one graph. Cargo keeps the version Cargo.lock already resolved until cargo update -p htl -p htl-core -p htl-macros is run once; the same command, with the block deleted, goes back.

Nearly everything documented here is defined in htl_core and re-exported by the line below, so that is where those pages are written and where a gap in them is filled. The deny under this paragraph holds only what this crate defines itself: missing_docs fires in the crate that defines an item, not in the one that re-exports it, so a clean run here says nothing about htl_core’s half of the same public surface. That half is being closed file by file, and the deny goes there when it reaches zero (#224).

Modules§

adopt
Which of htl’s nine markers a project has actually written, and where.
batteries
std.*: mlua-batteries inside the binary, installed the way htl.test is.
build_target
BuildTarget: what runs the output of an htl project.
bundle
Bundle format (.hb): one program’s modules in a single file.
cache
An on-disk cache of what checking one module reported (issues #3, #19).
cexport
What #[c_export] writes: the plan for one extern "C" wrapper per method, and the C header that declares them.
config
htl.toml: project-level settings shared by the CLI and include_tl!.
contract
---@contract / ---@required: the contract a directory of modules must satisfy, declared where the type is declared.
dep_dts
Declarations a dependency crate ships, materialised into the project’s types/.
diagnostic
What a check reported, as a value rather than as a line of text.
dts
Teal declaration (.d.tl) generation from Rust source.
ffi
The C ABI an htl host hands to a caller that is not written in Rust.
fix
Applying the fixes that diagnostics carry (htl fix).
link
Linking: the require closure of one entry file, as a Bundle.
lint
The rules a finding can be reported under, and which of them a run has on.
mlua
High-level bindings to Lua
mlua_isle
The owner of a state’s debug hook (mlua_isle::runtime::Vm): Interrupt, coverage and a host’s own instruction or line callback register with it rather than each taking the one hook slot a Lua thread has — see Htl::hook_owner. Thread-isolated Lua VM with cancellation for mlua.
model
The project model: which modules a project is made of, where each keeps its files, and what name a file answers to.
naming
The naming rule: which module name a file answers to, and — the same rule read the other way — which files may answer to a name.
pkg
mlua-pkg integration: a TealResolver that serves .tl modules through mlua-pkg’s Registry, so Teal sources sit in the same resolution chain as Rust-native modules, embedded Lua, vendored git deps and assets.
project
A check over a project: many files, a run cache, and the decisions that go with them.
registry
The seam a binary adds its own require-able libraries through, wherever this crate builds an Htl for its own use rather than the binary’s: crate::testing’s per-test state and crate::project::checker. Both already call Htl::install_std and Htl::install_task_lib for the libraries this crate can name itself; this module is for the ones it cannot.
resolve
Which file require("<name>") resolves to, what that hides, and where each of them came from — the report behind htl resolve.
rsgen
The Rust types of the records and enums a project’s modules declare, lowered from what the checker knows of the files (htl rs, htl::teal_types!()).
run
A Teal module’s functions, called from async Rust: one VM thread, many program states on it, and a deadline on every call (htl::run, feature async).
serde
serde, with its derive feature, as htl builds it: htl::serde. A host that already depends on serde itself changes nothing and keeps writing #[derive(Serialize)] against its own. A host that does not can derive through this one, but serde’s derive writes ::serde::.. paths into the code it generates, which only resolve against a direct dependency, so the type also says where serde is:
serde_json
serde_json, as htl builds it: htl::serde_json, for the host that reads or writes the JSON its htl::serde types describe without a dependency of its own.
shapes
The run-time shape of each record and enum a file declares, lowered from what the checker knows of the file (htl shapes).
task
htl.task: concurrent tasks for a program on the executor, typed via task.d.tl.
teal
Rust <-> Teal type bridge used by #[derive(TealRecord)] and #[host_module].
testing
htl test: discovery, one isolated Lua state per test file, compile, report.
typeindex
What the checker knows about each position of a file, kept for an editor’s hover and go-to-definition (TypeIndex, CheckInfo::types).
unused
What no entry reaches: the complement of the require closure htl build links.
verdict
Whether a run fails: the findings of the run, and the policy that judges them.

Macros§

include_bundle
include_bundle!("src/main.tl", host = ["host"], extra = ["modkit"], payload = "source", debug = true)
include_tl
include_tl!("path.tl") -> &'static str: the Lua tl (the vendored Teal checker) generates from path.tl, relative to CARGO_MANIFEST_DIR, Teal-checked at build time against the project’s model and the crate’s #[host_module]s. Before checking, it regenerates every #[host_module]’s .d.tl it can see from the Rust source (regenerate_crate), so the #[host_module] it checks against does not have to be declared before this in the crate’s mod order — in the same file or another one (#429). A Teal type error, or a warning/lint the project’s policy denies, becomes a compile_error! at this macro’s call site; every .tl the check reads is include_str!-tracked, so an edit anywhere in the closure rebuilds. See the module doc for the lint policy and for what the regeneration cannot see.
include_tl_bytes
include_tl!, embedding stripped Lua 5.4 bytecode as &'static [u8] instead of the generated source — the same check, the same .d.tl regeneration, and the same tracking.
teal_types
teal_types!() -> the pub mod ... { ... } items htl rs writes, generated at cargo build from htl.toml ([rust] modules, exports and [rust.types]) through [htl_core::rsgen::generate], for a project that does not commit generated Rust.

Structs§

CheckInfo
Result of type-checking one .tl file.
ContractResult
Result of a static contract check (see Htl::contract_check).
DependencyError
A type error in a module a check reached through require (see CheckInfo::dependency_errors).
Diagnostic
One error: / warning: / lint: finding, split into its parts.
Edit
One text replacement: [start, end) in 1-based line / byte-column coordinates; an insertion has end == start.
Fix
A mechanical rewrite attached to a diagnostic (see fix).
FunctionSpan
A named function of a .tl file, for coverage (see Htl::coverage_spans).
GlobalSite
One global declaration a check saw (see CheckInfo::global_sites): the name and the site — file, line and column of the declared name — which is what tells two declarations of one name apart from one declaration seen through two requires.
Htl
An mlua state with the Teal compiler loaded.
MarkerSite
One marker the census found on a declaration (see CheckInfo::markers).
ModuleCandidate
One file require(name) could have resolved to. See Htl::module_candidates.
RecordSite
One table literal or as cast a check found typed as a declared record (see CheckInfo::record_sites).
Replaced
What Htl::replace_bundle did, so a host can say it rather than guess.
RequireSite
One literal require call in a checked file.
Strict
A host parameter that takes the Lua kind its Teal type names, and converts nothing.
UnmarkedSealed
One record unmarked_sealeds found a candidate for ---@sealed (#304).
UnmarkedStruct
One record unmarked_structs found a candidate for ---@struct (#304).

Enums§

Applicability
How safely a Fix can be applied without a human looking at it.
BuildTarget
A build target is what runs htl’s output. The htl binary runs a .hb bundle; the OS runs a native binary; a caller written in C, Python or C# loads a cdylib. That is the axis, and it is the only thing the entries below differ about:
ModuleKind
What a file on the search path is, for Htl::module_candidates. The three the searchers try, in the order they try them: a .tl source beats a .d.tl declaration wherever the two sit, and a plain .lua is what is left when neither is reachable.
Provision
What the project model says about a name that may run from no file of the project (Htl::model_provides).
Severity
How loud a diagnostic is. error fails a check; warning and lint do not unless the caller promotes them (htl check --strict, include_tl!).

Constants§

DEP_TYPES_NOTE
The note htl dts writes beside the declarations it materialises from a dependency crate, in types/<crate>/. The module that writes it is dep_dts, which the dts feature compiles.
SKIP_DIRS
Directories never descended into when collecting sources under a root: build output, installed packages, VCS and tool state. A root passed explicitly is always walked.
TEAL_VERSION
Teal version vendored into this crate: vendor/tl.lua, verbatim. There is no fork; the compiler is swapped as a file when it moves.

Functions§

checker_identity
A hash of the Lua the checker is made of: the vendored tl, the lints, the formatter, the _VERSION reader, the search chunk and the prelude. Two builds with the same value generate the same Lua for the same input, whatever else differs about them.
collect_tl
Collect .tl sources from files and directories (sorted, recursive). Directories in SKIP_DIRS, dot-directories and the project’s package dir are not entered unless given as a root themselves.
collect_tl_skipping
collect_tl, not entering skip either — directories named by path rather than by name, for what the caller knows and a name cannot say — the project model’s Project::not_walked.
contract_enforcement_lints
contract-unenforced lint: a contract only becomes a run-time guarantee when the host builds its resolver from it. Scan the host crate’s Rust sources — src/, examples/, tests/ and benches/ under cargo_root, a directory that is absent skipped — for contract_resolvers(. No host crate (cargo_root = None) means a script-only project: nothing to enforce.
contract_lints
contract lint for one file: when a directory a contract holds serves file as a module (contract::held_name: anywhere under it, by the name require writes — foo for foo/init.tl, sub.x for sub/x.tl), check it against that contract statically, as the host’s resolver for the directory holds it at run time. root is the directory holding htl.toml. Returns lint lines (empty when none applies).
declaration_conflict_lints
duplicate-declaration lint: a module file requires resolved to a .d.tl while another .d.tl for the same module was reachable further along the search path. One was read and the other was not, decided by position, and until now nothing said so — the case this catches is a host publishing a declaration into a project that also keeps a hand-written one for the same module.
developer_message
A message for whoever is developing the program: user_message’s innermost cause, followed by Lua’s stack traceback: block when the error carries one.
global_redeclarations
One global name declared at two sites among what a set of checked files brought into scope, one message per name, anchored at the later site (files sorted, then line and column) and naming the earlier one. The checker keeps the first declaration it walks and, when the second has the same type, says nothing (add_global in the vendored compiler returns without a word), so two .d.tl that both declare a name were read as one and nobody was told — the gap duplicate-declaration closes for two declarations of one module, closed here for one global.
is_cancelled
Whether err is the cancel of a run: what Htl::run_async and Htl::call_async resolve to when their token was cancelled, however the program took it — it is recognised by the value the runtime raised, never by its message. What htl run reads to print interrupted instead of a traceback.
is_declaration
true for foo.d.tl: a declaration, with the implementation somewhere else.
is_skipped_dir
true for a directory entry that source collection should not enter: a name in SKIP_DIRS, any dot-directory, or one of extra — named by path rather than by name, for what the caller knows and a name cannot say.
is_tl_source
true for foo.tl but not foo.d.tl.
lib_dir
Where the libraries that ship inside the binary put their .d.tl so the checker can see them: <tmp>/htl-lib-<version>-<key>/, with htl/test.d.tl and, under the std feature, std/*.d.tl below it. The files are written on demand by the library that owns them, only when their content changes.
materialised_types_dirs
The immediate subdirectories of types/ holding declarations materialised from a dependency, in name order.
parent_dir
Parent directory of a file, . when the path has none.
require_cycles
Cycles in the require graph of a set of checked files, one message per cycle, anchored at the first edge’s call site. Teal types a circular require as an opaque circular_require, so a cycle shows up elsewhere as “cannot index” errors; naming the loop is the useful part. Files outside infos are treated as leaves.
strip_traceback
Remove a trailing Lua stack traceback: section from an error text.
unmarked_sealeds
A record declared among the project’s own files, built and cast only in the file that declares it, and left unmarked ---@sealed (#304; htl adopt’s ---@sealed row reads the same list). A record is a candidate when all four hold:
unmarked_structs
A record declared among the project’s own files, built whole at every one of its construction sites, and left unmarked (#304; htl adopt’s ---@struct row reads the same list). A record is a candidate when all four hold:
user_message
A message for the people an embedding host serves: the innermost cause without Lua’s stack traceback: block. A host function’s Err(e) surfaces as e’s own text; a Lua error("msg") surfaces as file:line: msg.
user_message_lua
user_message for an error already held as mlua’s own type, which is how a caller that catches mlua::Result (the C ABI in ffi, say) has it.
write_if_changed
Write text to path only if the content differs. Returns true when written. Used by the derive macros to emit .d.tl files without churning cargo’s fingerprints.
write_if_changed_when
write_if_changed, writing only when write is set. Without it the answer is whether the file would change — what a dry run reports — and nothing on disk is touched.

Type Aliases§

CoverageSpans
What one parse gives a coverage report: the statement ranges, and the functions those ranges sit in. See Htl::coverage_spans.

Attribute Macros§

c_export
#[c_export(prefix = "hello", header = "include/hello.h")] on an impl block -> one extern "C" wrapper per pub fn, the handle lifecycle, and the C header.
host_module
Turn a plain impl block into a mlua::UserData impl, and write its Teal declaration (dts = "scripts/host.d.tl") when the macro expands, so a script sees host:scale(p: Point, k: number): Point and host.Point. Change a Rust signature and the next cargo build fails inside the .tl that relied on it: the declaration is rewritten first, and include_tl! / include_bundle! check against it. The breakdown is htl_core::dts::host_decl, which htl dts runs without building.

Derive Macros§

TealRecord
Declare a struct or enum on the Teal side and convert it both ways: TealRecord::DECL (the .d.tl text), IntoLua / FromLua that produce and accept exactly what it declares, and htl_preload. What each Rust shape lowers to is the type table in htl::dts, which is also what htl dts reads; the two cannot disagree.