lua_types/version.rs
1//! `LuaVersion` — the single source of truth for which Lua language version a
2//! runtime instance speaks.
3//!
4//! This lives in `lua-types`, the lowest shared crate, so every layer above
5//! (parser, compiler, VM, stdlib, runtime) can name the version without a
6//! dependency cycle. Per the multi-version architecture decision
7//! (`specs/MULTIVERSION_ARCHITECTURE_DECISION.md` §4, §5), the version is a
8//! *backend selector* threaded from construction; it never appears in a public
9//! embedding-API type.
10
11/// The numeric model a version uses for Lua numbers.
12///
13/// This is the single sharpest behavioral axis across versions: 5.1/5.2 are
14/// float-only (one `number` type, every value an `f64`, no `math.type`), while
15/// 5.3/5.4/5.5 carry the dual integer/float subtype.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17pub enum NumberModel {
18 /// One `number` type; every numeric value is an `f64`. Lua 5.1/5.2.
19 FloatOnly,
20 /// Distinct integer (`i64`) and float (`f64`) subtypes. Lua 5.3/5.4/5.5.
21 Dual,
22}
23
24/// Which Lua language version a runtime instance speaks.
25///
26/// `Default` is [`LuaVersion::V54`] — the version this codebase currently
27/// implements end-to-end — so that `Lua::new()` and any other defaulted
28/// construction keeps the existing 5.4 behavior.
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
30#[non_exhaustive]
31pub enum LuaVersion {
32 /// Lua 5.1 — float-only, `fenv`-based globals. Deferred (separate core).
33 V51,
34 /// Lua 5.2 — float-only, modern `_ENV` globals. Deferred (separate core).
35 V52,
36 /// Lua 5.3 — dual subtype, modern `_ENV`. Deferred.
37 V53,
38 /// Lua 5.4 — the implemented baseline today.
39 V54,
40 /// Lua 5.5 — dual subtype, declared-globals scope model. Deferred.
41 V55,
42}
43
44impl Default for LuaVersion {
45 fn default() -> Self {
46 LuaVersion::V54
47 }
48}
49
50impl LuaVersion {
51 /// The family-level numeric model for this version.
52 pub fn number_model(self) -> NumberModel {
53 match self {
54 LuaVersion::V51 | LuaVersion::V52 => NumberModel::FloatOnly,
55 LuaVersion::V53 | LuaVersion::V54 | LuaVersion::V55 => NumberModel::Dual,
56 }
57 }
58
59 /// Whether this version has a real backend. The modern family (5.3/5.4/5.5)
60 /// and 5.2 (float-only + `_ENV`) are complete. 5.1 reuses the 5.2 float-only
61 /// core plus three faithful 5.1-specific axes:
62 /// - **fenv globals** — `getfenv`/`setfenv` (the per-function environment
63 /// model, Option B over the reused `_ENV` upvalue; `specs/followup/5.1-fenv.md`).
64 /// - **metamethod diffs** — `#t` never consults a table `__len`, no
65 /// `__pairs`/`__ipairs`, no `__gc` on tables (userdata only).
66 /// - **roster + syntax** — `unpack` is global (no `table.unpack`/`pack`/
67 /// `move`); `loadstring` + reader-only `load`; `table.getn`/`setn`(stub)/
68 /// `maxn`/`foreach`/`foreachi`; `module`/`package.seeall`/`package.loaders`
69 /// (no `package.searchers`); `string.gfind`; `math.log` 1-arg +
70 /// `log10`/`atan2`/`pow`/`mod` (no `math.type`); `gcinfo`; `newproxy`;
71 /// `xpcall`-no-extra-args; `coroutine.running` nil in main; no `bit32`/
72 /// `utf8`/`rawlen`; `goto`/labels/`//`/bitwise/`<const>`/`\x`-`\z` escapes
73 /// rejected (`goto` stays a valid identifier). See
74 /// `specs/followup/5.1-roster-syntax.md`. Documented divergences: the
75 /// `math.random` C-`rand()` sequence and `os.execute` raw-status byte are
76 /// host-dependent (contract matches; exact bytes do not).
77 pub fn is_supported(self) -> bool {
78 matches!(
79 self,
80 LuaVersion::V51
81 | LuaVersion::V52
82 | LuaVersion::V53
83 | LuaVersion::V54
84 | LuaVersion::V55
85 )
86 }
87
88 /// The `_VERSION` global string for this version (e.g. `"Lua 5.4"`).
89 pub fn version_str(self) -> &'static str {
90 match self {
91 LuaVersion::V51 => "Lua 5.1",
92 LuaVersion::V52 => "Lua 5.2",
93 LuaVersion::V53 => "Lua 5.3",
94 LuaVersion::V54 => "Lua 5.4",
95 LuaVersion::V55 => "Lua 5.5",
96 }
97 }
98
99 /// The `LUAC_VERSION` byte written into a `luac`/`string.dump` header for
100 /// this version. Upstream encodes the version as `(major << 4) | minor`,
101 /// e.g. 5.4 → `0x54`.
102 pub fn luac_version_byte(self) -> u8 {
103 match self {
104 LuaVersion::V51 => 0x51,
105 LuaVersion::V52 => 0x52,
106 LuaVersion::V53 => 0x53,
107 LuaVersion::V54 => 0x54,
108 LuaVersion::V55 => 0x55,
109 }
110 }
111}
112
113#[cfg(test)]
114mod tests {
115 use super::*;
116
117 #[test]
118 fn default_is_v54() {
119 assert_eq!(LuaVersion::default(), LuaVersion::V54);
120 }
121
122 #[test]
123 fn number_model_split() {
124 assert_eq!(LuaVersion::V51.number_model(), NumberModel::FloatOnly);
125 assert_eq!(LuaVersion::V52.number_model(), NumberModel::FloatOnly);
126 assert_eq!(LuaVersion::V53.number_model(), NumberModel::Dual);
127 assert_eq!(LuaVersion::V54.number_model(), NumberModel::Dual);
128 assert_eq!(LuaVersion::V55.number_model(), NumberModel::Dual);
129 }
130
131 #[test]
132 fn version_str_and_byte() {
133 assert_eq!(LuaVersion::V54.version_str(), "Lua 5.4");
134 assert_eq!(LuaVersion::V54.luac_version_byte(), 0x54);
135 assert_eq!(LuaVersion::V53.version_str(), "Lua 5.3");
136 assert_eq!(LuaVersion::V53.luac_version_byte(), 0x53);
137 }
138}
139
140// ──────────────────────────────────────────────────────────────────────────
141// PORT STATUS
142// source: (foundation — multi-version seam, not ported from .c)
143// target_crate: lua-types
144// confidence: high
145// todos: 0
146// port_notes: 0
147// unsafe_blocks: 0
148// notes: LuaVersion + NumberModel. Default = V54 preserves the
149// existing single-version behavior. V51-V55 complete; V51
150// reuses the 5.2 float-only core plus the fenv-globals,
151// metamethod-diff, and roster/syntax axes (all V51-gated).
152// ──────────────────────────────────────────────────────────────────────────