Skip to main content

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}