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! / #[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 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
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.
resolve
Which file require("<name>") resolves to, what that hides, and where each of them came from — the report behind htl 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 build links.

Macros§

include_bundle
include_bundle!("src/main.tl", host = ["host"], extra = ["modkit"], payload = "source", debug = true)
include_tl
include_tl_bytes

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).
Htl
An mlua state with the Teal compiler loaded.
ModuleCandidate
One file require(name) could have resolved to. See Htl::module_candidates.
Replaced
What Htl::replace_bundle did, so a host can say it rather than guess.
RequireSite
One literal require call in a checked file.

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 — README “Build targets” has the table of what each one produces.
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.
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.

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 .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 (patched_dirs).
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 (under cargo_root) 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 file sits directly under the directory a contract holds (relative to root, the directory holding htl.toml), check it against that contract statically. 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.
dependency_dirs
The directories a require in the project at root resolves installed deps from: the entry links under .htl/modules and the parents of target_dir copies — what Htl::apply_project puts 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’s stack traceback: block when the error carries one.
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.
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_dir deps below root: 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, when root is inside an mlua-pkg.toml project: where it installed its deps, and each copy a target_dir dep 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 outside infos are 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’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.

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

Derive Macros§

TealRecord