rustc_attr_parsing/attributes/
mod.rs

1//! This module defines traits for attribute parsers, little state machines that recognize and parse
2//! attributes out of a longer list of attributes. The main trait is called [`AttributeParser`].
3//! You can find more docs about [`AttributeParser`]s on the trait itself.
4//! However, for many types of attributes, implementing [`AttributeParser`] is not necessary.
5//! It allows for a lot of flexibility you might not want.
6//!
7//! Specifically, you might not care about managing the state of your [`AttributeParser`]
8//! state machine yourself. In this case you can choose to implement:
9//!
10//! - [`SingleAttributeParser`]: makes it easy to implement an attribute which should error if it
11//! appears more than once in a list of attributes
12//! - [`CombineAttributeParser`]: makes it easy to implement an attribute which should combine the
13//! contents of attributes, if an attribute appear multiple times in a list
14//!
15//! Attributes should be added to `crate::context::ATTRIBUTE_PARSERS` to be parsed.
16
17use std::marker::PhantomData;
18
19use rustc_attr_data_structures::AttributeKind;
20use rustc_feature::{AttributeTemplate, template};
21use rustc_span::{Span, Symbol};
22use thin_vec::ThinVec;
23
24use crate::context::{AcceptContext, FinalizeContext, Stage};
25use crate::parser::ArgParser;
26use crate::session_diagnostics::UnusedMultiple;
27
28pub(crate) mod allow_unstable;
29pub(crate) mod cfg;
30pub(crate) mod cfg_old;
31pub(crate) mod codegen_attrs;
32pub(crate) mod confusables;
33pub(crate) mod deprecation;
34pub(crate) mod dummy;
35pub(crate) mod inline;
36pub(crate) mod link_attrs;
37pub(crate) mod lint_helpers;
38pub(crate) mod loop_match;
39pub(crate) mod must_use;
40pub(crate) mod no_implicit_prelude;
41pub(crate) mod non_exhaustive;
42pub(crate) mod path;
43pub(crate) mod repr;
44pub(crate) mod rustc_internal;
45pub(crate) mod semantics;
46pub(crate) mod stability;
47pub(crate) mod test_attrs;
48pub(crate) mod traits;
49pub(crate) mod transparency;
50pub(crate) mod util;
51
52type AcceptFn<T, S> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess, S>, &ArgParser<'_>);
53type AcceptMapping<T, S> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T, S>)];
54
55/// An [`AttributeParser`] is a type which searches for syntactic attributes.
56///
57/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
58/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
59/// attribute it is looking for was not yet seen.
60///
61/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].
62/// These are listed as pairs, of symbols and function pointers. The function pointer will
63/// be called when that attribute is found on an item, which can influence the state of the little
64/// state machine.
65///
66/// Finally, after all attributes on an item have been seen, and possibly been accepted,
67/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
68/// whether it has seen the attribute it has been looking for.
69///
70/// The state machine is automatically reset to parse attributes on the next item.
71///
72/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]
73/// or [`CombineAttributeParser`] instead.
74pub(crate) trait AttributeParser<S: Stage>: Default + 'static {
75    /// The symbols for the attributes that this parser is interested in.
76    ///
77    /// If an attribute has this symbol, the `accept` function will be called on it.
78    const ATTRIBUTES: AcceptMapping<Self, S>;
79
80    /// The parser has gotten a chance to accept the attributes on an item,
81    /// here it can produce an attribute.
82    ///
83    /// All finalize methods of all parsers are unconditionally called.
84    /// This means you can't unconditionally return `Some` here,
85    /// that'd be equivalent to unconditionally applying an attribute to
86    /// every single syntax item that could have attributes applied to it.
87    /// Your accept mappings should determine whether this returns something.
88    fn finalize(self, cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind>;
89}
90
91/// Alternative to [`AttributeParser`] that automatically handles state management.
92/// A slightly simpler and more restricted way to convert attributes.
93/// Assumes that an attribute can only appear a single time on an item,
94/// and errors when it sees more.
95///
96/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
97///
98/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple
99/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
100pub(crate) trait SingleAttributeParser<S: Stage>: 'static {
101    /// The single path of the attribute this parser accepts.
102    ///
103    /// If you need the parser to accept more than one path, use [`AttributeParser`] instead
104    const PATH: &[Symbol];
105
106    /// Configures the precedence of attributes with the same `PATH` on a syntax node.
107    const ATTRIBUTE_ORDER: AttributeOrder;
108
109    /// Configures what to do when when the same attribute is
110    /// applied more than once on the same syntax node.
111    ///
112    /// [`ATTRIBUTE_ORDER`](Self::ATTRIBUTE_ORDER) specified which one is assumed to be correct,
113    /// and this specified whether to, for example, warn or error on the other one.
114    const ON_DUPLICATE: OnDuplicate<S>;
115
116    /// The template this attribute parser should implement. Used for diagnostics.
117    const TEMPLATE: AttributeTemplate;
118
119    /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
120    fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind>;
121}
122
123/// Use in combination with [`SingleAttributeParser`].
124/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].
125pub(crate) struct Single<T: SingleAttributeParser<S>, S: Stage>(
126    PhantomData<(S, T)>,
127    Option<(AttributeKind, Span)>,
128);
129
130impl<T: SingleAttributeParser<S>, S: Stage> Default for Single<T, S> {
131    fn default() -> Self {
132        Self(Default::default(), Default::default())
133    }
134}
135
136impl<T: SingleAttributeParser<S>, S: Stage> AttributeParser<S> for Single<T, S> {
137    const ATTRIBUTES: AcceptMapping<Self, S> = &[(
138        T::PATH,
139        <T as SingleAttributeParser<S>>::TEMPLATE,
140        |group: &mut Single<T, S>, cx, args| {
141            if let Some(pa) = T::convert(cx, args) {
142                match T::ATTRIBUTE_ORDER {
143                    // keep the first and report immediately. ignore this attribute
144                    AttributeOrder::KeepInnermost => {
145                        if let Some((_, unused)) = group.1 {
146                            T::ON_DUPLICATE.exec::<T>(cx, cx.attr_span, unused);
147                            return;
148                        }
149                    }
150                    // keep the new one and warn about the previous,
151                    // then replace
152                    AttributeOrder::KeepOutermost => {
153                        if let Some((_, used)) = group.1 {
154                            T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);
155                        }
156                    }
157                }
158
159                group.1 = Some((pa, cx.attr_span));
160            }
161        },
162    )];
163
164    fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
165        Some(self.1?.0)
166    }
167}
168
169pub(crate) enum OnDuplicate<S: Stage> {
170    /// Give a default warning
171    Warn,
172
173    /// Duplicates will be a warning, with a note that this will be an error in the future.
174    WarnButFutureError,
175
176    /// Give a default error
177    Error,
178
179    /// Ignore duplicates
180    Ignore,
181
182    /// Custom function called when a duplicate attribute is found.
183    ///
184    /// - `unused` is the span of the attribute that was unused or bad because of some
185    ///   duplicate reason (see [`AttributeOrder`])
186    /// - `used` is the span of the attribute that was used in favor of the unused attribute
187    Custom(fn(cx: &AcceptContext<'_, '_, S>, used: Span, unused: Span)),
188}
189
190impl<S: Stage> OnDuplicate<S> {
191    fn exec<P: SingleAttributeParser<S>>(
192        &self,
193        cx: &mut AcceptContext<'_, '_, S>,
194        used: Span,
195        unused: Span,
196    ) {
197        match self {
198            OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),
199            OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),
200            OnDuplicate::Error => {
201                cx.emit_err(UnusedMultiple {
202                    this: used,
203                    other: unused,
204                    name: Symbol::intern(
205                        &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),
206                    ),
207                });
208            }
209            OnDuplicate::Ignore => {}
210            OnDuplicate::Custom(f) => f(cx, used, unused),
211        }
212    }
213}
214
215pub(crate) enum AttributeOrder {
216    /// Duplicates after the innermost instance of the attribute will be an error/warning.
217    /// Only keep the lowest attribute.
218    ///
219    /// Attributes are processed from bottom to top, so this raises a warning/error on all the attributes
220    /// further above the lowest one:
221    /// ```
222    /// #[stable(since="1.0")] //~ WARNING duplicated attribute
223    /// #[stable(since="2.0")]
224    /// ```
225    KeepInnermost,
226
227    /// Duplicates before the outermost instance of the attribute will be an error/warning.
228    /// Only keep the highest attribute.
229    ///
230    /// Attributes are processed from bottom to top, so this raises a warning/error on all the attributes
231    /// below the highest one:
232    /// ```
233    /// #[path="foo.rs"]
234    /// #[path="bar.rs"] //~ WARNING duplicated attribute
235    /// ```
236    KeepOutermost,
237}
238
239/// An even simpler version of [`SingleAttributeParser`]:
240/// now automatically check that there are no arguments provided to the attribute.
241///
242/// [`WithoutArgs<T> where T: NoArgsAttributeParser`](WithoutArgs) implements [`SingleAttributeParser`].
243//
244pub(crate) trait NoArgsAttributeParser<S: Stage>: 'static {
245    const PATH: &[Symbol];
246    const ON_DUPLICATE: OnDuplicate<S>;
247
248    /// Create the [`AttributeKind`] given attribute's [`Span`].
249    const CREATE: fn(Span) -> AttributeKind;
250}
251
252pub(crate) struct WithoutArgs<T: NoArgsAttributeParser<S>, S: Stage>(PhantomData<(S, T)>);
253
254impl<T: NoArgsAttributeParser<S>, S: Stage> Default for WithoutArgs<T, S> {
255    fn default() -> Self {
256        Self(Default::default())
257    }
258}
259
260impl<T: NoArgsAttributeParser<S>, S: Stage> SingleAttributeParser<S> for WithoutArgs<T, S> {
261    const PATH: &[Symbol] = T::PATH;
262    const ATTRIBUTE_ORDER: AttributeOrder = AttributeOrder::KeepOutermost;
263    const ON_DUPLICATE: OnDuplicate<S> = T::ON_DUPLICATE;
264    const TEMPLATE: AttributeTemplate = template!(Word);
265
266    fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind> {
267        if let Err(span) = args.no_args() {
268            cx.expected_no_args(span);
269        }
270        Some(T::CREATE(cx.attr_span))
271    }
272}
273
274type ConvertFn<E> = fn(ThinVec<E>, Span) -> AttributeKind;
275
276/// Alternative to [`AttributeParser`] that automatically handles state management.
277/// If multiple attributes appear on an element, combines the values of each into a
278/// [`ThinVec`].
279/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].
280///
281/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple
282/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
283pub(crate) trait CombineAttributeParser<S: Stage>: 'static {
284    const PATH: &[rustc_span::Symbol];
285
286    type Item;
287    /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.
288    ///
289    /// For example, individual representations fomr `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,
290    ///  where `x` is a vec of these individual reprs.
291    const CONVERT: ConvertFn<Self::Item>;
292
293    /// The template this attribute parser should implement. Used for diagnostics.
294    const TEMPLATE: AttributeTemplate;
295
296    /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
297    fn extend<'c>(
298        cx: &'c mut AcceptContext<'_, '_, S>,
299        args: &'c ArgParser<'_>,
300    ) -> impl IntoIterator<Item = Self::Item> + 'c;
301}
302
303/// Use in combination with [`CombineAttributeParser`].
304/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].
305pub(crate) struct Combine<T: CombineAttributeParser<S>, S: Stage> {
306    phantom: PhantomData<(S, T)>,
307    /// A list of all items produced by parsing attributes so far. One attribute can produce any amount of items.
308    items: ThinVec<<T as CombineAttributeParser<S>>::Item>,
309    /// The full span of the first attribute that was encountered.
310    first_span: Option<Span>,
311}
312
313impl<T: CombineAttributeParser<S>, S: Stage> Default for Combine<T, S> {
314    fn default() -> Self {
315        Self {
316            phantom: Default::default(),
317            items: Default::default(),
318            first_span: Default::default(),
319        }
320    }
321}
322
323impl<T: CombineAttributeParser<S>, S: Stage> AttributeParser<S> for Combine<T, S> {
324    const ATTRIBUTES: AcceptMapping<Self, S> = &[(
325        T::PATH,
326        <T as CombineAttributeParser<S>>::TEMPLATE,
327        |group: &mut Combine<T, S>, cx, args| {
328            // Keep track of the span of the first attribute, for diagnostics
329            group.first_span.get_or_insert(cx.attr_span);
330            group.items.extend(T::extend(cx, args))
331        },
332    )];
333
334    fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
335        if let Some(first_span) = self.first_span {
336            Some(T::CONVERT(self.items, first_span))
337        } else {
338            None
339        }
340    }
341}
rustc_attr_parsing/attributes/mod.rs

rustc_attr_parsing/attributes/
mod.rs
