feat(lua): backport 5.1 leveled long brackets; fix top-level vararg fallback

Adversarial testing of the transpiler surfaced two gaps beyond PR 28:

- Leveled long brackets ([=[ ]=], [==[ ]==]) are the one 5.1 syntax
  construct still missing. The 5.0 engine lexer has no =-level handling
  (verified in FUN_006ff610), so they fail to compile. A new source-walking
  pre-pass rewrites a leveled long string to [[body]] when the body is safe
  (byte-exact, keeps the leading-newline strip) or to a quoted literal with
  \-newline continuations otherwise, and blanks leveled long comments to
  spaces. Line numbers preserved. Gated by the new LongBrackets toggle.

- Top-level ... outside the addon file funnel (RunScript, XML <OnLoad>,
  loadstring) expanded to unpack(arg) and threw on nil arg, where 5.1
  yields nothing. Non-addon vararg chunks now get a local arg={n=0}
  fallback.

Adds a /capitranspile self-test suite (19 cases, all passing in-game) and
updates docs/API.md (also fixing a stale limits note that described plain
long strings as non-nesting: they nest by depth, matching the engine) and
README.

Author: brues-code

AddOns/!!!ClassicAPI/Util/AddOnCompat.lua

@@ -84,3 +84,95 @@ if C_AddOns.DoesAddOnExist("Puppeteer") then
         CAPI_MouseoverClearedCompat(PTEnemyUpdater)
     end)
 end
+
+-- ============================================================================
+-- Transpiler self-test suite. Run in-game with /capitranspile (alias /captr).
+--
+-- Exercises the Lua 5.1 syntax backport in the DLL (luasyntax/Transpile.cpp):
+-- leveled long brackets `[=[`, the `#` and `%` operators, `...` expansion, and
+-- `0x` hex literals. Each case checks EITHER the exact rewrite text (via
+-- _classicapi_TranspileLength) OR end-to-end runtime behavior (via loadstring,
+-- which funnels through the same luaL_loadbuffer hook every chunk uses).
+--
+-- Every `[=[` / `#` / `%` / `...` / `0x` below is inside a double-quoted string,
+-- so this file itself transpiles to a no-op on load — the constructs reach the
+-- transpiler only at runtime, when the test feeds them in.
+-- ============================================================================
+local function CAPI_RunTranspileTests()
+    if type(_classicapi_TranspileLength) ~= "function" then
+        print("|cffff5555[transpile]|r ClassicAPI DLL not loaded — nothing to test.")
+        return
+    end
+
+    local pass, fail = 0, 0
+    local function ok(name, cond, detail)
+        if cond then
+            pass = pass + 1
+        else
+            fail = fail + 1
+            print("|cffff5555[transpile] FAIL|r " .. name ..
+                  (detail and ("  " .. detail) or ""))
+        end
+    end
+
+    -- The transpiler rewrites `input` to exactly `expected`.
+    local function textEq(name, input, expected)
+        local got = _classicapi_TranspileLength(input)
+        ok(name, got == expected,
+           "got=[" .. tostring(got) .. "] want=[" .. expected .. "]")
+    end
+
+    -- Compile+run a full chunk through loadstring; compare its return value.
+    local function runChunk(name, src, expected)
+        local f, err = loadstring(src)
+        if not f then ok(name, false, "compile: " .. tostring(err)); return end
+        local good, val = pcall(f)
+        ok(name, good and val == expected,
+           good and ("got=[" .. tostring(val) .. "] want=[" .. tostring(expected) .. "]")
+                 or ("error: " .. tostring(val)))
+    end
+    local function evalEq(name, expr, expected)
+        runChunk(name, "return " .. expr, expected)
+    end
+
+    -- leveled long brackets (new pass) --------------------------------------
+    textEq("longbracket tier1 lvl2",    "s=[==[hello]==]", "s=[[hello]]")
+    textEq("longbracket tier1 lvl1",    "s=[=[hi]=]",      "s=[[hi]]")
+    textEq("longbracket tier2 has-]]",  "s=[==[a]]b]==]",  "s=\"a]]b\"")
+    textEq("longbracket tier2 trail-]", "s=[=[end]]=]",    "s=\"end]\"")
+    textEq("longbracket lvl0 kept",     "s=[[plain]]",     "s=[[plain]]")
+    evalEq("longbracket runtime has-]]","[==[a]]b]==]",    "a]]b")
+    evalEq("longbracket runtime tier1", "[=[plain]=]",     "plain")
+    runChunk("longcomment blanked",     "--[==[ hidden ]==] return 7", 7)
+
+    -- # length --------------------------------------------------------------
+    textEq("len rewrite", "x=#t",       "x=__len(t)")
+    evalEq("len table",   "#({1,2,3})", 3)
+    evalEq("len string",  "#('abcd')",  4)
+
+    -- % modulo (real 5.1 floor-mod, not C fmod) -----------------------------
+    textEq("mod rewrite",    "x=a%b",     "x=__mod(a,b)")
+    evalEq("mod positive",   "5 % 3",     2)
+    evalEq("mod negative",   "-1 % 3",    2)   -- C fmod would give -1
+    evalEq("mod precedence", "2 + 8 % 3", 4)   -- 2 + (8 % 3)
+
+    -- 0x hex literals -------------------------------------------------------
+    textEq("hex rewrite", "x=0xFF", "x=255")
+    evalEq("hex value",   "0x10",   16)
+
+    -- ... vararg ------------------------------------------------------------
+    runChunk("vararg fallback empty", "local t = {...} return #t", 0)
+    runChunk("vararg expand in fn",
+             "local function g(...) return #({...}) end return g(1,2,3,4)", 4)
+
+    -- summary ---------------------------------------------------------------
+    if fail == 0 then
+        print("|cff40ff40[transpile] all " .. pass .. " tests passed.|r")
+    else
+        print("|cffff5555[transpile] " .. fail .. " FAILED|r, " .. pass .. " passed.")
+    end
+end
+
+SLASH_CAPITRANSPILE1 = "/capitranspile"
+SLASH_CAPITRANSPILE2 = "/captr"
+SlashCmdList["CAPITRANSPILE"] = CAPI_RunTranspileTests

