htl_core/teal.rs
1//! Rust <-> Teal type bridge used by `#[derive(TealRecord)]` and `#[host_module]`.
2//!
3//! The macros map Rust types to Teal type names *syntactically* at expansion time
4//! (`f64 -> number`, `String -> string`, `Vec<T> -> {T}`, ...). This module holds the
5//! runtime-side traits the generated code implements, and the functions it calls:
6//! [`field_error`] and its kin name a value that does not fit, and [`serde_field`] is what
7//! a `#[teal(serde)]` field crosses through (htl's `serde` feature).
8
9/// A Rust type mirrored as a Teal declaration: a struct as a `record` (plain table with
10/// named fields), a newtype as a `type` alias, an enum as an `enum` of its variant names
11/// or, when a variant carries data, as a union of `where`-discriminated records. The
12/// lowering is in `htl_core::dts`.
13pub trait TealRecord {
14 /// Teal type name (also the module name of its `.d.tl`).
15 const NAME: &'static str;
16 /// Full `.d.tl` text: `local record NAME ... end return NAME`, or the `enum` /
17 /// `type` form.
18 const DECL: &'static str;
19}
20
21/// A struct record's fields, written into and read out of a table the caller holds — what
22/// `#[serde(flatten)]` is built on. `#[derive(TealRecord)]` implements it for every struct
23/// with named fields (not for an enum or an alias), and its own `IntoLua` / `FromLua` are
24/// this around a table of their own; a struct that flattens another calls the inner type's
25/// pair on *its* table, so the inner fields sit beside its own, as `serde_json` puts them.
26///
27/// `TealRecord` itself stays two constants: these are only meaningful for a record, and a
28/// struct's `DECL` cannot carry another type's fields at compile time (the declaration
29/// side reads the flattened struct from source instead, `htl::dts`). Not meant to be
30/// implemented by hand: the derive's declaration and this conversion are one reading.
31pub trait TealFields: Sized {
32 /// Set each field's key in `t`, as the record's `into_lua` does (a skipped field, or
33 /// one whose `skip_serializing_if` holds, is left out). A failure (a `#[teal(serde)]`
34 /// field's) is reported as `path.field`, `path` named as `read_fields` names it: the
35 /// type's own name from its `into_lua`, the outer record's when it is flattened, so a
36 /// flattened field is named by the same key whichever way it crosses. (A record nested
37 /// under a key, not flattened, still reports a write failure under its own name.)
38 fn write_fields(self, t: &mlua::Table, lua: &mlua::Lua, path: &str) -> mlua::Result<()>;
39 /// Read each field from `t`, reporting a failure as `path.field` — `path` is the
40 /// record the table is declared as: the type's own name from its `from_lua`, the outer
41 /// record's when it is flattened (the Teal side has no level for the inner struct, so a
42 /// `FieldError` names the key where it sits: `Outer.innerField`).
43 fn read_fields(t: &mlua::Table, lua: &mlua::Lua, path: &str) -> mlua::Result<Self>;
44}
45
46/// Why a value coming back from Lua did not fit a `#[derive(TealRecord)]` struct.
47///
48/// `FromLua` is the only place the two sides of a record are compared — the `.d.tl` is
49/// generated from Rust, so what a host *offers* is checked at build time, while what it
50/// *receives* is checked when a value crosses. This carries enough to act on: which
51/// record, which field, the Teal type declared for it, and what arrived instead.
52///
53/// ```text
54/// Outcome.cause: expected string, got nil
55/// Outcome.depth: expected integer, got string
56/// ```
57///
58/// A record inside a record extends the path rather than nesting the message, so the
59/// innermost field is what the reader sees: `Recording.outcome.cause`.
60#[derive(Debug, Clone, PartialEq, Eq)]
61pub struct FieldError {
62 /// `Record.field`, one segment per level of nesting.
63 pub path: String,
64 /// The Teal type the record declares for the field.
65 pub expected: String,
66 /// The Lua type that arrived: `nil`, `string`, `table`, ...
67 pub got: String,
68}
69
70impl std::fmt::Display for FieldError {
71 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
72 write!(
73 f,
74 "{}: expected {}, got {}",
75 self.path, self.expected, self.got
76 )
77 }
78}
79
80impl std::error::Error for FieldError {}
81
82/// Name the record and the field a conversion failed on.
83///
84/// Called by the `FromLua` that `#[derive(TealRecord)]` generates, once per field that
85/// fails. `cause` is what the field's own conversion returned, and is only replaced when
86/// it says nothing the caller does not already know — a plain type mismatch. Anything
87/// else (a host function's own error, a borrow failure) is kept and given the field as
88/// context, because it carries more than this can reconstruct.
89pub fn field_error(
90 record: &str,
91 field: &str,
92 expected: &str,
93 got: &str,
94 cause: mlua::Error,
95) -> mlua::Error {
96 located(format!("{record}.{field}"), expected, got, cause)
97}
98
99/// Name the type a whole-value conversion failed on: a newtype (`type N = T` on the
100/// Teal side) whose inner conversion refused what arrived. The alias is what the Teal
101/// side declared, so it is the name the reader looks for: a `FieldError` from inside
102/// (the inner type is a record, an enum, or another alias) is re-rooted at the alias —
103/// `Label.y: expected number, got nil`, `Wrap: expected one of ..` — and a plain
104/// mismatch becomes `N: expected T, got <type>`.
105pub fn value_error(name: &str, expected: &str, got: &str, cause: mlua::Error) -> mlua::Error {
106 located(name.to_string(), expected, got, cause)
107}
108
109/// The one policy behind `field_error` and `value_error`, given the location the caller
110/// stands at (`Record.field`, `Enum.Variant.field`, or a bare type name):
111///
112/// - a `FieldError` from inside is re-rooted here: the head of its path is the inner
113/// type's own name, which this location already states, so it is dropped and the rest
114/// (if any — an enum or alias reports with a bare name) appended;
115/// - a plain type mismatch becomes a `FieldError` at this location;
116/// - anything else (a host function's own error, a borrow failure) keeps its message
117/// with the location as context, because it carries more than this can reconstruct.
118fn located(path: String, expected: &str, got: &str, cause: mlua::Error) -> mlua::Error {
119 if let Some(inner) = cause.downcast_ref::<FieldError>() {
120 let path = match inner.path.split_once('.') {
121 Some((_, rest)) => format!("{path}.{rest}"),
122 None => path,
123 };
124 return mlua::Error::external(FieldError {
125 path,
126 expected: inner.expected.clone(),
127 got: inner.got.clone(),
128 });
129 }
130 if !matches!(cause, mlua::Error::FromLuaConversionError { .. }) {
131 return mlua::ErrorContext::context(cause, path);
132 }
133 mlua::Error::external(FieldError {
134 path,
135 expected: expected.to_string(),
136 got: got.to_string(),
137 })
138}
139
140/// Name the enum a value did not belong to, listing what it accepts:
141/// `Mode: expected one of "Fast", "Careful", got "fst"`. `got` is the offending string
142/// in quotes, or the Lua type name when it was not a string (or, for a data-carrying
143/// enum, not a table). Reported as a `FieldError` so an enum inside a record extends the
144/// record's path the way a nested record does.
145pub fn enum_error(name: &str, variants: &[&str], got: &str) -> mlua::Error {
146 let list: Vec<String> = variants.iter().map(|v| format!("\"{v}\"")).collect();
147 mlua::Error::external(FieldError {
148 path: name.to_string(),
149 expected: format!("one of {}", list.join(", ")),
150 got: got.to_string(),
151 })
152}
153
154/// Name the untagged union a value did not belong to, listing the Teal types it is a union
155/// of: `Shape: expected one of string, number, Shape_Rect, got boolean`. An untagged
156/// enum's variants carry no word to quote; what tells them apart is the Lua type, so that
157/// is what is listed and what `got` names.
158pub fn union_error(name: &str, members: &[&str], got: &str) -> mlua::Error {
159 mlua::Error::external(FieldError {
160 path: name.to_string(),
161 expected: format!("one of {}", members.join(", ")),
162 got: got.to_string(),
163 })
164}
165
166/// A host parameter that takes the Lua kind its Teal type names, and converts nothing.
167///
168/// mlua's `FromLua` for `i64` accepts a Lua string and coerces it (`"10"` arrives as
169/// `10`), and its `FromLua` for `String` accepts a number and formats it. The `.d.tl`
170/// that `#[host_module]` writes says `integer` and `string`, and checked Teal cannot pass
171/// the other kind — but a value from past a cast or a `load`, which the checker did not
172/// see, can, and the host has no way to tell the two apart once mlua has converted.
173/// `Strict<T>` is the parameter type that keeps the runtime to the declaration: an
174/// integer is `Value::Integer`, or a `Value::Number` with no fraction (as
175/// `math.tointeger` reads it); a float is either number kind; `bool` is
176/// `Value::Boolean`; `String` is `Value::String`. Anything else is a conversion error
177/// naming what arrived — `error converting Lua string to integer` — the same shape mlua
178/// reports, so a caller reading errors sees one kind of message.
179///
180/// ```ignore
181/// #[host_module(name = "api")]
182/// impl Api {
183/// pub fn take(&self, n: Strict<i64>) -> i64 { *n } // `take: function(self: api, n: integer): integer`
184/// }
185/// ```
186///
187/// The declaration is the inner type's — `Strict<i64>` is `integer` in the `.d.tl` — since
188/// it already said that; this only holds the runtime to it. Derefs to `T`, and goes back
189/// to Lua as `T` would, so a return type may be `Strict<T>` as well, though there it
190/// adds nothing.
191///
192/// The other two layers of the same question are the checker, which holds checked Teal,
193/// and [`Htl::strict_strings`](crate::Htl::strict_strings), which holds the program state
194/// where arithmetic on a string would otherwise convert.
195#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
196pub struct Strict<T>(pub T);
197
198impl<T> Strict<T> {
199 /// The value, out of the wrapper.
200 pub fn into_inner(self) -> T {
201 self.0
202 }
203}
204
205impl<T> std::ops::Deref for Strict<T> {
206 type Target = T;
207 fn deref(&self) -> &T {
208 &self.0
209 }
210}
211
212impl<T> std::ops::DerefMut for Strict<T> {
213 fn deref_mut(&mut self) -> &mut T {
214 &mut self.0
215 }
216}
217
218impl<T> From<T> for Strict<T> {
219 fn from(v: T) -> Self {
220 Strict(v)
221 }
222}
223
224/// What [`Strict<T>`] accepts for a `T`: the Lua kind, read without conversion. Sealed;
225/// the integers, `f32` / `f64`, `bool` and `String`.
226pub trait StrictKind: Sized + private::Sealed {
227 /// The Teal type the `.d.tl` declares for `T`, for the error message.
228 const TEAL: &'static str;
229 /// `Some` when `v` is the kind `T` names, `None` for every other kind.
230 fn from_value(v: &mlua::Value) -> Option<Self>;
231}
232
233mod private {
234 pub trait Sealed {}
235}
236
237macro_rules! strict_int {
238 ($($t:ty),*) => {$(
239 impl private::Sealed for $t {}
240 impl StrictKind for $t {
241 const TEAL: &'static str = "integer";
242 fn from_value(v: &mlua::Value) -> Option<Self> {
243 match *v {
244 mlua::Value::Integer(i) => <$t>::try_from(i).ok(),
245 // What `math.tointeger` accepts: a float with no fraction. Lua's own
246 // `3.0 == 3`, and a JSON decoder hands back a float for `3.0`.
247 mlua::Value::Number(n) if n.fract() == 0.0 && n.is_finite() => {
248 let i = n as i64;
249 (i as f64 == n).then(|| <$t>::try_from(i).ok()).flatten()
250 }
251 _ => None,
252 }
253 }
254 }
255 )*};
256}
257strict_int!(
258 i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize
259);
260
261macro_rules! strict_float {
262 ($($t:ty),*) => {$(
263 impl private::Sealed for $t {}
264 impl StrictKind for $t {
265 const TEAL: &'static str = "number";
266 fn from_value(v: &mlua::Value) -> Option<Self> {
267 match *v {
268 mlua::Value::Integer(i) => Some(i as $t),
269 mlua::Value::Number(n) => Some(n as $t),
270 _ => None,
271 }
272 }
273 }
274 )*};
275}
276strict_float!(f32, f64);
277
278impl private::Sealed for bool {}
279impl StrictKind for bool {
280 const TEAL: &'static str = "boolean";
281 fn from_value(v: &mlua::Value) -> Option<Self> {
282 match *v {
283 mlua::Value::Boolean(b) => Some(b),
284 _ => None,
285 }
286 }
287}
288
289impl private::Sealed for String {}
290impl StrictKind for String {
291 const TEAL: &'static str = "string";
292 fn from_value(v: &mlua::Value) -> Option<Self> {
293 match v {
294 mlua::Value::String(s) => s.to_str().ok().map(|s| s.to_owned()),
295 _ => None,
296 }
297 }
298}
299
300impl<T: StrictKind> mlua::FromLua for Strict<T> {
301 fn from_lua(value: mlua::Value, _lua: &mlua::Lua) -> mlua::Result<Self> {
302 T::from_value(&value)
303 .map(Strict)
304 .ok_or_else(|| mlua::Error::FromLuaConversionError {
305 from: value.type_name(),
306 to: T::TEAL.to_string(),
307 message: Some(format!(
308 "a Strict parameter takes a Lua {} and converts nothing",
309 T::TEAL
310 )),
311 })
312 }
313}
314
315impl<T: mlua::IntoLua> mlua::IntoLua for Strict<T> {
316 fn into_lua(self, lua: &mlua::Lua) -> mlua::Result<mlua::Value> {
317 self.0.into_lua(lua)
318 }
319}
320
321/// A Rust type exposed to Teal as a userdata module via `#[host_module]`.
322pub trait HostModule {
323 /// Module name used in `require("...")`.
324 const MODULE: &'static str;
325 /// Full `.d.tl` text for the module.
326 const DECL: &'static str;
327}
328
329/// What `#[teal(serde)]` on a `#[derive(TealRecord)]` field crosses through: mlua's serde
330/// (`LuaSerdeExt::to_value_with` / `from_value_with`), with options htl fixes rather than
331/// mlua's defaults. The derive calls these; they are public only so that it can.
332///
333/// It exists under htl's `serde` feature (on with `std`, which is on by default). Without
334/// it the module holds the same two functions bounded by a trait nothing implements,
335/// `EnableHtlFeatureSerde`, so a field that says `#[teal(serde)]` fails to compile with an
336/// error that names the feature instead of one about a missing function.
337///
338/// The options, and why:
339///
340/// - writing: `set_array_metatable` on (a sequence carries mlua's array metatable, so an
341/// empty one reads back as a sequence); `serialize_none_to_null` off (a `None` is `nil`,
342/// so an absent field is an absent key, as a Teal record field is nilable) — on only for
343/// a field whose Rust type holds an `Option` inside a sequence (`Vec<Option<T>>`), where
344/// `nil` would leave a hole a Lua sequence cannot hold, and the derive asks for it
345/// (`none_to_null`); `serialize_unit_to_null` off; `detect_serde_json_arbitrary_precision`
346/// on (a `serde_json::Number` crosses as a number). A value that serializes to the null
347/// marker at the top (`None` under `none_to_null`) is written as `nil`: the field is
348/// absent, not a marker.
349/// - reading: `deny_unsupported_types` and `deny_recursive_tables` on (a function or a
350/// cycle is an error, not dropped); `encode_empty_tables_as_array` from the field's Rust
351/// type (`empty_as_array`, decided by the derive: a sequence type — `Vec`, `VecDeque`,
352/// `HashSet`, `BTreeSet`, a slice or an array, through `Option` / `Box` — reads an empty
353/// table as an empty sequence, anything else as an empty map). A serde type that holds
354/// both a sequence and a map inside cannot be told apart on an empty table — the option
355/// is one per conversion, and the derive sees only the field's type as written: that is
356/// the residue of mlua's option, and why the outermost type decides.
357/// `detect_mixed_tables` stays off: in mlua 0.12 it overrides `encode_empty_tables_as_array`
358/// (an empty table is always an array under it), and it only reaches values serde reads
359/// untyped (`serde_json::Value`) — a typed `Vec` reads a table's sequence part and ignores
360/// every other key. So htl refuses a mixed table itself, before serde reads: any table in
361/// the value with a sequence part (`#t > 0`) and a key that is not one of `1..#t` — a
362/// string key beside the sequence, or a hole.
363///
364/// A failure is a [`FieldError`] at the field (`Rec.opts: expected {string: any}, got table
365/// (a mixed table at `list`: ...)`), so a record nested in another extends the path as any
366/// field's does.
367pub mod serde_field {
368 #[cfg(not(feature = "serde"))]
369 use mlua::{Lua, Value};
370
371 /// Implemented by nothing: the bound the two functions carry when htl is built without
372 /// its `serde` feature, so `#[teal(serde)]` fails to compile naming the feature.
373 #[cfg(not(feature = "serde"))]
374 #[diagnostic::on_unimplemented(
375 message = "`#[teal(serde)]` crosses a field through serde, which needs htl's `serde` feature",
376 label = "this field says `#[teal(serde)]`",
377 note = "enable it: `htl = {{ version = \"..\", features = [\"serde\"] }}` (the default `std` feature turns it on too)"
378 )]
379 pub trait EnableHtlFeatureSerde {}
380
381 /// Without the `serde` feature: never callable, see [`EnableHtlFeatureSerde`].
382 #[cfg(not(feature = "serde"))]
383 pub fn to_lua<T: EnableHtlFeatureSerde + ?Sized>(
384 _lua: &Lua,
385 _value: &T,
386 _record: &str,
387 _field: &str,
388 _none_to_null: bool,
389 ) -> mlua::Result<Value> {
390 unreachable!("no type implements EnableHtlFeatureSerde")
391 }
392
393 /// Without the `serde` feature: never callable, see [`EnableHtlFeatureSerde`].
394 #[cfg(not(feature = "serde"))]
395 pub fn from_lua<T: EnableHtlFeatureSerde>(
396 _lua: &Lua,
397 _value: Value,
398 _record: &str,
399 _field: &str,
400 _expected: &str,
401 _empty_as_array: bool,
402 ) -> mlua::Result<T> {
403 unreachable!("no type implements EnableHtlFeatureSerde")
404 }
405
406 #[cfg(feature = "serde")]
407 pub use imp::{from_lua, to_lua};
408
409 #[cfg(feature = "serde")]
410 mod imp {
411 use super::super::FieldError;
412 use mlua::{ErrorContext, Lua, LuaSerdeExt, Table, Value};
413
414 /// Field `record.field` -> Lua, through its `Serialize`, with htl's options.
415 pub fn to_lua<T: serde::Serialize + ?Sized>(
416 lua: &Lua,
417 value: &T,
418 record: &str,
419 field: &str,
420 none_to_null: bool,
421 ) -> mlua::Result<Value> {
422 let opts = mlua::serde::ser::Options::new()
423 .set_array_metatable(true)
424 .serialize_none_to_null(none_to_null)
425 .serialize_unit_to_null(false)
426 .detect_serde_json_arbitrary_precision(true);
427 let v = lua
428 .to_value_with(value, opts)
429 .context(format!("{record}.{field}"))?;
430 Ok(match v {
431 Value::LightUserData(ud) if ud.0.is_null() => Value::Nil,
432 v => v,
433 })
434 }
435
436 /// Lua -> field `record.field` (declared `expected`), through its `Deserialize`,
437 /// with htl's options; a mixed table anywhere in the value is refused first.
438 pub fn from_lua<T: serde::de::DeserializeOwned>(
439 lua: &Lua,
440 value: Value,
441 record: &str,
442 field: &str,
443 expected: &str,
444 empty_as_array: bool,
445 ) -> mlua::Result<T> {
446 let fail = |got: String| {
447 mlua::Error::external(FieldError {
448 path: format!("{record}.{field}"),
449 expected: expected.to_string(),
450 got,
451 })
452 };
453 let got = value.type_name();
454 if let Value::Table(t) = &value {
455 let mut seen = Vec::new();
456 if let Some(why) = mixed(t, "", &mut seen)? {
457 return Err(fail(format!("{got} ({why})")));
458 }
459 }
460 let opts = mlua::serde::de::Options::new()
461 .deny_unsupported_types(true)
462 .deny_recursive_tables(true)
463 .detect_mixed_tables(false)
464 .encode_empty_tables_as_array(empty_as_array);
465 lua.from_value_with(value, opts).map_err(|e| {
466 let msg = match &e {
467 mlua::Error::DeserializeError(m) => m.clone(),
468 other => other.to_string(),
469 };
470 fail(format!("{got} ({msg})"))
471 })
472 }
473
474 /// The first table in `t` (itself, then its values, depth first) with a sequence
475 /// part and a key outside it, described with the keys that lead to it from the
476 /// field; `None` when there is none. `seen` keeps a cycle from recursing (serde's
477 /// own `deny_recursive_tables` reports it after).
478 fn mixed(t: &Table, at: &str, seen: &mut Vec<usize>) -> mlua::Result<Option<String>> {
479 let ptr = t.to_pointer() as usize;
480 if seen.contains(&ptr) {
481 return Ok(None);
482 }
483 seen.push(ptr);
484 let n = t.raw_len();
485 let mut inner = Vec::new();
486 let mut in_seq_count = 0;
487 for pair in t.clone().pairs::<Value, Value>() {
488 let (k, v) = pair?;
489 if n > 0 {
490 let in_seq = match k {
491 Value::Integer(i) => i >= 1 && (i as usize) <= n,
492 _ => false,
493 };
494 in_seq_count += usize::from(in_seq);
495 if !in_seq {
496 let key = match &k {
497 Value::String(s) => format!("{:?}", s.to_string_lossy()),
498 Value::Integer(i) => i.to_string(),
499 other => other.type_name().to_string(),
500 };
501 let place = if at.is_empty() {
502 String::new()
503 } else {
504 format!(" at `{at}`")
505 };
506 return Ok(Some(format!(
507 "a mixed table{place}: a sequence of {n} and the key {key}; a Lua \
508 table crosses as a sequence or as a map, not both, and not with holes"
509 )));
510 }
511 }
512 if let Value::Table(c) = v {
513 let seg = match &k {
514 Value::String(s) => s.to_string_lossy().to_string(),
515 Value::Integer(i) => format!("[{i}]"),
516 other => format!("[{}]", other.type_name()),
517 };
518 let path = if at.is_empty() {
519 seg
520 } else if seg.starts_with('[') {
521 format!("{at}{seg}")
522 } else {
523 format!("{at}.{seg}")
524 };
525 inner.push((c, path));
526 }
527 }
528 if in_seq_count < n {
529 let place = if at.is_empty() {
530 String::new()
531 } else {
532 format!(" at `{at}`")
533 };
534 return Ok(Some(format!(
535 "a sequence with holes{place}: {in_seq_count} values under the length {n}; a \
536 Lua sequence cannot hold nil"
537 )));
538 }
539 for (c, path) in inner {
540 if let Some(why) = mixed(&c, &path, seen)? {
541 return Ok(Some(why));
542 }
543 }
544 Ok(None)
545 }
546 }
547}