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 wayhtl.testis.- 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 oneextern "C"wrapper per method, and the C header that declares them. - config
htl.toml: project-level settings shared by the CLI andinclude_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
requireclosure of one entry file, as aBundle. - 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 — seeHtl::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
TealResolverthat serves.tlmodules through mlua-pkg’sRegistry, 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 anHtlfor its own use rather than the binary’s:crate::testing’s per-test state andcrate::project::checker. Both already callHtl::install_stdandHtl::install_task_libfor 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 behindhtl 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, featureasync). - serde
- serde, with its
derivefeature, as htl builds it:htl::serde. A host that already depends onserdeitself 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 itshtl::serdetypes 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 viatask.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 buildlinks. - 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 Luatl(the vendored Teal checker) generates frompath.tl, relative toCARGO_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.tlit 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’smodorder — in the same file or another one (#429). A Teal type error, or a warning/lint the project’s policy denies, becomes acompile_error!at this macro’s call site; every.tlthe check reads isinclude_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.tlregeneration, and the same tracking.- teal_
types teal_types!()-> thepub mod ... { ... }itemshtl rswrites, generated atcargo buildfromhtl.toml([rust] modules,exportsand[rust.types]) through [htl_core::rsgen::generate], for a project that does not commit generated Rust.
Structs§
- Check
Info - Result of type-checking one
.tlfile. - Contract
Result - Result of a static contract check (see
Htl::contract_check). - Dependency
Error - A type error in a module a check reached through
require(seeCheckInfo::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 hasend == start. - Fix
- A mechanical rewrite attached to a diagnostic (see
fix). - Function
Span - A named function of a
.tlfile, for coverage (seeHtl::coverage_spans). - Global
Site - One
globaldeclaration a check saw (seeCheckInfo::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.
- Marker
Site - One marker the census found on a declaration (see
CheckInfo::markers). - Module
Candidate - One file
require(name)could have resolved to. SeeHtl::module_candidates. - Record
Site - One table literal or
ascast a check found typed as a declared record (seeCheckInfo::record_sites). - Replaced
- What
Htl::replace_bundledid, so a host can say it rather than guess. - Require
Site - One literal
requirecall in a checked file. - Strict
- A host parameter that takes the Lua kind its Teal type names, and converts nothing.
- Unmarked
Sealed - One record
unmarked_sealedsfound a candidate for---@sealed(#304). - Unmarked
Struct - One record
unmarked_structsfound a candidate for---@struct(#304).
Enums§
- Applicability
- How safely a
Fixcan be applied without a human looking at it. - Build
Target - A build target is what runs htl’s output. The
htlbinary runs a.hbbundle; the OS runs a native binary; a caller written in C, Python or C# loads acdylib. That is the axis, and it is the only thing the entries below differ about: - Module
Kind - What a file on the search path is, for
Htl::module_candidates. The three the searchers try, in the order they try them: a.tlsource beats a.d.tldeclaration wherever the two sit, and a plain.luais 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.
errorfails a check;warningandlintdo not unless the caller promotes them (htl check --strict,include_tl!).
Constants§
- DEP_
TYPES_ NOTE - The note
htl dtswrites beside the declarations it materialises from a dependency crate, intypes/<crate>/. The module that writes it isdep_dts, which thedtsfeature 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_VERSIONreader, 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
.tlsources from files and directories (sorted, recursive). Directories inSKIP_DIRS, dot-directories and the project’s package dir are not entered unless given as a root themselves. - collect_
tl_ skipping collect_tl, not enteringskipeither — directories named by path rather than by name, for what the caller knows and a name cannot say — the project model’sProject::not_walked.- contract_
enforcement_ lints contract-unenforcedlint: 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/andbenches/undercargo_root, a directory that is absent skipped — forcontract_resolvers(. No host crate (cargo_root= None) means a script-only project: nothing to enforce.- contract_
lints contractlint for one file: when a directory a contract holds servesfileas a module (contract::held_name: anywhere under it, by the namerequirewrites —fooforfoo/init.tl,sub.xforsub/x.tl), check it against that contract statically, as the host’s resolver for the directory holds it at run time.rootis the directory holdinghtl.toml. Returns lint lines (empty when none applies).- declaration_
conflict_ lints duplicate-declarationlint: a modulefilerequires resolved to a.d.tlwhile another.d.tlfor 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’sstack 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_globalin the vendored compiler returns without a word), so two.d.tlthat both declare a name were read as one and nobody was told — the gapduplicate-declarationcloses for two declarations of one module, closed here for one global. - is_
cancelled - Whether
erris the cancel of a run: whatHtl::run_asyncandHtl::call_asyncresolve to when their token was cancelled, however the program took it — it is recognised by the value the runtime raised, never by its message. Whathtl runreads to printinterruptedinstead of a traceback. - is_
declaration trueforfoo.d.tl: a declaration, with the implementation somewhere else.- is_
skipped_ dir truefor a directory entry that source collection should not enter: a name inSKIP_DIRS, any dot-directory, or one ofextra— named by path rather than by name, for what the caller knows and a name cannot say.- is_
tl_ source trueforfoo.tlbut notfoo.d.tl.- lib_dir
- Where the libraries that ship inside the binary put their
.d.tlso the checker can see them:<tmp>/htl-lib-<version>-<key>/, withhtl/test.d.tland, under thestdfeature,std/*.d.tlbelow 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 outsideinfosare 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---@sealedrow 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---@structrow 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’sErr(e)surfaces ase’s own text; a Luaerror("msg")surfaces asfile:line: msg. - user_
message_ lua user_messagefor an error already held as mlua’s own type, which is how a caller that catchesmlua::Result(the C ABI inffi, say) has it.- write_
if_ changed - Write
texttopathonly if the content differs. Returnstruewhen written. Used by the derive macros to emit.d.tlfiles without churning cargo’s fingerprints. - write_
if_ changed_ when write_if_changed, writing only whenwriteis set. Without it the answer is whether the file would change — what a dry run reports — and nothing on disk is touched.
Type Aliases§
- Coverage
Spans - 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 animplblock -> oneextern "C"wrapper perpub fn, the handle lifecycle, and the C header.- host_
module - Turn a plain
implblock into amlua::UserDataimpl, and write its Teal declaration (dts = "scripts/host.d.tl") when the macro expands, so a script seeshost:scale(p: Point, k: number): Pointandhost.Point. Change a Rust signature and the nextcargo buildfails inside the.tlthat relied on it: the declaration is rewritten first, andinclude_tl!/include_bundle!check against it. The breakdown ishtl_core::dts::host_decl, whichhtl dtsruns without building.
Derive Macros§
- Teal
Record - Declare a struct or enum on the Teal side and convert it both ways:
TealRecord::DECL(the.d.tltext),IntoLua/FromLuathat produce and accept exactly what it declares, andhtl_preload. What each Rust shape lowers to is the type table inhtl::dts, which is also whathtl dtsreads; the two cannot disagree.