pub struct MacroTable { /* private fields */ }Expand description
C MAC_HANDLE (macLib.h:47-57): the macro table, the scope depth,
and the one bit that says whether the cached values can be trusted.
This is the unit C creates once per FILE and expands once per line
(dbReadCOM holds macHandle across the whole .db,
dbLexRoutines.c:256-300), which is what makes a macro’s own fault a
once-per-file notice rather than a once-per-line one. Callers that
have a single string and no file keep using expand_macros, which
is this type for the length of one call.
Entries are in the order they were defined in, which is C’s
macPutValue call order and the order the expansion pass walks them
in (C expand, macCore.c:655) — so it is the order the notices a
faulty definition raises come out in.
That order is a property of MacroDefs, not of this type: a table
built from one is in the caller’s order by construction, and a table
built from a HashMap is in the only order a hash map can offer.
Implementations§
Source§impl MacroTable
impl MacroTable
Sourcepub fn new(defs: impl Into<MacroDefs>, opts: MacroExpandOptions) -> Self
pub fn new(defs: impl Into<MacroDefs>, opts: MacroExpandOptions) -> Self
C macCreateHandle + one macPutValue per pair
(macCore.c:64-118). The table starts dirty: nothing is expanded
until something asks for an expansion.
The definitions arrive in MacroDefs order and are installed in
it, so the notice order of the first expansion pass is the
caller’s own definition order and does not have to be arranged
for afterwards.
Sourcepub fn expand(&mut self, src: &str) -> MacroExpansion
pub fn expand(&mut self, src: &str) -> MacroExpansion
C macExpandString (macCore.c:175-227): bring the cached
values up to date, then translate src under a stack entry typed
"string" whose name is src itself.
Both halves matter to what comes out. The table pass is what decides the text of a reference into a cycle and the seat of every notice a macro’s own value raises; the string pass is the only place the caller’s own text is ever looked at.
Sourcepub fn define(&mut self, name: &str, rawval: String)
pub fn define(&mut self, name: &str, rawval: String)
C macPutValue( handle, name, value ) (macCore.c:262-289) with
a non-NULL value: install rawval for name at the current scope
level.
The value is stored RAW. C never expands a definition as it is
installed — macInstallMacros hands macPutValue exactly the
bytes macParseDefns cut out (macUtil.c:250-275) — so a
definition that mentions another macro stays live and follows
whatever that macro is when it is finally read.
Sourcepub fn undefine(&mut self, name: &str)
pub fn undefine(&mut self, name: &str)
C macPutValue( handle, name, NULL ) (macCore.c:274-280): the
name is deleted rather than defined, which is what a definition
with no = in it means (macParseDefns’s del[i],
macUtil.c:105-110).
Deleting is not the same as defining nothing: an OUTER definition of the same name is uncovered by it, and a reference that finds nothing at all is undefined rather than empty.