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

rustc_attr_parsing/
interface.rs
