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 | LuaVersion::V52 | LuaVersion::V53 | LuaVersion::V54 | LuaVersion::V55
81 )
82 }
83
84 /// The `_VERSION` global string for this version (e.g. `"Lua 5.4"`).
85 pub fn version_str(self) -> &'static str {
86 match self {
87 LuaVersion::V51 => "Lua 5.1",
88 LuaVersion::V52 => "Lua 5.2",
89 LuaVersion::V53 => "Lua 5.3",
90 LuaVersion::V54 => "Lua 5.4",
91 LuaVersion::V55 => "Lua 5.5",
92 }
93 }
94
95 /// The `LUAC_VERSION` byte written into a `luac`/`string.dump` header for
96 /// this version. Upstream encodes the version as `(major << 4) | minor`,
97 /// e.g. 5.4 → `0x54`.
98 pub fn luac_version_byte(self) -> u8 {
99 match self {
100 LuaVersion::V51 => 0x51,
101 LuaVersion::V52 => 0x52,
102 LuaVersion::V53 => 0x53,
103 LuaVersion::V54 => 0x54,
104 LuaVersion::V55 => 0x55,
105 }
106 }
107}
108
109#[cfg(test)]
110mod tests {
111 use super::*;
112
113 #[test]
114 fn default_is_v54() {
115 assert_eq!(LuaVersion::default(), LuaVersion::V54);
116 }
117
118 #[test]
119 fn number_model_split() {
120 assert_eq!(LuaVersion::V51.number_model(), NumberModel::FloatOnly);
121 assert_eq!(LuaVersion::V52.number_model(), NumberModel::FloatOnly);
122 assert_eq!(LuaVersion::V53.number_model(), NumberModel::Dual);
123 assert_eq!(LuaVersion::V54.number_model(), NumberModel::Dual);
124 assert_eq!(LuaVersion::V55.number_model(), NumberModel::Dual);
125 }
126
127 #[test]
128 fn version_str_and_byte() {
129 assert_eq!(LuaVersion::V54.version_str(), "Lua 5.4");
130 assert_eq!(LuaVersion::V54.luac_version_byte(), 0x54);
131 assert_eq!(LuaVersion::V53.version_str(), "Lua 5.3");
132 assert_eq!(LuaVersion::V53.luac_version_byte(), 0x53);
133 }
134}
135
136// ──────────────────────────────────────────────────────────────────────────
137// PORT STATUS
138// source: (foundation — multi-version seam, not ported from .c)
139// target_crate: lua-types
140// confidence: high
141// todos: 0
142// port_notes: 0
143// unsafe_blocks: 0
144// notes: LuaVersion + NumberModel. Default = V54 preserves the
145// existing single-version behavior. V51-V55 complete; V51
146// reuses the 5.2 float-only core plus the fenv-globals,
147// metamethod-diff, and roster/syntax axes (all V51-gated).
148// ──────────────────────────────────────────────────────────────────────────