Expand description
Native implementations of macros from TeX-coded libraries (pgfmath,
l3fp, …).
A native implementation replaces one specific definition of a macro,
recognized by a fingerprint of its parameter text and body, so a package
version with a different definition, or a document that redefines the
macro, simply runs the TeX code. Each Macro object is looked up once,
on its first call (the result is cached in Macro::native); the
lookup is by definition, so \let copies are recognized too.
A native implementation runs after the macro’s arguments have been
scanned, instead of the macro’s body. It must leave exactly the state the
body would have left (assignments, registers, the tokens it puts back
into the input), or return false before changing anything, and the
body runs as usual. That makes partial implementations safe: anything
unusual falls back to TeX.
Implementations that perform assignments (Native::executes) only run
where TeX would execute the body: when main control fetches the macro
(not inside \edef, \message, \csname, a number being scanned, …).
Expandable implementations put their final result back into the input,
where TeX would put the body and expand it further. They do not run
where the body is not expanded further: a single expansion step
(\expandafter, \span in a preamble, Lua’s token.expand; see
Engine::one_step), where the body itself is the observable result.
Everywhere else the next token of the body is expanded at once, so an
implementation is correct if the body’s full expansion is
self-contained (it consumes nothing after the call) and produces its
whole result before its first unexpandable token is seen; each
implementation documents why its macro qualifies.
No native implementation runs while tracing is on, so logs stay
identical. An implementation that expands tokens itself must clear
Engine::exec_context while doing so.
RETEX_NO_NATIVE=1 disables all native implementations: the reference
for differential tests (output with and without must be identical).
RETEX_NATIVE_DEBUG=1 prints, for each first call of a macro whose
name is registered, its fingerprint and whether it matched: the way to
obtain fingerprints for a new package version.
Structs§
- Following
- The input after a native macro’s arguments, from
Engine::native_following_subst: the tokens of the token lists on top of the input stack, in reading order, read on demand. - Native
- A native implementation of one macro definition.
Statics§
- NATIVES
- The registry.