Struct rustc_expand::mbe::macro_parser::MatcherPos

pub(in mbe::macro_parser) struct MatcherPos<'root, 'tt> {
    top_elts: TokenTreeOrTokenTreeSlice<'tt>,
    idx: usize,
    matches: Box<[Lrc<SmallVec<[NamedMatch; 4]>>]>,
    match_lo: usize,
    match_cur: usize,
    match_hi: usize,
    seq_op: Option<KleeneOp>,
    sep: Option<Token>,
    up: Option<MatcherPosHandle<'root, 'tt>>,
    stack: SmallVec<[MatcherTtFrame<'tt>; 1]>,
}

Represents a single "position" (aka "matcher position", aka "item"), as described in the module documentation.

Here:

• 'root represents the lifetime of the stack slot that holds the root MatcherPos. As described in MatcherPosHandle, the root MatcherPos structure is stored on the stack, but subsequent instances are put into the heap.
• 'tt represents the lifetime of the token trees that this matcher position refers to.

It is important to distinguish these two lifetimes because we have a SmallVec<TokenTreeOrTokenTreeSlice<'tt>> below, and the destructor of that is considered to possibly access the data from its elements (it lacks a #[may_dangle] attribute). As a result, the compiler needs to know that all the elements in that SmallVec strictly outlive the root stack slot lifetime. By separating 'tt from 'root, we can show that.

Fields

top_elts: TokenTreeOrTokenTreeSlice<'tt>

The token or sequence of tokens that make up the matcher

idx: usize

The position of the "dot" in this matcher

matches: Box<[Lrc<SmallVec<[NamedMatch; 4]>>]>

For each named metavar in the matcher, we keep track of token trees matched against the metavar by the black box parser. In particular, there may be more than one match per metavar if we are in a repetition (each repetition matches each of the variables). Moreover, matchers and repetitions can be nested; the matches field is shared (hence the Rc) among all "nested" matchers. match_lo, match_cur, and match_hi keep track of the current position of the self matcher position in the shared matches list.

Also, note that while we are descending into a sequence, matchers are given their own matches vector. Only once we reach the end of a full repetition of the sequence do we add all bound matches from the submatcher into the shared top-level matches vector. If sep and up are Some, then matches is not the shared top-level list. Instead, if one wants the shared matches, one should use up.matches.

match_lo: usize

The position in matches corresponding to the first metavar in this matcher's sequence of token trees. In other words, the first metavar in the first token of top_elts corresponds to matches[match_lo].

match_cur: usize

The position in matches corresponding to the metavar we are currently trying to match against the source token stream. match_lo <= match_cur <= match_hi.

match_hi: usize

Similar to match_lo except match_hi is the position in matches of the last metavar in this matcher.

seq_op: Option<KleeneOp>

The KleeneOp of this sequence if we are in a repetition.

sep: Option<Token>

The separator if we are in a repetition.

up: Option<MatcherPosHandle<'root, 'tt>>

The "parent" matcher position if we are in a repetition. That is, the matcher position just before we enter the sequence.

stack: SmallVec<[MatcherTtFrame<'tt>; 1]>

Specifically used to "unzip" token trees. By "unzip", we mean to unwrap the delimiters from a delimited token tree (e.g., something wrapped in ( )) or to get the contents of a doc comment...

When matching against matchers with nested delimited submatchers (e.g., pat ( pat ( .. ) pat ) pat), we need to keep track of the matchers we are descending into. This stack does that where the bottom of the stack is the outermost matcher. Also, throughout the comments, this "descent" is often referred to as "unzipping"...

Implementations

impl<'root, 'tt> MatcherPos<'root, 'tt>

pub(in mbe::macro_parser) fn push_match(
    &mut self,
    idx: usize,
    m: NamedMatch
)

Adds m as a named match for the idx-th metavar.

Trait Implementations

impl<'root, 'tt> Clone for MatcherPos<'root, 'tt>

pub fn clone(&self) -> MatcherPos<'root, 'tt>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.