1 //! Checks that meta-variables in macro definition are correctly declared and used.
5 //! ## Meta-variables must not be bound twice
8 //! macro_rules! foo { ($x:tt $x:tt) => { $x }; }
11 //! This check is sound (no false-negative) and complete (no false-positive).
13 //! ## Meta-variables must not be free
16 //! macro_rules! foo { () => { $x }; }
19 //! This check is also done at macro instantiation but only if the branch is taken.
21 //! ## Meta-variables must repeat at least as many times as their binder
24 //! macro_rules! foo { ($($x:tt)*) => { $x }; }
27 //! This check is also done at macro instantiation but only if the branch is taken.
29 //! ## Meta-variables must repeat with the same Kleene operators as their binder
32 //! macro_rules! foo { ($($x:tt)+) => { $($x)* }; }
35 //! This check is not done at macro instantiation.
39 //! In the presence of nested macros (a macro defined in a macro), those checks may have false
40 //! positives and false negatives. We try to detect those cases by recognizing potential macro
41 //! definitions in RHSes, but nested macros may be hidden through the use of particular values of
44 //! ## Examples of false positive
46 //! False positives can come from cases where we don't recognize a nested macro, because it depends
47 //! on particular values of meta-variables. In the following example, we think both instances of
48 //! `$x` are free, which is a correct statement if `$name` is anything but `macro_rules`. But when
49 //! `$name` is `macro_rules`, like in the instantiation below, then `$x:tt` is actually a binder of
50 //! the nested macro and `$x` is bound to it.
53 //! macro_rules! foo { ($name:ident) => { $name! bar { ($x:tt) => { $x }; } }; }
54 //! foo!(macro_rules);
57 //! False positives can also come from cases where we think there is a nested macro while there
58 //! isn't. In the following example, we think `$x` is free, which is incorrect because `bar` is not
59 //! a nested macro since it is not evaluated as code by `stringify!`.
62 //! macro_rules! foo { () => { stringify!(macro_rules! bar { () => { $x }; }) }; }
65 //! ## Examples of false negative
67 //! False negatives can come from cases where we don't recognize a meta-variable, because it depends
68 //! on particular values of meta-variables. In the following examples, we don't see that if `$d` is
69 //! instantiated with `$` then `$d z` becomes `$z` in the nested macro definition and is thus a free
70 //! meta-variable. Note however, that if `foo` is instantiated, then we would check the definition
71 //! of `bar` and would see the issue.
74 //! macro_rules! foo { ($d:tt) => { macro_rules! bar { ($y:tt) => { $d z }; } }; }
77 //! # How it is checked
79 //! There are 3 main functions: `check_binders`, `check_occurrences`, and `check_nested_macro`. They
80 //! all need some kind of environment.
84 //! Environments are used to pass information.
86 //! ### From LHS to RHS
88 //! When checking a LHS with `check_binders`, we produce (and use) an environment for binders,
89 //! namely `Binders`. This is a mapping from binder name to information about that binder: the span
90 //! of the binder for error messages and the stack of Kleene operators under which it was bound in
93 //! This environment is used by both the LHS and RHS. The LHS uses it to detect duplicate binders.
94 //! The RHS uses it to detect the other errors.
96 //! ### From outer macro to inner macro
98 //! When checking the RHS of an outer macro and we detect a nested macro definition, we push the
99 //! current state, namely `MacroState`, to an environment of nested macro definitions. Each state
100 //! stores the LHS binders when entering the macro definition as well as the stack of Kleene
101 //! operators under which the inner macro is defined in the RHS.
103 //! This environment is a stack representing the nesting of macro definitions. As such, the stack of
104 //! Kleene operators under which a meta-variable is repeating is the concatenation of the stacks
105 //! stored when entering a macro definition starting from the state in which the meta-variable is
107 use crate::mbe
::{KleeneToken, TokenTree}
;
109 use rustc_ast
::token
::{DelimToken, Token, TokenKind}
;
110 use rustc_ast
::{NodeId, DUMMY_NODE_ID}
;
111 use rustc_data_structures
::fx
::FxHashMap
;
112 use rustc_session
::lint
::builtin
::META_VARIABLE_MISUSE
;
113 use rustc_session
::parse
::ParseSess
;
114 use rustc_span
::symbol
::kw
;
115 use rustc_span
::{symbol::MacroRulesNormalizedIdent, MultiSpan, Span}
;
117 use smallvec
::SmallVec
;
119 /// Stack represented as linked list.
121 /// Those are used for environments because they grow incrementally and are not mutable.
125 /// A non-empty stack.
129 /// The previous elements.
130 prev
: &'a Stack
<'a
, T
>,
134 impl<'a
, T
> Stack
<'a
, T
> {
135 /// Returns whether a stack is empty.
136 fn is_empty(&self) -> bool
{
138 Stack
::Empty
=> true,
143 /// Returns a new stack with an element of top.
144 fn push(&'a
self, top
: T
) -> Stack
<'a
, T
> {
145 Stack
::Push { top, prev: self }
149 impl<'a
, T
> Iterator
for &'a Stack
<'a
, T
> {
152 // Iterates from top to bottom of the stack.
153 fn next(&mut self) -> Option
<&'a T
> {
155 Stack
::Empty
=> None
,
156 Stack
::Push { ref top, ref prev }
=> {
164 impl From
<&Stack
<'_
, KleeneToken
>> for SmallVec
<[KleeneToken
; 1]> {
165 fn from(ops
: &Stack
<'_
, KleeneToken
>) -> SmallVec
<[KleeneToken
; 1]> {
166 let mut ops
: SmallVec
<[KleeneToken
; 1]> = ops
.cloned().collect();
167 // The stack is innermost on top. We want outermost first.
173 /// Information attached to a meta-variable binder in LHS.
175 /// The span of the meta-variable in LHS.
177 /// The stack of Kleene operators (outermost first).
178 ops
: SmallVec
<[KleeneToken
; 1]>,
181 /// An environment of meta-variables to their binder information.
182 type Binders
= FxHashMap
<MacroRulesNormalizedIdent
, BinderInfo
>;
184 /// The state at which we entered a macro definition in the RHS of another macro definition.
185 struct MacroState
<'a
> {
186 /// The binders of the branch where we entered the macro definition.
187 binders
: &'a Binders
,
188 /// The stack of Kleene operators (outermost first) where we entered the macro definition.
189 ops
: SmallVec
<[KleeneToken
; 1]>,
192 /// Checks that meta-variables are used correctly in a macro definition.
195 /// - `sess` is used to emit diagnostics and lints
196 /// - `node_id` is used to emit lints
197 /// - `span` is used when no spans are available
198 /// - `lhses` and `rhses` should have the same length and represent the macro definition
199 pub(super) fn check_meta_variables(
206 if lhses
.len() != rhses
.len() {
207 sess
.span_diagnostic
.span_bug(span
, "length mismatch between LHSes and RHSes")
209 let mut valid
= true;
210 for (lhs
, rhs
) in lhses
.iter().zip(rhses
.iter()) {
211 let mut binders
= Binders
::default();
212 check_binders(sess
, node_id
, lhs
, &Stack
::Empty
, &mut binders
, &Stack
::Empty
, &mut valid
);
213 check_occurrences(sess
, node_id
, rhs
, &Stack
::Empty
, &binders
, &Stack
::Empty
, &mut valid
);
218 /// Checks `lhs` as part of the LHS of a macro definition, extends `binders` with new binders, and
219 /// sets `valid` to false in case of errors.
222 /// - `sess` is used to emit diagnostics and lints
223 /// - `node_id` is used to emit lints
224 /// - `lhs` is checked as part of a LHS
225 /// - `macros` is the stack of possible outer macros
226 /// - `binders` contains the binders of the LHS
227 /// - `ops` is the stack of Kleene operators from the LHS
228 /// - `valid` is set in case of errors
233 macros
: &Stack
<'_
, MacroState
<'_
>>,
234 binders
: &mut Binders
,
235 ops
: &Stack
<'_
, KleeneToken
>,
239 TokenTree
::Token(..) => {}
240 // This can only happen when checking a nested macro because this LHS is then in the RHS of
241 // the outer macro. See ui/macros/macro-of-higher-order.rs where $y:$fragment in the
242 // LHS of the nested macro (and RHS of the outer macro) is parsed as MetaVar(y) Colon
243 // MetaVar(fragment) and not as MetaVarDecl(y, fragment).
244 TokenTree
::MetaVar(span
, name
) => {
245 if macros
.is_empty() {
246 sess
.span_diagnostic
.span_bug(span
, "unexpected MetaVar in lhs");
248 let name
= MacroRulesNormalizedIdent
::new(name
);
249 // There are 3 possibilities:
250 if let Some(prev_info
) = binders
.get(&name
) {
251 // 1. The meta-variable is already bound in the current LHS: This is an error.
252 let mut span
= MultiSpan
::from_span(span
);
253 span
.push_span_label(prev_info
.span
, "previous declaration".into());
254 buffer_lint(sess
, span
, node_id
, "duplicate matcher binding");
255 } else if get_binder_info(macros
, binders
, name
).is_none() {
256 // 2. The meta-variable is free: This is a binder.
257 binders
.insert(name
, BinderInfo { span, ops: ops.into() }
);
259 // 3. The meta-variable is bound: This is an occurrence.
260 check_occurrences(sess
, node_id
, lhs
, macros
, binders
, ops
, valid
);
263 // Similarly, this can only happen when checking a toplevel macro.
264 TokenTree
::MetaVarDecl(span
, name
, _kind
) => {
265 if !macros
.is_empty() {
266 sess
.span_diagnostic
.span_bug(span
, "unexpected MetaVarDecl in nested lhs");
268 let name
= MacroRulesNormalizedIdent
::new(name
);
269 if let Some(prev_info
) = get_binder_info(macros
, binders
, name
) {
270 // Duplicate binders at the top-level macro definition are errors. The lint is only
271 // for nested macro definitions.
273 .struct_span_err(span
, "duplicate matcher binding")
274 .span_label(span
, "duplicate binding")
275 .span_label(prev_info
.span
, "previous binding")
279 binders
.insert(name
, BinderInfo { span, ops: ops.into() }
);
282 TokenTree
::Delimited(_
, ref del
) => {
284 check_binders(sess
, node_id
, tt
, macros
, binders
, ops
, valid
);
287 TokenTree
::Sequence(_
, ref seq
) => {
288 let ops
= ops
.push(seq
.kleene
);
290 check_binders(sess
, node_id
, tt
, macros
, binders
, &ops
, valid
);
296 /// Returns the binder information of a meta-variable.
299 /// - `macros` is the stack of possible outer macros
300 /// - `binders` contains the current binders
301 /// - `name` is the name of the meta-variable we are looking for
302 fn get_binder_info
<'a
>(
303 mut macros
: &'a Stack
<'a
, MacroState
<'a
>>,
304 binders
: &'a Binders
,
305 name
: MacroRulesNormalizedIdent
,
306 ) -> Option
<&'a BinderInfo
> {
307 binders
.get(&name
).or_else(|| macros
.find_map(|state
| state
.binders
.get(&name
)))
310 /// Checks `rhs` as part of the RHS of a macro definition and sets `valid` to false in case of
314 /// - `sess` is used to emit diagnostics and lints
315 /// - `node_id` is used to emit lints
316 /// - `rhs` is checked as part of a RHS
317 /// - `macros` is the stack of possible outer macros
318 /// - `binders` contains the binders of the associated LHS
319 /// - `ops` is the stack of Kleene operators from the RHS
320 /// - `valid` is set in case of errors
321 fn check_occurrences(
325 macros
: &Stack
<'_
, MacroState
<'_
>>,
327 ops
: &Stack
<'_
, KleeneToken
>,
331 TokenTree
::Token(..) => {}
332 TokenTree
::MetaVarDecl(span
, _name
, _kind
) => {
333 sess
.span_diagnostic
.span_bug(span
, "unexpected MetaVarDecl in rhs")
335 TokenTree
::MetaVar(span
, name
) => {
336 let name
= MacroRulesNormalizedIdent
::new(name
);
337 check_ops_is_prefix(sess
, node_id
, macros
, binders
, ops
, span
, name
);
339 TokenTree
::Delimited(_
, ref del
) => {
340 check_nested_occurrences(sess
, node_id
, &del
.tts
, macros
, binders
, ops
, valid
);
342 TokenTree
::Sequence(_
, ref seq
) => {
343 let ops
= ops
.push(seq
.kleene
);
344 check_nested_occurrences(sess
, node_id
, &seq
.tts
, macros
, binders
, &ops
, valid
);
349 /// Represents the processed prefix of a nested macro.
350 #[derive(Clone, Copy, PartialEq, Eq)]
351 enum NestedMacroState
{
352 /// Nothing that matches a nested macro definition was processed yet.
354 /// The token `macro_rules` was processed.
356 /// The tokens `macro_rules!` were processed.
358 /// The tokens `macro_rules!` followed by a name were processed. The name may be either directly
359 /// an identifier or a meta-variable (that hopefully would be instantiated by an identifier).
361 /// The keyword `macro` was processed.
363 /// The keyword `macro` followed by a name was processed.
365 /// The keyword `macro` followed by a name and a token delimited by parentheses was processed.
369 /// Checks `tts` as part of the RHS of a macro definition, tries to recognize nested macro
370 /// definitions, and sets `valid` to false in case of errors.
373 /// - `sess` is used to emit diagnostics and lints
374 /// - `node_id` is used to emit lints
375 /// - `tts` is checked as part of a RHS and may contain macro definitions
376 /// - `macros` is the stack of possible outer macros
377 /// - `binders` contains the binders of the associated LHS
378 /// - `ops` is the stack of Kleene operators from the RHS
379 /// - `valid` is set in case of errors
380 fn check_nested_occurrences(
384 macros
: &Stack
<'_
, MacroState
<'_
>>,
386 ops
: &Stack
<'_
, KleeneToken
>,
389 let mut state
= NestedMacroState
::Empty
;
390 let nested_macros
= macros
.push(MacroState { binders, ops: ops.into() }
);
391 let mut nested_binders
= Binders
::default();
395 NestedMacroState
::Empty
,
396 &TokenTree
::Token(Token { kind: TokenKind::Ident(name, false), .. }
),
398 if name
== kw
::MacroRules
{
399 state
= NestedMacroState
::MacroRules
;
400 } else if name
== kw
::Macro
{
401 state
= NestedMacroState
::Macro
;
405 NestedMacroState
::MacroRules
,
406 &TokenTree
::Token(Token { kind: TokenKind::Not, .. }
),
408 state
= NestedMacroState
::MacroRulesNot
;
411 NestedMacroState
::MacroRulesNot
,
412 &TokenTree
::Token(Token { kind: TokenKind::Ident(..), .. }
),
414 state
= NestedMacroState
::MacroRulesNotName
;
416 (NestedMacroState
::MacroRulesNot
, &TokenTree
::MetaVar(..)) => {
417 state
= NestedMacroState
::MacroRulesNotName
;
418 // We check that the meta-variable is correctly used.
419 check_occurrences(sess
, node_id
, tt
, macros
, binders
, ops
, valid
);
421 (NestedMacroState
::MacroRulesNotName
, &TokenTree
::Delimited(_
, ref del
))
422 | (NestedMacroState
::MacroName
, &TokenTree
::Delimited(_
, ref del
))
423 if del
.delim
== DelimToken
::Brace
=>
425 let macro_rules
= state
== NestedMacroState
::MacroRulesNotName
;
426 state
= NestedMacroState
::Empty
;
428 check_nested_macro(sess
, node_id
, macro_rules
, &del
.tts
, &nested_macros
, valid
);
429 // If we did not check the whole macro definition, then check the rest as if outside
430 // the macro definition.
431 check_nested_occurrences(
442 NestedMacroState
::Macro
,
443 &TokenTree
::Token(Token { kind: TokenKind::Ident(..), .. }
),
445 state
= NestedMacroState
::MacroName
;
447 (NestedMacroState
::Macro
, &TokenTree
::MetaVar(..)) => {
448 state
= NestedMacroState
::MacroName
;
449 // We check that the meta-variable is correctly used.
450 check_occurrences(sess
, node_id
, tt
, macros
, binders
, ops
, valid
);
452 (NestedMacroState
::MacroName
, &TokenTree
::Delimited(_
, ref del
))
453 if del
.delim
== DelimToken
::Paren
=>
455 state
= NestedMacroState
::MacroNameParen
;
456 nested_binders
= Binders
::default();
467 (NestedMacroState
::MacroNameParen
, &TokenTree
::Delimited(_
, ref del
))
468 if del
.delim
== DelimToken
::Brace
=>
470 state
= NestedMacroState
::Empty
;
482 state
= NestedMacroState
::Empty
;
483 check_occurrences(sess
, node_id
, tt
, macros
, binders
, ops
, valid
);
489 /// Checks the body of nested macro, returns where the check stopped, and sets `valid` to false in
492 /// The token trees are checked as long as they look like a list of (LHS) => {RHS} token trees. This
493 /// check is a best-effort to detect a macro definition. It returns the position in `tts` where we
494 /// stopped checking because we detected we were not in a macro definition anymore.
497 /// - `sess` is used to emit diagnostics and lints
498 /// - `node_id` is used to emit lints
499 /// - `macro_rules` specifies whether the macro is `macro_rules`
500 /// - `tts` is checked as a list of (LHS) => {RHS}
501 /// - `macros` is the stack of outer macros
502 /// - `valid` is set in case of errors
503 fn check_nested_macro(
508 macros
: &Stack
<'_
, MacroState
<'_
>>,
513 let separator
= if macro_rules { TokenKind::Semi }
else { TokenKind::Comma }
;
515 // We expect 3 token trees: `(LHS) => {RHS}`. The separator is checked after.
517 || !tts
[i
].is_delimited()
518 || !tts
[i
+ 1].is_token(&TokenKind
::FatArrow
)
519 || !tts
[i
+ 2].is_delimited()
524 let rhs
= &tts
[i
+ 2];
525 let mut binders
= Binders
::default();
526 check_binders(sess
, node_id
, lhs
, macros
, &mut binders
, &Stack
::Empty
, valid
);
527 check_occurrences(sess
, node_id
, rhs
, macros
, &binders
, &Stack
::Empty
, valid
);
528 // Since the last semicolon is optional for `macro_rules` macros and decl_macro are not terminated,
529 // we increment our checked position by how many token trees we already checked (the 3
530 // above) before checking for the separator.
532 if i
== n
|| !tts
[i
].is_token(&separator
) {
535 // We increment our checked position for the semicolon.
541 /// Checks that a meta-variable occurrence is valid.
544 /// - `sess` is used to emit diagnostics and lints
545 /// - `node_id` is used to emit lints
546 /// - `macros` is the stack of possible outer macros
547 /// - `binders` contains the binders of the associated LHS
548 /// - `ops` is the stack of Kleene operators from the RHS
549 /// - `span` is the span of the meta-variable to check
550 /// - `name` is the name of the meta-variable to check
551 fn check_ops_is_prefix(
554 macros
: &Stack
<'_
, MacroState
<'_
>>,
556 ops
: &Stack
<'_
, KleeneToken
>,
558 name
: MacroRulesNormalizedIdent
,
560 let macros
= macros
.push(MacroState { binders, ops: ops.into() }
);
561 // Accumulates the stacks the operators of each state until (and including when) the
562 // meta-variable is found. The innermost stack is first.
563 let mut acc
: SmallVec
<[&SmallVec
<[KleeneToken
; 1]>; 1]> = SmallVec
::new();
564 for state
in ¯os
{
565 acc
.push(&state
.ops
);
566 if let Some(binder
) = state
.binders
.get(&name
) {
567 // This variable concatenates the stack of operators from the RHS of the LHS where the
568 // meta-variable was defined to where it is used (in possibly nested macros). The
569 // outermost operator is first.
570 let mut occurrence_ops
: SmallVec
<[KleeneToken
; 2]> = SmallVec
::new();
571 // We need to iterate from the end to start with outermost stack.
572 for ops
in acc
.iter().rev() {
573 occurrence_ops
.extend_from_slice(ops
);
575 ops_is_prefix(sess
, node_id
, span
, name
, &binder
.ops
, &occurrence_ops
);
579 buffer_lint(sess
, span
.into(), node_id
, &format
!("unknown macro variable `{}`", name
));
582 /// Returns whether `binder_ops` is a prefix of `occurrence_ops`.
584 /// The stack of Kleene operators of a meta-variable occurrence just needs to have the stack of
585 /// Kleene operators of its binder as a prefix.
587 /// Consider $i in the following example:
589 /// ( $( $i:ident = $($j:ident),+ );* ) => { $($( $i += $j; )+)* }
591 /// It occurs under the Kleene stack ["*", "+"] and is bound under ["*"] only.
594 /// - `sess` is used to emit diagnostics and lints
595 /// - `node_id` is used to emit lints
596 /// - `span` is the span of the meta-variable being check
597 /// - `name` is the name of the meta-variable being check
598 /// - `binder_ops` is the stack of Kleene operators for the binder
599 /// - `occurrence_ops` is the stack of Kleene operators for the occurrence
604 name
: MacroRulesNormalizedIdent
,
605 binder_ops
: &[KleeneToken
],
606 occurrence_ops
: &[KleeneToken
],
608 for (i
, binder
) in binder_ops
.iter().enumerate() {
609 if i
>= occurrence_ops
.len() {
610 let mut span
= MultiSpan
::from_span(span
);
611 span
.push_span_label(binder
.span
, "expected repetition".into());
612 let message
= &format
!("variable '{}' is still repeating at this depth", name
);
613 buffer_lint(sess
, span
, node_id
, message
);
616 let occurrence
= &occurrence_ops
[i
];
617 if occurrence
.op
!= binder
.op
{
618 let mut span
= MultiSpan
::from_span(span
);
619 span
.push_span_label(binder
.span
, "expected repetition".into());
620 span
.push_span_label(occurrence
.span
, "conflicting repetition".into());
621 let message
= "meta-variable repeats with different Kleene operator";
622 buffer_lint(sess
, span
, node_id
, message
);
628 fn buffer_lint(sess
: &ParseSess
, span
: MultiSpan
, node_id
: NodeId
, message
: &str) {
629 // Macros loaded from other crates have dummy node ids.
630 if node_id
!= DUMMY_NODE_ID
{
631 sess
.buffer_lint(&META_VARIABLE_MISUSE
, span
, node_id
, message
);