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! / #[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 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; the README’s Async section is the tour.
§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§
- 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.
- resolve
- Which file
require("<name>")resolves to, what that hides, and where each of them came from — the report behindhtl resolve. - 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.- 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_ bytes
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.
- Module
Candidate - One file
require(name)could have resolved to. SeeHtl::module_candidates. - 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.
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 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. - 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.