Skip to main content

Module lua

Module lua 

Source
Expand description

\directlua: the Lua a LuaTeX document contains, actually run.

LuaTeX’s one real addition to TeX82 is an escape into a scripting language: \directlua{...} hands its ⟨general text⟩ to an embedded interpreter, and whatever that chunk prints comes back as input. The LuaTeX manual (1.24.0, TeX Live 2026, §2.4.1) states the whole contract in two sentences:

The \directlua command is expandable. Since it passes Lua code to the Lua interpreter its expansion from the TeX viewpoint is usually empty. However, there are some Lua functions that produce material to be read by TeX, the so called print functions. The most simple use of these is tex.print(<string> s). The characters of the string s will be placed on the TeX input buffer, that is, ‘before TeX’s eyes’ to be read by TeX immediately.

That is what this module is: a real Lua state, and a bridge that turns what it printed into tokens pushed in front of the mouth. The manual’s own example is the acceptance criterion —

\count10=20
a\directlua{tex.print(tex.count[10]+5)}b

— which expands to a25b and cannot be faked by consuming the chunk.

§Which Lua

PUC-Lua 5.3, through mlua’s vendored build, because that is the language the documents are written against: “We currently use Lua 5.3 and will follow developments of the language but normally with some delay” (§4.2.1), and lua.version in a LuaTeX run answers Lua 5.3. fusevm hosts seventeen language frontends and none of them is Lua, so there was nothing to reuse: a Lua frontend for it would be a second Lua implementation to keep bug-for- bug identical with PUC’s, which is precisely the kind of near-miss that makes a document’s output wrong in a way nobody can see.

§When it runs

Expansion is a compile-time act here (see crate::lower), so a chunk runs while the document is being lowered, in document order, and its printed tokens are read by the lowerer immediately after. That is the same position \directlua occupies in LuaTeX — it is expandable, so it runs when the expander reaches it — and it is why a chunk can define a macro the next line uses.

The corollary is what a chunk can SEE. \count registers live in fusevm slots at run time and in Engine::known while lowering, so tex.count[10] reads the lowering-time value, and a write goes to both: the frontend table (so \the\count10 inside an \edef agrees) and a Cmd::SetCount (so the same register in the compiled program agrees). \dimen and \skip are the same slot file at another offset (crate::compiler), so they come the same way; \toks is a token list rather than a slot, and comes from Engine::toks.

§The node library, and the lists the stomach builds

node (crate::lua::node) is LuaTeX’s, both faces of it: every type, every field at luatex’s index, the direct face as bare integers, attribute lists, the properties table, and node.hpack/node.vpack/node.dimensions over crate::pack’s port of tex.web §649-§679. The lists TeX builds are the stomach’s (crate::stomach), and they reach Lua through the callbacks: a callback.register of a list callback fills the matching crate::node::hooks point, so the stomach hands its list over while the program runs and packs what comes back.

§What is NOT here, and why it is absent rather than stubbed

  • The box registers and the current list from a chunk. tex.box, tex.getbox, tex.setbox, tex.getlist, tex.getnest, node.write: the stomach holds them while the program runs, and a chunk runs while the program is lowered, before any of them exists. These say so rather than being absent, because “attempt to call a nil value” would not tell a document’s author which of the two engines’ worlds it had walked into.
  • The internal parameters texrs does not hold – tex.prevdepth, tex.pagegoal, LuaTeX’s and e-TeX’s additions to §236 – refuse, naming where the value would live. The ones it does hold, crate::intpar and crate::params, are read and assigned (crate::lua::tex).

§The rest of LuaTeX’s state

build follows luastuff.c’s luainterpreter(): crate::lua::libs opens Lua’s libraries and LuaTeX’s C ones (LPeg, slnunicode, LuaFileSystem, bit32, zlib, gzip – compiled from the sources LuaTeX ships), md5, sha2 and the string/os extensions; then come tex, token, node, texio, kpse (crate::lua::kpse, with the require searcher), callback, lua (crate::lua::lualib) and status, and last luatex-core.lua’s gap-filling. The engine a library function needs is lent to it for the length of each call into Lua (crate::lua::ctx), so a function a package keeps from one chunk works in the next, as a C function over TeX’s globals does in LuaTeX.

Re-exports§

pub use font::LuaChar;
pub use font::LuaFont;

Modules§

callback
The callback library: where a document’s Lua takes over a step of TeX.
font
The font library: fonts as Lua tables (luatexdir/lua/lfontlib.c and the font_from_lua/font_to_lua halves of font/luafont.c).
pdf
The pdf library: what a chunk tells the PDF backend (luatexdir/lua/lpdflib.c).

Functions§

claims
Whether this control sequence is one this module answers.
expands_in_gullet
Whether name is a Lua call the gullet expands: a token.set_lua name defined without "protected" (lua_expandable_call_cmd).
explicit_jobname
A job name given outright – by set_jobname or -jobname – rather than taken from the input file’s name.
lower
Lower one of the Lua primitives.
reset
Throw away the Lua state. For a caller that knows a document has ended.
set_jobname
What tex.jobname answers from here on.
set_progname
The program name kpse searches under from here on: lualatex for a LaTeX document, as LuaTeX’s own lualatex invocation sets it, luatex for plain. It decides TEXINPUTS.<progname>, so kpse.find_file of a .sty under luatex and under lualatex are different searches.