Expand description
htl: Teal, hidden.
Embeds the Teal compiler (tl.lua) into an mlua state so .tl sources can be
type-checked, generated and executed without any external toolchain.
Htl::check/Htl::gen_lua: type-check and generate Lua from a.tlfileHtl::install_searcher: strictrequirefor.tl(type errors abort the require)Htl::preload: register generated Lua (e.g. frominclude_tl!) under a module namebundle: stripped-bytecode bundles produced byhtl build
A project — its own code, its dependencies, the declarations crates ship to it and the
directories it accepts modules from — is described by the model module (compiled
with the pkg and dts features): one Module per unit that owns a namespace, each
with its source, test and declaration roots, and one rule for the name a file answers
to.
Three libraries ship inside the binary rather than on a project’s search path, and all
are installed the same way — a package.preload entry for the run, a .d.tl under
lib_dir for the checker: htl.test (Htl::install_test_lib, describe / it /
expect); with the std feature, std.* — mlua-batteries’ modules under the
namespace that crate leaves to its host; and with the async feature, htl.task —
tasks a program on the executor spawns and awaits (spawn / await / <close>,
mlua-isle’s task library under a declaration; the task module says what it promises).
The methods that install the last two are named and linked below when the feature that
compiles them is on; a link to an item that is not compiled is a broken one.
A value the host puts into the Lua state reaches .tl code with a type in one of
three ways, and the first is the one to reach for:
#[host_module]on the Rust side (thehtl-macroscrate): the host registers a module inpackage.preloadand the macro writes its.d.tl, so the.tlsiderequires it like any module and the checker reads the declaration the build keeps current.- When the Rust side stays as it is and sets the value as a global
(
lua.globals().set("knl", ..)): one.tlmodule that reads it from_Gand returns it —— so nolocal record Knl open: function(): Session end local knl = (_G as {string:any})["knl"] as Knl return knlglobalis declared anywhere, the checker sees an ordinary module, and the one line that reads the state is that one. Four files over such a module check clean in either order, andhtl runwith the value set finds it. - A
globaldeclaration in a module, a.d.tlor a.tl. It is visible in the files that require the declaring module, directly or through a chain of requires, and nowhere else: the run checks each file in an environment of its own, and the checked-module store hands a module’s globals to the environments that require it. The global namespace is one per project, so a second declaration of the name at another site isglobal-redeclaration, whether or not the types agree (the checker’s owncannot redeclare global with a different typeis raised only where one environment walks both, which depends on the walk order; the lint does not).no-globalis the lint that asks for 1 or 2 instead.
Re-exports§
pub use build_target::BuildTarget;pub use diagnostic::Diagnostic;pub use diagnostic::Severity;pub use teal::Strict;pub use mlua;pub use mlua_isle;pub use serde;pub use serde_json;
Modules§
- 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).
- 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.- diagnostic
- What a check reported, as a value rather than as a line of text.
- 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.
- 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. - 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 and [crate::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. - shapes
- The run-time shape of each record and enum a file declares, lowered from what the
checker knows of the file (
htl shapes). - 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). - verdict
- Whether a run fails: the findings of the run, and the policy that judges them.
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). - 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. - 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. - 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).
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_
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.