{{#invoke:Module|function}} runs Lua to build part of a page. That is how most of
the complicated logic on a real wiki is written: infoboxes, citation formatting,
string manipulation that templates cannot express.
This project runs it on a Lua 5.1 interpreter written from scratch, in
crates/lua. It is not a port of PUC-Lua or LuaJIT, so the license
stays clean.
The interpreter is behind a feature, because most compilations do not need it:
cargo add wikitext --features luaWithout the feature, #invoke compiles to an error marker. With it, and with no
provider configured, you get a different one:
invoke: no Lua module provider is configured
LuaModules is the built-in provider:
use std::rc::Rc;
use wikitext::lua_modules::LuaModules;
use wikitext::{compile, Options};
let modules = LuaModules::new();
modules.insert("Roman", r#"
local p = {}
function p.convert(frame)
return "value: " .. frame.args[1]
end
return p
"#);
let options = Options::default().with_module_provider(Rc::new(modules));
assert!(compile("{{#invoke:Roman|convert|42}}", &options).contains("value: 42"));A module is an ordinary Lua chunk that returns a table. Each function on that table
becomes callable through #invoke. Module:Roman and Roman are the same module,
and the name is normalised the way page titles are.
Note the Rc rather than Arc: Lua values are single threaded, so a provider is not
Send and cannot be shared across threads. Give each thread its own.
The function receives a frame with the call's arguments:
| Field or method | What it holds |
|---|---|
frame.args |
The arguments after the function name, positional and named |
frame:getParent() |
The frame that called this one, or nil at the top |
frame:getTitle() |
The title of the page being compiled |
function p.greet(frame)
local name = frame.args[1] or frame.args.name or "world"
return "Hello, " .. name .. "!"
endThere is no frame:expandTemplate and no frame:preprocess, so a module cannot
transclude a template or re-parse wikitext itself. Whatever a module needs from
another page it has to receive as an argument.
The CLI reads *.lua files and uses each file name as the module name:
mkdir modules
cat > modules/Roman.lua <<'LUA'
local p = {}
function p.convert(frame)
local n = tonumber(frame.args[1]) or 0
local map = { [1000]='M', [900]='CM', [500]='D', [400]='CD', [100]='C',
[90]='XC', [50]='L', [40]='XL', [10]='X', [9]='IX',
[5]='V', [4]='IV', [1]='I' }
local out = {}
for _, value in ipairs({1000,900,500,400,100,90,50,40,10,9,5,4,1}) do
while n >= value do n = n - value; out[#out + 1] = map[value] end
end
return table.concat(out)
end
return p
LUA
echo 'Roman numeral of 1994 is {{#invoke:Roman|convert|1994}}.' | wikitext --modules ./modules
# <p>Roman numeral of 1994 is MCMXCIV.</p>Each #invoke call runs in a fresh interpreter with an mw table installed. Fresh
each time is deliberate: one module must not see another's globals, and a call must
not leave state behind for the next one.
| Namespace | What it covers |
|---|---|
mw.text |
Trimming, splitting, escaping, mw.text.len by bytes |
mw.ustring |
The same operations counted in characters rather than bytes |
mw.title |
Page title objects, with tostring and .. |
mw.uri |
Percent encoding and decoding |
mw.html |
A chained builder for HTML fragments |
mw.language |
Language codes and names |
mw.dumpObject |
A readable dump, for debugging a module |
Three names exist so that a module written for a real wiki fails where you can see it rather than silently doing nothing:
mw.loadDataraisesmw.loadData is not supported.mw.siteandmw.messageare empty tables, and reading a field from them givesnil. There is no site configuration or interface message store behind this compiler, so there is nothing truthful to return.
Title objects also compare by field rather than by title; only tostring, .. and
field access are guaranteed.
The interpreter implements Lua 5.1, including the parts people actually rely on:
if,while,repeat, bothforforms,break, functions,:method declarations withself, varargs..., table constructors, multiple returns- Closures capturing upvalues by reference, metatables, and the usual metamethods
(
__index,__newindex,__call,__tostring,__concat,__eq,__lt,__le,__lenand the arithmetic ones) - String and number coercion
string,table,math,osand thebaselibrary, with the full Lua pattern matcher (%b,%f, position captures, back-references, greedy and lazy quantifiers) and everystring.formatconversion
A module cannot run forever. Three ceilings apply per evaluation:
| Limit | Default |
|---|---|
| Call depth | 200 frames |
| Loop iterations | 1 000 000 per loop |
| Instruction budget | 20 000 000 steps |
Exceeding one returns a limit error rather than hanging. That error is not
catchable by pcall, on purpose: it means the interpreter gave up, and letting the
module catch it and continue would only hit the ceiling again immediately.
A few habits that pay off, learned from the ones that are hard to debug:
- Return early for a bad argument rather than producing
nilthat fails later.frame.args[1]is a string ornil, never a number, sotonumberit. - Do not count arguments with
#frame.args. Positional arguments are numbered from 1, but named arguments share the same table and are invisible to the length operator, so{{#invoke:M|f|one|two|name=three}}gives#frame.args == 2whilepairssees three entries. Usepairswhen you need to know what was passed. - Keep the module returning a table. A chunk that returns nothing makes every
#invokeon it fail.