Skip to main content

Module effect

Module effect 

Source
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.