1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
//! 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]`.
//!
//! # Embedding
//!
//! ```rust,ignore
//! use htl::{Htl, TealRecord, host_module, include_tl, include_tl_bytes};
//!
//! #[derive(TealRecord, Clone)] // Teal record <-> plain table (IntoLua / FromLua)
//! pub struct Point { pub x: f64, pub y: f64 }
//!
//! pub struct Host { started: std::time::Instant }
//!
//! #[host_module(name = "host", dts = "scripts/host.d.tl", records = [Point])]
//! impl Host {
//! pub fn uptime_ms(&self) -> u64 { self.started.elapsed().as_millis() as u64 }
//! pub fn scale(&self, p: Point, k: f64) -> Point { Point { x: p.x * k, y: p.y * k } }
//! pub fn greet(name: &str) -> String { format!("hello, {name}") } // static
//! pub fn parse(s: &str) -> Result<i64, std::num::ParseIntError> { s.parse() } // Err -> Lua error
//! }
//!
//! const MAIN: &str = include_tl!("scripts/main.tl"); // checked at cargo build
//! const UTIL: &[u8] = include_tl_bytes!("scripts/util.tl"); // same, as stripped bytecode
//!
//! fn main() -> anyhow::Result<()> {
//! let h = Htl::new()?;
//! Host { started: std::time::Instant::now() }.htl_preload(&h)?;
//! h.preload_bytes("util", UTIL)?;
//! h.exec(MAIN, "@scripts/main.tl", &[])?; // frames read scripts/main.tl:<line>
//! Ok(())
//! }
//! ```
//!
//! `include_tl!` checks the file with the search path `htl check` gives it
//! ([`project::file_view`]); a crate whose Teal lives in `scripts/` says `[layout] source
//! = "scripts"`. A script that reads `arg[1]` needs [`Htl::set_arg`] before
//! [`Htl::exec`]. What crosses between Rust and Teal, and as what, is [`dts`]; what
//! holds the runtime to the declaration is [`teal::Strict`] and [`Htl::strict_strings`];
//! a host running Teal it did not write builds the `Lua` itself and hands it to
//! [`Htl::with_checker_lua`]. A crate that registers a module for other people's
//! projects ships the declaration ([`dep_dts`]); a crate whose Teal has dependencies
//! ships them as a patched copy ([`Htl::apply_project`]). A host that serves modules at
//! run time describes its directories once ([`model::Project::for_host`]) and derives the
//! checker and the run from that ([`pkg::TealResolver`]).
//!
//! The macros run the checker inside the proc macro, under `[profile.dev.build-override]`
//! — `htl new --embed` writes `opt-level = 3` into that section, and a host that predates
//! it adds the two lines by hand (one rebuild of the macro's dependencies, then every
//! build after); see `htl_macros`.
//!
//! # Features
//!
//! 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. A host that turns it on adds `crate-type = ["rlib",
//! "cdylib"]` (plus `"staticlib"` for Unity on iOS); `cargo build` then writes the
//! header, and the library exports the `<prefix>_*` functions and nothing else. 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.
//!
//! The `async` feature is off by default for the same reason: it turns on mlua's own
//! `async`, and a host with no async method should be built as it was without it.
//!
//! # Against an unpublished htl
//!
//! A consumer building against a checkout of htl before a change is published patches
//! all three crates in its `[patch.crates-io]`, not this one alone: `htl` re-exports
//! `htl-core`, and the proc macros in `htl-macros` run `htl-core` at expansion time, so
//! patching only `htl` builds two versions of the same code into one graph. Cargo keeps
//! the version `Cargo.lock` already resolved until `cargo update -p htl -p htl-core -p
//! htl-macros` is run once; the same command, with the block deleted, goes back.
//!
//! 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).
pub use *;
pub use ;
pub use c_export;