Expand description
A file’s effect on the macro table: what its directives do to the environment they are read in.
surface_of says what a file’s directives are; this module interprets them. Together they are the replacement
for “cook the include closure to find out what a header does”:
effect(surface, environment) = define/undef events that are *active* under that environment, in order① composition: a translation unit's macro table = fold(apply, effect of each included file). One hash lookup
per include once the effect is cached, not a parse.
② a body does not move the effect: function bodies, statements and comments are not events, so
`Surface::signature` is unchanged by them and the effect cannot change either.
③ a guarded header's second inclusion is empty: its `#ifndef GUARD` is already false, so the effect has no
folds at all — which is why including the same file three times costs one evaluation plus two lookups.§What “cannot be said” means here, and why it is a first-class answer
A condition the table cannot decide (#if __has_include(<x>) with no search paths, a value that is not a
number) gives Effect::certain = false. A caller must then fall back to the exact path — cooking the file —
rather than guess: an effect that quietly assumed false would drop every #define behind the condition, and
the index would be wrong rather than incomplete. That is the same distinction the preprocessor layer makes with
its Value::Unknown.
Structs§
- Chain
- The macro table a translation unit has, built by folding effects instead of cooking.
- Effect
- What a file does to a macro table, given the table it is read in.
- Macros
- A macro table: the environment an effect is interpreted against, and what an effect produces.
- Surfaces
- Walked
- What one walk of an include tree cost, and how often the effect cache answered.
Enums§
- Fold
- One step an effect performs.
Constants§
- SURFACES_
HELD - The surfaces a walk has already scanned, keyed by the file’s content.
Traits§
- Reads
- How the chain reads files: a provider and an include resolver, both as plain functions so that a caller can hand over a session, a test’s memory files, or a probe.
Functions§
- condition_
tokens - The tokens of a condition, exposed for callers that evaluate one themselves.
- effect_
of - Interpret a file’s directives against an environment.
- values_
for - The names a surface tests, with the values they hold in an environment — the key’s material.