Skip to main content

MacroBindings

Trait MacroBindings 

Source
pub trait MacroBindings {
    // Required methods
    fn definition_at(&self, name: &str, offset: usize) -> Option<&MacroDef>;
    fn definition(&self, name: &str) -> Option<&MacroDef>;

    // Provided method
    fn builtin_operator(&self, name: &str, operand: &str) -> Option<Value> { ... }
}
Expand description

What a cook reads its macros from — the definitions a file starts with, asked by name and offset.

A trait rather than &MacroTable because the answer comes from three places, and they must be asked the same way: a file’s own directives while it is being cooked, the compilation’s builtins (-dM), and — for a file inside a walked translation unit — the unit’s timeline, which materialises nothing per file.

§Why the answer is by offset, and why that is the whole difficulty

A #define is in force from where it was written, and “where” is a position in the file being cooked. One definition reaches hundreds of files from a different offset in each, which is why the shared layer cannot be a table of definitions alone: what is shared is the definition, and the offset is computed by whoever knows which file is asking. See TranslationUnit::definitions and FileMacros.

Both questions return a borrow rather than an Arc: the layers own their definitions, and the hot path asks this once per identifier token.

Required Methods§

Source

fn definition_at(&self, name: &str, offset: usize) -> Option<&MacroDef>

The definition name is in force with at offset, or None when nothing says.

Source

fn definition(&self, name: &str) -> Option<&MacroDef>

The definition name is in force with at the end of the file.

A question of its own rather than definition_at(name, usize::MAX): a caller that has read the whole file (a #if evaluated after it, a completion list) means “the last one”, and a shared layer may answer it without resolving any offset at all.

Provided Methods§

Source

fn builtin_operator(&self, name: &str, operand: &str) -> Option<Value>

The value of a builtin operator whose operand is not a name — __has_include(<vector>).

Here as well as on crate::condition::MacroValues because the two are the same question asked by two layers, and the layer in the middle must not swallow it: every condition in every cook is evaluated through a crate::preprocess::PositionalMacros, which holds a &dyn MacroBindings and adds an offset. A method that existed only on MacroValues would be unreachable from there — the implementation would sit one layer down, fully written and never called, and __has_include would answer Unknown in every real cook.

None is “this table cannot speak about that”, which the evaluator turns into Unknown rather than 0. The default is None so that a table which knows nothing about builtins is not forced to say so.

__has_cpp_attribute is not answered here: its answer depends on the macro state at an offset, and a position is the one thing this trait’s methods are not given. It is a free function taking an offset — crate::preprocess::cooked::attribute_support — and crate::preprocess::PositionalMacros, which has the offset, is the layer that calls it.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§