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_attr_data_structures::lints::AttributeLintKind;
21use rustc_feature::AttributeTemplate;
22use rustc_span::{Span, Symbol};
23use thin_vec::ThinVec;
24
25use crate::context::{AcceptContext, FinalizeContext, Stage};
26use crate::parser::ArgParser;
27use crate::session_diagnostics::UnusedMultiple;
28
29pub(crate) mod allow_unstable;
30pub(crate) mod cfg;
31pub(crate) mod codegen_attrs;
32pub(crate) mod confusables;
33pub(crate) mod deprecation;
34pub(crate) mod inline;
35pub(crate) mod lint_helpers;
36pub(crate) mod must_use;
37pub(crate) mod repr;
38pub(crate) mod semantics;
39pub(crate) mod stability;
40pub(crate) mod transparency;
41pub(crate) mod util;
42
43type AcceptFn<T, S> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess, S>, &ArgParser<'_>);
44type AcceptMapping<T, S> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T, S>)];
45
46/// An [`AttributeParser`] is a type which searches for syntactic attributes.
47///
48/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
49/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
50/// attribute it is looking for was not yet seen.
51///
52/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].
53/// These are listed as pairs, of symbols and function pointers. The function pointer will
54/// be called when that attribute is found on an item, which can influence the state of the little
55/// state machine.
56///
57/// Finally, after all attributes on an item have been seen, and possibly been accepted,
58/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
59/// whether it has seen the attribute it has been looking for.
60///
61/// The state machine is automatically reset to parse attributes on the next item.
62///
63/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]
64/// or [`CombineAttributeParser`] instead.
65pub(crate) trait AttributeParser<S: Stage>: Default + 'static {
66    /// The symbols for the attributes that this parser is interested in.
67    ///
68    /// If an attribute has this symbol, the `accept` function will be called on it.
69    const ATTRIBUTES: AcceptMapping<Self, S>;
70
71    /// The parser has gotten a chance to accept the attributes on an item,
72    /// here it can produce an attribute.
73    ///
74    /// All finalize methods of all parsers are unconditionally called.
75    /// This means you can't unconditionally return `Some` here,
76    /// that'd be equivalent to unconditionally applying an attribute to
77    /// every single syntax item that could have attributes applied to it.
78    /// Your accept mappings should determine whether this returns something.
79    fn finalize(self, cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind>;
80}
81
82/// Alternative to [`AttributeParser`] that automatically handles state management.
83/// A slightly simpler and more restricted way to convert attributes.
84/// Assumes that an attribute can only appear a single time on an item,
85/// and errors when it sees more.
86///
87/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
88///
89/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple
90/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
91pub(crate) trait SingleAttributeParser<S: Stage>: 'static {
92    /// The single path of the attribute this parser accepts.
93    ///
94    /// If you need the parser to accept more than one path, use [`AttributeParser`] instead
95    const PATH: &[Symbol];
96
97    /// Configures the precedence of attributes with the same `PATH` on a syntax node.
98    const ATTRIBUTE_ORDER: AttributeOrder;
99
100    /// Configures what to do when when the same attribute is
101    /// applied more than once on the same syntax node.
102    ///
103    /// [`ATTRIBUTE_ORDER`](Self::ATTRIBUTE_ORDER) specified which one is assumed to be correct,
104    /// and this specified whether to, for example, warn or error on the other one.
105    const ON_DUPLICATE: OnDuplicate<S>;
106
107    /// The template this attribute parser should implement. Used for diagnostics.
108    const TEMPLATE: AttributeTemplate;
109
110    /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
111    fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind>;
112}
113
114/// Use in combination with [`SingleAttributeParser`].
115/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].
116pub(crate) struct Single<T: SingleAttributeParser<S>, S: Stage>(
117    PhantomData<(S, T)>,
118    Option<(AttributeKind, Span)>,
119);
120
121impl<T: SingleAttributeParser<S>, S: Stage> Default for Single<T, S> {
122    fn default() -> Self {
123        Self(Default::default(), Default::default())
124    }
125}
126
127impl<T: SingleAttributeParser<S>, S: Stage> AttributeParser<S> for Single<T, S> {
128    const ATTRIBUTES: AcceptMapping<Self, S> = &[(
129        T::PATH,
130        <T as SingleAttributeParser<S>>::TEMPLATE,
131        |group: &mut Single<T, S>, cx, args| {
132            if let Some(pa) = T::convert(cx, args) {
133                match T::ATTRIBUTE_ORDER {
134                    // keep the first and report immediately. ignore this attribute
135                    AttributeOrder::KeepFirst => {
136                        if let Some((_, unused)) = group.1 {
137                            T::ON_DUPLICATE.exec::<T>(cx, cx.attr_span, unused);
138                            return;
139                        }
140                    }
141                    // keep the new one and warn about the previous,
142                    // then replace
143                    AttributeOrder::KeepLast => {
144                        if let Some((_, used)) = group.1 {
145                            T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);
146                        }
147                    }
148                }
149
150                group.1 = Some((pa, cx.attr_span));
151            }
152        },
153    )];
154
155    fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
156        Some(self.1?.0)
157    }
158}
159
160// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
161// them will be merged in another PR
162#[allow(unused)]
163pub(crate) enum OnDuplicate<S: Stage> {
164    /// Give a default warning
165    Warn,
166
167    /// Duplicates will be a warning, with a note that this will be an error in the future.
168    WarnButFutureError,
169
170    /// Give a default error
171    Error,
172
173    /// Ignore duplicates
174    Ignore,
175
176    /// Custom function called when a duplicate attribute is found.
177    ///
178    /// - `unused` is the span of the attribute that was unused or bad because of some
179    ///   duplicate reason (see [`AttributeOrder`])
180    /// - `used` is the span of the attribute that was used in favor of the unused attribute
181    Custom(fn(cx: &AcceptContext<'_, '_, S>, used: Span, unused: Span)),
182}
183
184impl<S: Stage> OnDuplicate<S> {
185    fn exec<P: SingleAttributeParser<S>>(
186        &self,
187        cx: &mut AcceptContext<'_, '_, S>,
188        used: Span,
189        unused: Span,
190    ) {
191        match self {
192            OnDuplicate::Warn => cx.emit_lint(
193                AttributeLintKind::UnusedDuplicate { this: unused, other: used, warning: false },
194                unused,
195            ),
196            OnDuplicate::WarnButFutureError => cx.emit_lint(
197                AttributeLintKind::UnusedDuplicate { this: unused, other: used, warning: true },
198                unused,
199            ),
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//
215// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
216// them will be merged in another PR
217#[allow(unused)]
218pub(crate) enum AttributeOrder {
219    /// Duplicates after the first attribute will be an error.
220    ///
221    /// This should be used where duplicates would be ignored, but carry extra
222    /// meaning that could cause confusion. For example, `#[stable(since="1.0")]
223    /// #[stable(since="2.0")]`, which version should be used for `stable`?
224    KeepFirst,
225
226    /// Duplicates preceding the last instance of the attribute will be a
227    /// warning, with a note that this will be an error in the future.
228    ///
229    /// This is the same as `FutureWarnFollowing`, except the last attribute is
230    /// the one that is "used". Ideally these can eventually migrate to
231    /// `ErrorPreceding`.
232    KeepLast,
233}
234
235type ConvertFn<E> = fn(ThinVec<E>) -> AttributeKind;
236
237/// Alternative to [`AttributeParser`] that automatically handles state management.
238/// If multiple attributes appear on an element, combines the values of each into a
239/// [`ThinVec`].
240/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].
241///
242/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple
243/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
244pub(crate) trait CombineAttributeParser<S: Stage>: 'static {
245    const PATH: &[rustc_span::Symbol];
246
247    type Item;
248    /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.
249    ///
250    /// For example, individual representations fomr `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,
251    ///  where `x` is a vec of these individual reprs.
252    const CONVERT: ConvertFn<Self::Item>;
253
254    /// The template this attribute parser should implement. Used for diagnostics.
255    const TEMPLATE: AttributeTemplate;
256
257    /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
258    fn extend<'c>(
259        cx: &'c mut AcceptContext<'_, '_, S>,
260        args: &'c ArgParser<'_>,
261    ) -> impl IntoIterator<Item = Self::Item> + 'c;
262}
263
264/// Use in combination with [`CombineAttributeParser`].
265/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].
266pub(crate) struct Combine<T: CombineAttributeParser<S>, S: Stage>(
267    PhantomData<(S, T)>,
268    ThinVec<<T as CombineAttributeParser<S>>::Item>,
269);
270
271impl<T: CombineAttributeParser<S>, S: Stage> Default for Combine<T, S> {
272    fn default() -> Self {
273        Self(Default::default(), Default::default())
274    }
275}
276
277impl<T: CombineAttributeParser<S>, S: Stage> AttributeParser<S> for Combine<T, S> {
278    const ATTRIBUTES: AcceptMapping<Self, S> = &[(
279        T::PATH,
280        <T as CombineAttributeParser<S>>::TEMPLATE,
281        |group: &mut Combine<T, S>, cx, args| group.1.extend(T::extend(cx, args)),
282    )];
283
284    fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
285        if self.1.is_empty() { None } else { Some(T::CONVERT(self.1)) }
286    }
287}
rustc_attr_parsing/attributes/mod.rs

rustc_attr_parsing/attributes/
mod.rs
