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].
use htl::{Htl, TealRecord, host_module, include_tl, include_tl_bytes};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. 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.
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
- 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. - 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.
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). - 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 — README “Build targets” has the table of what each one produces. - 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. - 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.
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 (patched_dirs).- 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 (undercargo_root) forcontract_resolvers(. No host crate (cargo_root= None) means a script-only project: nothing to enforce.- contract_
lints contractlint for one file: whenfilesits directly under the directory a contract holds (relative toroot, the directory holdinghtl.toml), check it against that contract statically. 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.- dependency_
dirs - The directories a
requirein the project atrootresolves installed deps from: the entry links under.htl/modulesand the parents oftarget_dircopies — whatHtl::apply_projectputs on the path, listed whether or not they exist yet, for the cache’s probes (cache::search_dirs). - 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. - 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. - module_
name root/foo/bar.tl->foo.bar,root/foo/init.tl->foo.- parent_
dir - Parent directory of a file,
.when the path has none. - patched_
dirs - The
patch_dirdeps belowroot: a dependency’s source taken into the tree, which the project edits and commits (htl pkg patch). - project_
skip_ dirs - Extra directories to skip below
root, whenrootis inside anmlua-pkg.tomlproject: where it installed its deps, and each copy atarget_dirdep put in the tree. - 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.
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