rustc_attr_parsing/attributes/
mod.rs

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

rustc_attr_parsing/attributes/
mod.rs
