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
\directluacommand 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 istex.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::intparandcrate::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§
Modules§
- callback
- The
callbacklibrary: where a document’s Lua takes over a step of TeX. - font
- The
fontlibrary: fonts as Lua tables (luatexdir/lua/lfontlib.c and thefont_from_lua/font_to_luahalves of font/luafont.c). - The
pdflibrary: 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
nameis a Lua call the gullet expands: atoken.set_luaname defined without"protected"(lua_expandable_call_cmd). - explicit_
jobname - A job name given outright – by
set_jobnameor-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.jobnameanswers from here on. - set_
progname - The program name
kpsesearches under from here on:lualatexfor a LaTeX document, as LuaTeX’s ownlualatexinvocation sets it,luatexfor plain. It decidesTEXINPUTS.<progname>, sokpse.find_fileof a.styunderluatexand underlualatexare different searches.