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.

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:

  1. #[host_module] on the Rust side (the htl-macros crate): the host registers a module in package.preload and the macro writes its .d.tl, so the .tl side requires it like any module and the checker reads the declaration the build keeps current.
  2. When the Rust side stays as it is and sets the value as a global (lua.globals().set("knl", ..)): one .tl module that reads it from _G and returns it —
    local record Knl
       open: function(): Session
    end
    local knl = (_G as {string:any})["knl"] as Knl
    return knl
    — so no global is 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, and htl run with the value set finds it.
  3. A global declaration in a module, a .d.tl or 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 is global-redeclaration, whether or not the types agree (the checker’s own cannot redeclare global with a different type is raised only where one environment walks both, which depends on the walk order; the lint does not). no-global is 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 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.
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 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.
registry
The seam a binary adds its own require-able libraries through, wherever this crate builds an Htl for its own use rather than the binary’s: crate::testing’s per-test state and [crate::project::checker]. Both already call Htl::install_std and Htl::install_task_lib for 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§

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).
GlobalSite
One global declaration a check saw (see CheckInfo::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.
MarkerSite
One marker the census found on a declaration (see CheckInfo::markers).
ModuleCandidate
One file require(name) could have resolved to. See Htl::module_candidates.
RecordSite
One table literal or as cast a check found typed as a declared record (see CheckInfo::record_sites).
Replaced
What Htl::replace_bundle did, so a host can say it rather than guess.
RequireSite
One literal require call in a checked file.
UnmarkedSealed
One record unmarked_sealeds found a candidate for ---@sealed (#304).
UnmarkedStruct
One record unmarked_structs found a candidate for ---@struct (#304).

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.
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 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: 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 _VERSION reader, 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 .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 — the project model’s Project::not_walked.
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 — src/, examples/, tests/ and benches/ under cargo_root, a directory that is absent skipped — 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 a directory a contract holds serves file as a module (contract::held_name: anywhere under it, by the name require writes — foo for foo/init.tl, sub.x for sub/x.tl), check it against that contract statically, as the host’s resolver for the directory holds it at run time. root is the directory holding htl.toml. 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.
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.
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_global in the vendored compiler returns without a word), so two .d.tl that both declare a name were read as one and nobody was told — the gap duplicate-declaration closes for two declarations of one module, closed here for one global.
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.
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 outside infos are 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 ---@sealed row 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 ---@struct row 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’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.
write_if_changed_when
write_if_changed, writing only when write is set. Without it the answer is whether the file would change — what a dry run reports — and nothing on disk is touched.

Type Aliases§

CoverageSpans
What one parse gives a coverage report: the statement ranges, and the functions those ranges sit in. See Htl::coverage_spans.