Skip to main content

Crate htl_core

Crate htl_core 

Source
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.

Two libraries ship inside the binary rather than on a project’s search path, and both 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) and, with the std feature, std.* — mlua-batteries’ modules under the namespace that crate leaves to its host. The method that installs them is named and linked below when the feature that compiles it is on; a link to an item that is not compiled is a broken one.

Re-exports§

pub use build_target::BuildTarget;
pub use diagnostic::Diagnostic;
pub use diagnostic::Severity;
pub use mlua;

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 and include_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 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.
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.
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.

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).
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.
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.

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.