README.md

@@ -234,7 +234,7 @@ Transparent engine tweaks — no API to call, they just fix a vanilla limitation
 |-------|--------|
 | Tooltip line cap | Lifts `GameTooltip`'s hard 30-line limit to 60 for every `GameTooltipTemplate` frame (`GameTooltip`, `ShoppingTooltip1/2`, `ItemRefTooltip`, AtlasLoot, …). Stat-heavy tooltips and comparison blocks (e.g. pfUI's eqcompare) no longer have their extra lines silently dropped. Done in pure C++ by growing the engine's FontString pool at tooltip-creation time. |
 | Inline textures | Draws inline texture markup (`\|T…\|t`) as icons in FontStrings, chat, and tooltips, the way 4.3.4+ clients do. Vanilla 1.12 shows the raw escape as literal text instead. This covers item and spell icons, raid-target markers, and the coin icons in money strings. `GetStringWidth` and `GetStringHeight` count the icons, so measured width and text wrapping stay correct. Done in pure C++ by hooking the engine's text pipeline — no addon. |
-| Lua 5.1 syntax | Compiles the Lua 5.1 length (`#`), modulo (`%`), `...`-expression, and `0x` hex-literal syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). See [Lua 5.1 syntax](docs/API.md#lua-51-syntax). |
+| Lua 5.1 syntax | Compiles the Lua 5.1 length (`#`), modulo (`%`), `...`-expression, `0x` hex-literal, and leveled long bracket (`[=[ ]=]`) syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). See [Lua 5.1 syntax](docs/API.md#lua-51-syntax). |
 | Lua 5.1 environment protection | `getfenv` / `setfenv` honor a `__environment` metatable field — the Lua 5.1 sandbox form — in addition to vanilla's raw `__fenv`. See [getfenv / setfenv environment protection](docs/API.md#getfenv--setfenv-environment-protection). |
 | Multi-flavor & conditional TOC loading | Loads modern multi-flavor addons that ship one folder. Selects a version-specific TOC (`<Name>_ClassicAPI.toc` or `<Name>_Turtle.toc`) and the matching keybinding file (`Bindings_ClassicAPI.xml` / `Bindings_Turtle.xml`), accepts a comma-separated `## Interface:` version list (compatible when it includes the client version `11200`), and honors per-line `[AllowLoadGameType]` / `[AllowLoadTextLocale]` conditions and `[Family]` / `[Game]` / `[TextLocale]` path variables inside a TOC. See [Conditional and multi-flavor TOC loading](docs/API.md#conditional-and-multi-flavor-toc-loading). |
 | SavedVariables loaded first | Honors the modern `## LoadSavedVariablesFirst` TOC directive: a flagged addon's SavedVariables load before its Lua runs, so file-scope code sees restored config (instead of vanilla's `nil`). See [SavedVariables loaded first](docs/API.md#savedvariables-loaded-first). |

docs/API.md

@@ -8497,17 +8497,18 @@ just the 5.0→5.1 renames — `string.gmatch`←`gfind`, `math.fmod`←`math.mo
 
 ### Lua 5.1 syntax
 
-1.12 runs Lua 5.0. It cannot compile four pieces of Lua 5.1 syntax that
+1.12 runs Lua 5.0. It cannot compile five pieces of Lua 5.1 syntax that
 modern addons use. These are the length operator `#`, the modulo operator
-`%`, `...` used as an expression, and `0x` hexadecimal number literals.
-ClassicAPI rewrites addon source to the 5.0 equivalent before it compiles,
-so all four work:
+`%`, `...` used as an expression, `0x` hexadecimal number literals, and
+leveled long brackets (`[=[ ... ]=]`). ClassicAPI rewrites addon source to
+the 5.0 equivalent before it compiles, so all five work:
 
 ```lua
 local n = #myTable          -- length operator
 local r = a % b             -- modulo operator
 local args = { ... }        -- ... as an expression, not only in a parameter list
 local mask = 0xFF00         -- hex number literal
+local doc = [=[ has ]] in it ]=]   -- leveled long bracket
 ```
 
 The rewrite is transparent. You do not call anything. It runs on every
@@ -8526,6 +8527,11 @@ What each form does:
 - `0xFF00` becomes its decimal value (`65280`) — the same number Lua 5.1
   produces. Vanilla's lexer rejects `0x` literals, so without this an addon
   needs `tonumber("0xFF00", 16)`.
+- `[=[ ... ]=]` (a leveled long bracket, with any number of `=`) holds text
+  a plain `[[ ... ]]` cannot, such as text that contains `]]`. ClassicAPI
+  rewrites a leveled long string to a plain long string, or to a quoted
+  string when its body needs one. It removes a leveled long comment
+  (`--[=[ ... ]=]`).
 
 **Addon file arguments.** A modern addon reads its name and its private
 table from the file arguments:
@@ -8545,9 +8551,13 @@ needs that addon's opt-in.
 
 - The rewrite reads strings and comments correctly. A `%` in `"%d"` or a
   `#` in `--[[ # ]]` is left alone.
-- A nested long string or comment (`[[ a [[ b ]] c ]]`) matches at the
-  first close, not by depth. This is a 5.0-only form that addons almost
-  never use.
+- A plain long string that contains `[[` nests and closes by depth, the
+  same as the 5.0 engine. Lua 5.1 does not nest. For text that contains
+  `[[` or `]]`, use a leveled bracket (`[=[ ... ]=]`).
+- ClassicAPI rewrites a leveled long string to a plain `[[ ... ]]` when it
+  can, which keeps the exact value. A body that contains `[[` or `]]`, or
+  ends with `]`, becomes a quoted string instead. A quoted string keeps a
+  leading newline in the value. Lua 5.1 drops that newline.
 - Only integer hex is converted. Hex *floats* (`0x1.8p3`) and literals
   wider than 64 bits are left as-is. Both are almost nonexistent in addon
   code.
@@ -8556,7 +8566,8 @@ needs that addon's opt-in.
   Treat them as internal. Do not call them directly.
 - To turn a rewrite off for diagnosis, call
   `_classicapi_SetTranspileOption(name, false)`, where `name` is
-  `"Length"`, `"Modulo"`, `"VarargExpansion"`, or `"HexLiterals"`. This
+  `"Length"`, `"Modulo"`, `"VarargExpansion"`, `"HexLiterals"`, or
+  `"LongBrackets"`. This
   reverts affected chunks to the state that fails to compile, so use it
   only to answer "is the rewrite breaking this addon?".