rustc_attr_parsing/
interface.rs

1use std::convert::identity;
2
3use rustc_ast as ast;
4use rustc_ast::token::DocFragmentKind;
5use rustc_ast::{AttrItemKind, AttrStyle, CRATE_NODE_ID, NodeId, Safety};
6use rustc_data_structures::sync::{DynSend, DynSync};
7use rustc_errors::{Diag, DiagCtxtHandle, Diagnostic, Level, MultiSpan};
8use rustc_feature::{AttributeTemplate, Features};
9use rustc_hir::attrs::AttributeKind;
10use rustc_hir::{AttrArgs, AttrItem, AttrPath, Attribute, HashIgnoredAttrId, Target};
11use rustc_lint_defs::RegisteredTools;
12use rustc_session::Session;
13use rustc_session::lint::LintId;
14use rustc_span::{DUMMY_SP, ErrorGuaranteed, Span, Symbol, sym};
15
16use crate::attributes::AttributeSafety;
17use crate::context::{
18    ATTRIBUTE_PARSERS, AcceptContext, FinalizeContext, FinalizeFn, SharedContext,
19};
20use crate::early_parsed::{EARLY_PARSED_ATTRIBUTES, EarlyParsedState};
21use crate::parser::{AllowExprMetavar, ArgParser, PathParser, RefPathParser};
22use crate::session_diagnostics::ParsedDescription;
23use crate::{OmitDoc, ShouldEmit};
24
25pub struct EmitAttribute(
26    pub  Box<
27        dyn for<'a> FnOnce(DiagCtxtHandle<'a>, Level, &Session) -> Diag<'a, ()>
28            + DynSend
29            + DynSync
30            + 'static,
31    >,
32);
33
34/// Context created once, for example as part of the ast lowering
35/// context, through which all attributes can be lowered.
36pub struct AttributeParser<'sess> {
37    pub(crate) tools: Option<&'sess RegisteredTools>,
38    pub(crate) features: Option<&'sess Features>,
39    pub(crate) sess: &'sess Session,
40    pub(crate) should_emit: ShouldEmit,
41
42    /// *Only* parse attributes with this symbol.
43    ///
44    /// Used in cases where we want the lowering infrastructure for parse just a single attribute.
45    parse_only: Option<&'static [Symbol]>,
46}
47
48impl<'sess> AttributeParser<'sess> {
49    /// This method allows you to parse attributes *before* you have access to features or tools.
50    /// One example where this is necessary, is to parse `feature` attributes themselves for
51    /// example.
52    ///
53    /// Try to use this as little as possible. Attributes *should* be lowered during
54    /// `rustc_ast_lowering`. Some attributes require access to features to parse, which would
55    /// crash if you tried to do so through [`parse_limited`](Self::parse_limited).
56    ///
57    /// To make sure use is limited, supply a `Symbol` you'd like to parse. Only attributes with
58    /// that symbol are picked out of the list of instructions and parsed. Those are returned.
59    ///
60    /// No diagnostics will be emitted when parsing limited. Lints are not emitted at all, while
61    /// errors will be emitted as a delayed bugs. in other words, we *expect* attributes parsed
62    /// with `parse_limited` to be reparsed later during ast lowering where we *do* emit the errors
63    ///
64    /// Due to this function not taking in RegisteredTools, *do not* use this for parsing any lint attributes
65    pub fn parse_limited(
66        sess: &'sess Session,
67        attrs: &[ast::Attribute],
68        sym: &'static [Symbol],
69    ) -> Option<Attribute> {
70        Self::parse_limited_should_emit(
71            sess,
72            attrs,
73            sym,
74            // Because we're not emitting warnings/errors, the target should not matter
75            DUMMY_SP,
76            CRATE_NODE_ID,
77            Target::Crate,
78            None,
79            ShouldEmit::Nothing,
80        )
81    }
82
83    /// This does the same as `parse_limited`, except it has a `should_emit` parameter which allows it to emit errors.
84    /// Usually you want `parse_limited`, which emits no errors.
85    ///
86    /// Due to this function not taking in RegisteredTools, *do not* use this for parsing any lint attributes
87    pub fn parse_limited_should_emit(
88        sess: &'sess Session,
89        attrs: &[ast::Attribute],
90        sym: &'static [Symbol],
91        target_span: Span,
92        target_node_id: NodeId,
93        target: Target,
94        features: Option<&'sess Features>,
95        should_emit: ShouldEmit,
96    ) -> Option<Attribute> {
97        let mut parsed = Self::parse_limited_all(
98            sess,
99            attrs,
100            Some(sym),
101            target,
102            target_span,
103            target_node_id,
104            features,
105            should_emit,
106            None,
107        );
108        if !(parsed.len() <= 1) {
    ::core::panicking::panic("assertion failed: parsed.len() <= 1")
};assert!(parsed.len() <= 1);
109        parsed.pop()
110    }
111
112    /// This method allows you to parse a list of attributes *before* `rustc_ast_lowering`.
113    /// This can be used for attributes that would be removed before `rustc_ast_lowering`, such as attributes on macro calls.
114    ///
115    /// Try to use this as little as possible. Attributes *should* be lowered during
116    /// `rustc_ast_lowering`. Some attributes require access to features to parse, which would
117    /// crash if you tried to do so through [`parse_limited_all`](Self::parse_limited_all).
118    /// Therefore, if `parse_only` is None, then features *must* be provided.
119    pub fn parse_limited_all(
120        sess: &'sess Session,
121        attrs: &[ast::Attribute],
122        parse_only: Option<&'static [Symbol]>,
123        target: Target,
124        target_span: Span,
125        target_node_id: NodeId,
126        features: Option<&'sess Features>,
127        should_emit: ShouldEmit,
128        tools: Option<&'sess RegisteredTools>,
129    ) -> Vec<Attribute> {
130        let mut p = Self { features, tools, parse_only, sess, should_emit };
131        p.parse_attribute_list(
132            attrs,
133            target_span,
134            target,
135            OmitDoc::Skip,
136            std::convert::identity,
137            |lint_id, span, kind| {
138                sess.psess.dyn_buffer_lint_sess(lint_id.lint, span, target_node_id, kind.0)
139            },
140        )
141    }
142
143    /// This method parses a single attribute, using `parse_fn`.
144    /// This is useful if you already know what exact attribute this is, and want to parse it.
145    pub fn parse_single<T>(
146        sess: &'sess Session,
147        attr: &ast::Attribute,
148        target_span: Span,
149        target_node_id: NodeId,
150        target: Target,
151        features: Option<&'sess Features>,
152        emit_errors: ShouldEmit,
153        parse_fn: fn(cx: &mut AcceptContext<'_, '_>, item: &ArgParser) -> Option<T>,
154        template: &AttributeTemplate,
155        allow_expr_metavar: AllowExprMetavar,
156        expected_safety: AttributeSafety,
157    ) -> Option<T> {
158        let ast::AttrKind::Normal(normal_attr) = &attr.kind else {
159            {
    ::core::panicking::panic_fmt(format_args!("parse_single called on a doc attr"));
}panic!("parse_single called on a doc attr")
160        };
161        let parts =
162            normal_attr.item.path.segments.iter().map(|seg| seg.ident.name).collect::<Vec<_>>();
163
164        let path = AttrPath::from_ast(&normal_attr.item.path, identity);
165        let args = ArgParser::from_attr_args(
166            &normal_attr.item.args.unparsed_ref().unwrap(),
167            &parts,
168            &sess.psess,
169            emit_errors,
170            allow_expr_metavar,
171        )?;
172        Self::parse_single_args(
173            sess,
174            attr.span,
175            normal_attr.item.span(),
176            attr.style,
177            path,
178            Some(normal_attr.item.unsafety),
179            expected_safety,
180            ParsedDescription::Attribute,
181            target_span,
182            target_node_id,
183            target,
184            features,
185            emit_errors,
186            &args,
187            parse_fn,
188            template,
189        )
190    }
191
192    /// This method is equivalent to `parse_single`, but parses arguments using `parse_fn` using manually created `args`.
193    /// This is useful when you want to parse other things than attributes using attribute parsers.
194    pub fn parse_single_args<T, I>(
195        sess: &'sess Session,
196        attr_span: Span,
197        inner_span: Span,
198        attr_style: AttrStyle,
199        attr_path: AttrPath,
200        attr_safety: Option<Safety>,
201        expected_safety: AttributeSafety,
202        parsed_description: ParsedDescription,
203        target_span: Span,
204        target_node_id: NodeId,
205        target: Target,
206        features: Option<&'sess Features>,
207        should_emit: ShouldEmit,
208        args: &I,
209        parse_fn: fn(cx: &mut AcceptContext<'_, '_>, item: &I) -> T,
210        template: &AttributeTemplate,
211    ) -> T {
212        let mut parser = Self { features, tools: None, parse_only: None, sess, should_emit };
213        let mut emit_lint = |lint_id: LintId, span: MultiSpan, kind: EmitAttribute| {
214            sess.psess.dyn_buffer_lint_sess(lint_id.lint, span, target_node_id, kind.0)
215        };
216        if let Some(safety) = attr_safety {
217            parser.check_attribute_safety(
218                &attr_path,
219                inner_span,
220                safety,
221                expected_safety,
222                &mut emit_lint,
223            );
224        }
225        let mut cx: AcceptContext<'_, 'sess> = AcceptContext {
226            shared: SharedContext {
227                cx: &mut parser,
228                target_span,
229                target,
230                emit_lint: &mut emit_lint,
231            },
232            attr_span,
233            inner_span,
234            attr_style,
235            parsed_description,
236            template,
237            attr_safety: attr_safety.unwrap_or(Safety::Default),
238            attr_path,
239        };
240        parse_fn(&mut cx, args)
241    }
242}
243
244impl<'sess> AttributeParser<'sess> {
245    pub fn new(
246        sess: &'sess Session,
247        features: &'sess Features,
248        tools: &'sess RegisteredTools,
249        should_emit: ShouldEmit,
250    ) -> Self {
251        Self { features: Some(features), tools: Some(tools), parse_only: None, sess, should_emit }
252    }
253
254    pub(crate) fn sess(&self) -> &'sess Session {
255        &self.sess
256    }
257
258    pub(crate) fn features(&self) -> &'sess Features {
259        self.features.expect("features not available at this point in the compiler")
260    }
261
262    pub(crate) fn features_option(&self) -> Option<&'sess Features> {
263        self.features
264    }
265
266    pub(crate) fn dcx(&self) -> DiagCtxtHandle<'sess> {
267        self.sess().dcx()
268    }
269
270    pub(crate) fn emit_err(&self, diag: impl for<'x> Diagnostic<'x>) -> ErrorGuaranteed {
271        self.should_emit.emit_err(self.sess.dcx().create_err(diag))
272    }
273
274    /// Parse a list of attributes.
275    ///
276    /// `target_span` is the span of the thing this list of attributes is applied to,
277    /// and when `omit_doc` is set, doc attributes are filtered out.
278    pub fn parse_attribute_list(
279        &mut self,
280        attrs: &[ast::Attribute],
281        target_span: Span,
282        target: Target,
283        omit_doc: OmitDoc,
284        lower_span: impl Copy + Fn(Span) -> Span,
285        mut emit_lint: impl FnMut(LintId, MultiSpan, EmitAttribute),
286    ) -> Vec<Attribute> {
287        let mut attributes = Vec::new();
288        // We store the attributes we intend to discard at the end of this function in order to
289        // check they are applied to the right target and error out if necessary. In practice, we
290        // end up dropping only derive attributes and derive helpers, both being fully processed
291        // at macro expansion.
292        let mut dropped_attributes = Vec::new();
293        let mut attr_paths: Vec<RefPathParser<'_>> = Vec::new();
294        let mut early_parsed_state = EarlyParsedState::default();
295
296        let mut finalizers: Vec<FinalizeFn> = Vec::with_capacity(attrs.len());
297
298        for attr in attrs {
299            // If we're only looking for a single attribute, skip all the ones we don't care about.
300            if let Some(expected) = self.parse_only {
301                if !attr.path_matches(expected) {
302                    continue;
303                }
304            }
305
306            // Sometimes, for example for `#![doc = include_str!("readme.md")]`,
307            // doc still contains a non-literal. You might say, when we're lowering attributes
308            // that's expanded right? But no, sometimes, when parsing attributes on macros,
309            // we already use the lowering logic and these are still there. So, when `omit_doc`
310            // is set we *also* want to ignore these.
311            let is_doc_attribute = attr.has_name(sym::doc);
312            if omit_doc == OmitDoc::Skip && is_doc_attribute {
313                continue;
314            }
315
316            let attr_span = lower_span(attr.span);
317            match &attr.kind {
318                ast::AttrKind::DocComment(comment_kind, symbol) => {
319                    if omit_doc == OmitDoc::Skip {
320                        continue;
321                    }
322
323                    attributes.push(Attribute::Parsed(AttributeKind::DocComment {
324                        style: attr.style,
325                        kind: DocFragmentKind::Sugared(*comment_kind),
326                        span: attr_span,
327                        comment: *symbol,
328                    }));
329                }
330                ast::AttrKind::Normal(n) => {
331                    attr_paths.push(PathParser(&n.item.path));
332                    let attr_path = AttrPath::from_ast(&n.item.path, lower_span);
333
334                    let args = match &n.item.args {
335                        AttrItemKind::Unparsed(args) => args,
336                        AttrItemKind::Parsed(parsed) => {
337                            early_parsed_state
338                                .accept_early_parsed_attribute(attr_span, lower_span, parsed);
339                            continue;
340                        }
341                    };
342
343                    let parts =
344                        n.item.path.segments.iter().map(|seg| seg.ident.name).collect::<Vec<_>>();
345
346                    if let Some(accept) = ATTRIBUTE_PARSERS.accepters.get(parts.as_slice()) {
347                        self.check_attribute_safety(
348                            &attr_path,
349                            lower_span(n.item.span()),
350                            n.item.unsafety,
351                            accept.safety,
352                            &mut emit_lint,
353                        );
354
355                        let Some(args) = ArgParser::from_attr_args(
356                            args,
357                            &parts,
358                            &self.sess.psess,
359                            self.should_emit,
360                            AllowExprMetavar::No,
361                        ) else {
362                            continue;
363                        };
364
365                        // Special-case handling for `#[doc = "..."]`: if we go through with
366                        // `DocParser`, the order of doc comments will be messed up because `///`
367                        // doc comments are added into `attributes` whereas attributes parsed with
368                        // `DocParser` are added into `parsed_attributes` which are then appended
369                        // to `attributes`. So if you have:
370                        //
371                        // /// bla
372                        // #[doc = "a"]
373                        // /// blob
374                        //
375                        // You would get:
376                        //
377                        // bla
378                        // blob
379                        // a
380                        if is_doc_attribute
381                            && let ArgParser::NameValue(nv) = &args
382                            // If not a string key/value, it should emit an error, but to make
383                            // things simpler, it's handled in `DocParser` because it's simpler to
384                            // emit an error with `AcceptContext`.
385                            && let Some(comment) = nv.value_as_str()
386                        {
387                            attributes.push(Attribute::Parsed(AttributeKind::DocComment {
388                                style: attr.style,
389                                kind: DocFragmentKind::Raw(nv.value_span),
390                                span: attr_span,
391                                comment,
392                            }));
393                            continue;
394                        }
395
396                        let mut cx: AcceptContext<'_, 'sess> = AcceptContext {
397                            shared: SharedContext {
398                                cx: self,
399                                target_span,
400                                target,
401                                emit_lint: &mut emit_lint,
402                            },
403                            attr_span,
404                            inner_span: lower_span(n.item.span()),
405                            attr_style: attr.style,
406                            parsed_description: ParsedDescription::Attribute,
407                            template: &accept.template,
408                            attr_safety: n.item.unsafety,
409                            attr_path: attr_path.clone(),
410                        };
411
412                        (accept.accept_fn)(&mut cx, &args);
413                        finalizers.push(accept.finalizer);
414
415                        if !#[allow(non_exhaustive_omitted_patterns)] match cx.should_emit {
    ShouldEmit::Nothing => true,
    _ => false,
}matches!(cx.should_emit, ShouldEmit::Nothing) {
416                            Self::check_target(&accept.allowed_targets, target, &mut cx);
417                        }
418                    } else {
419                        let attr = AttrItem {
420                            path: attr_path.clone(),
421                            args: self
422                                .lower_attr_args(n.item.args.unparsed_ref().unwrap(), lower_span),
423                            id: HashIgnoredAttrId { attr_id: attr.id },
424                            style: attr.style,
425                            span: attr_span,
426                        };
427
428                        self.check_attribute_safety(
429                            &attr_path,
430                            lower_span(n.item.span()),
431                            n.item.unsafety,
432                            AttributeSafety::Normal,
433                            &mut emit_lint,
434                        );
435
436                        if !#[allow(non_exhaustive_omitted_patterns)] match self.should_emit {
    ShouldEmit::Nothing => true,
    _ => false,
}matches!(self.should_emit, ShouldEmit::Nothing)
437                            && target == Target::Crate
438                        {
439                            self.check_invalid_crate_level_attr_item(&attr, n.item.span());
440                        }
441
442                        let attr = Attribute::Unparsed(Box::new(attr));
443
444                        if self.tools.is_some_and(|tools| {
445                            tools.iter().any(|tool| tool.name == parts[0])
446                            // FIXME: this can be removed once #152369 has been merged.
447                            // https://github.com/rust-lang/rust/pull/152369
448                            || [sym::allow, sym::deny, sym::expect, sym::forbid, sym::warn]
449                                .contains(&parts[0])
450                        }) {
451                            attributes.push(attr);
452                        } else {
453                            dropped_attributes.push(attr);
454                        }
455                    }
456                }
457            }
458        }
459
460        early_parsed_state.finalize_early_parsed_attributes(&mut attributes);
461        for f in &finalizers {
462            if let Some(attr) = f(&mut FinalizeContext {
463                shared: SharedContext { cx: self, target_span, target, emit_lint: &mut emit_lint },
464                all_attrs: &attr_paths,
465            }) {
466                attributes.push(Attribute::Parsed(attr));
467            }
468        }
469
470        if !#[allow(non_exhaustive_omitted_patterns)] match self.should_emit {
    ShouldEmit::Nothing => true,
    _ => false,
}matches!(self.should_emit, ShouldEmit::Nothing) && target == Target::WherePredicate {
471            self.check_invalid_where_predicate_attrs(attributes.iter().chain(&dropped_attributes));
472        }
473
474        attributes
475    }
476
477    /// Returns whether there is a parser for an attribute with this name
478    pub fn is_parsed_attribute(path: &[Symbol]) -> bool {
479        /// The list of attributes that are parsed attributes,
480        /// even though they don't have a parser in `Late::parsers()`
481        const SPECIAL_ATTRIBUTES: &[&[Symbol]] = &[
482            // Cfg attrs are removed after being early-parsed, so don't need to be in the parser list
483            &[sym::cfg],
484            &[sym::cfg_attr],
485        ];
486
487        ATTRIBUTE_PARSERS.accepters.contains_key(path)
488            || EARLY_PARSED_ATTRIBUTES.contains(&path)
489            || SPECIAL_ATTRIBUTES.contains(&path)
490    }
491
492    fn lower_attr_args(&self, args: &ast::AttrArgs, lower_span: impl Fn(Span) -> Span) -> AttrArgs {
493        match args {
494            ast::AttrArgs::Empty => AttrArgs::Empty,
495            ast::AttrArgs::Delimited(args) => AttrArgs::Delimited(args.clone()),
496            // This is an inert key-value attribute - it will never be visible to macros
497            // after it gets lowered to HIR. Therefore, we can extract literals to handle
498            // nonterminals in `#[doc]` (e.g. `#[doc = $e]`).
499            ast::AttrArgs::Eq { eq_span, expr } => {
500                // In valid code the value always ends up as a single literal. Otherwise, a dummy
501                // literal suffices because the error is handled elsewhere.
502                let lit = if let ast::ExprKind::Lit(token_lit) = expr.kind
503                    && let Ok(lit) =
504                        ast::MetaItemLit::from_token_lit(token_lit, lower_span(expr.span))
505                {
506                    lit
507                } else {
508                    let guar = self.dcx().span_delayed_bug(
509                        args.span().unwrap_or(DUMMY_SP),
510                        "expr in place where literal is expected (builtin attr parsing)",
511                    );
512                    ast::MetaItemLit {
513                        symbol: sym::dummy,
514                        suffix: None,
515                        kind: ast::LitKind::Err(guar),
516                        span: DUMMY_SP,
517                    }
518                };
519                AttrArgs::Eq { eq_span: lower_span(*eq_span), expr: lit }
520            }
521        }
522    }
523}
rustc_attr_parsing/interface.rs

rustc_attr_parsing/
interface.rs
