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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
//! 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!` / `teal_types!` / `#[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 crates htl is built against are re-exported, so a host names the versions htl
//! links rather than adding its own: [`mlua`], [`mlua_isle`], [`serde`] (with `derive`)
//! and [`serde_json`]. A host with no `serde` dependency of its own derives through
//! `htl::serde` and writes `#[serde(crate = "htl::serde")]` on the type, because serde's
//! derive writes `::serde` paths; one that has the dependency changes nothing.
//!
//! 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 mlua-isle's executor, and a host with no async method should be built as
//! it was without it. With it, an `async fn` in a `#[host_module]` is a call Teal can
//! `await`, `Htl::run_async` / `Htl::run_blocking` run a program as a root on the
//! executor, and `htl.task` (`Htl::install_task_lib`) is the task library the
//! `async` / `await` syntax desugars to, with the channels, timers and `select` a loop in
//! Teal waits on and the typed host channels (`htl::task::RecvChannel` / `SendChannel`)
//! a host feeds it through; the README's Async section is the tour.
//!
//! # 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;