1//! This module defines traits for attribute parsers, little state machines that recognize and parse2//! 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`](crate::attributes::SingleAttributeParser): makes it easy to implement an attribute which should error if it11//! appears more than once in a list of attributes12//! - [`CombineAttributeParser`](crate::attributes::CombineAttributeParser): makes it easy to implement an attribute which should combine the13//! contents of attributes, if an attribute appear multiple times in a list14//!15//! Attributes should be added to `crate::context::ATTRIBUTE_PARSERS` to be parsed.1617use std::marker::PhantomData;1819use rustc_feature::{AttributeTemplate, template};20use rustc_hir::attrs::AttributeKind;21use rustc_span::edition::Edition;22use rustc_span::{Span, Symbol};23use thin_vec::ThinVec;2425use crate::context::{AcceptContext, FinalizeContext};26use crate::parser::ArgParser;27use crate::session_diagnostics::UnusedMultiple;28use crate::target_checking::AllowedTargets;2930/// All the parsers require roughly the same imports, so this prelude has most of the often-needed ones.31mod prelude;3233pub(crate) mod allow_unstable;34pub(crate) mod autodiff;35pub(crate) mod body;36pub(crate) mod cfg;37pub(crate) mod cfg_select;38pub(crate) mod cfi_encoding;39pub(crate) mod codegen_attrs;40pub(crate) mod confusables;41pub(crate) mod crate_level;42pub(crate) mod debugger;43pub(crate) mod deprecation;44pub(crate) mod diagnostic;45pub(crate) mod doc;46pub(crate) mod dummy;47pub(crate) mod inline;48pub(crate) mod instruction_set;49pub(crate) mod link_attrs;50pub(crate) mod lint_helpers;51pub(crate) mod loop_match;52pub(crate) mod macro_attrs;53pub(crate) mod must_not_suspend;54pub(crate) mod must_use;55pub(crate) mod no_implicit_prelude;56pub(crate) mod no_link;57pub(crate) mod non_exhaustive;58pub(crate) mod path;59pub(crate) mod pin_v2;60pub(crate) mod proc_macro_attrs;61pub(crate) mod prototype;62pub(crate) mod repr;63pub(crate) mod rustc_allocator;64pub(crate) mod rustc_dump;65pub(crate) mod rustc_internal;66pub(crate) mod semantics;67pub(crate) mod stability;68pub(crate) mod test_attrs;69pub(crate) mod traits;70pub(crate) mod transparency;71pub(crate) mod util;7273type AcceptFn<T> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess>, &ArgParser);74type AcceptMapping<T> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T>)];7576/// An [`AttributeParser`] is a type which searches for syntactic attributes.77///78/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.79/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the80/// attribute it is looking for was not yet seen.81///82/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].83/// These are listed as pairs, of symbols and function pointers. The function pointer will84/// be called when that attribute is found on an item, which can influence the state of the little85/// state machine.86///87/// Finally, after all attributes on an item have been seen, and possibly been accepted,88/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report89/// whether it has seen the attribute it has been looking for.90///91/// The state machine is automatically reset to parse attributes on the next item.92///93/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]94/// or [`CombineAttributeParser`] instead.95pub(crate) trait AttributeParser: Default + 'static {96    /// The symbols for the attributes that this parser is interested in.97    ///98    /// If an attribute has this symbol, the `accept` function will be called on it.99    const ATTRIBUTES: AcceptMapping<Self>;100    const ALLOWED_TARGETS: AllowedTargets;101    const SAFETY: AttributeSafety = AttributeSafety::Normal;102103    /// The parser has gotten a chance to accept the attributes on an item,104    /// here it can produce an attribute.105    ///106    /// All finalize methods of all parsers are unconditionally called.107    /// This means you can't unconditionally return `Some` here,108    /// that'd be equivalent to unconditionally applying an attribute to109    /// every single syntax item that could have attributes applied to it.110    /// Your accept mappings should determine whether this returns something.111    fn finalize(self, cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind>;112}113114/// Alternative to [`AttributeParser`] that automatically handles state management.115/// A slightly simpler and more restricted way to convert attributes.116/// Assumes that an attribute can only appear a single time on an item,117/// and errors when it sees more.118///119/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].120///121/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple122/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.123pub(crate) trait SingleAttributeParser: 'static {124    /// The single path of the attribute this parser accepts.125    ///126    /// If you need the parser to accept more than one path, use [`AttributeParser`] instead127    const PATH: &[Symbol];128129    /// Configures what to do when when the same attribute is130    /// applied more than once on the same syntax node.131    const ON_DUPLICATE: OnDuplicate = OnDuplicate::Error;132    const SAFETY: AttributeSafety = AttributeSafety::Normal;133134    const ALLOWED_TARGETS: AllowedTargets;135136    /// The template this attribute parser should implement. Used for diagnostics.137    const TEMPLATE: AttributeTemplate;138139    /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]140    fn convert(cx: &mut AcceptContext<'_, '_>, args: &ArgParser) -> Option<AttributeKind>;141}142143/// Use in combination with [`SingleAttributeParser`].144/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].145pub(crate) struct Single<T: SingleAttributeParser>(PhantomData<T>, Option<(AttributeKind, Span)>);146147impl<T: SingleAttributeParser> Default for Single<T> {148    fn default() -> Self {149        Self(Default::default(), Default::default())150    }151}152153impl<T: SingleAttributeParser> AttributeParser for Single<T> {154    const ATTRIBUTES: AcceptMapping<Self> =155        &[(T::PATH, <T as SingleAttributeParser>::TEMPLATE, |group: &mut Single<T>, cx, args| {156            if let Some(pa) = T::convert(cx, args) {157                if let Some((_, used)) = group.1 {158                    T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);159                } else {160                    group.1 = Some((pa, cx.attr_span));161                }162            }163        })];164    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;165    const SAFETY: AttributeSafety = T::SAFETY;166167    fn finalize(self, _cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind> {168        Some(self.1?.0)169    }170}171172pub(crate) enum OnDuplicate {173    /// Give a default warning174    Warn,175176    /// Duplicates will be a warning, with a note that this will be an error in the future.177    WarnButFutureError,178179    /// Give a default error180    Error,181182    /// Ignore duplicates183    Ignore,184185    /// Custom function called when a duplicate attribute is found.186    ///187    /// - `unused` is the span of the attribute that was unused or bad because of some188    ///   duplicate reason189    /// - `used` is the span of the attribute that was used in favor of the unused attribute190    Custom(fn(cx: &AcceptContext<'_, '_>, used: Span, unused: Span)),191}192193impl OnDuplicate {194    fn exec<P: SingleAttributeParser>(195        &self,196        cx: &mut AcceptContext<'_, '_>,197        used: Span,198        unused: Span,199    ) {200        match self {201            OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),202            OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),203            OnDuplicate::Error => {204                cx.emit_err(UnusedMultiple {205                    this: unused,206                    other: used,207                    name: Symbol::intern(208                        &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),209                    ),210                });211            }212            OnDuplicate::Ignore => {}213            OnDuplicate::Custom(f) => f(cx, used, unused),214        }215    }216}217218#[derive(Copy, Clone, PartialEq, Debug)]219pub enum AttributeSafety {220    /// Normal attribute that does not need `#[unsafe(...)]`221    Normal,222    /// Unsafe attribute that requires safety obligations to be discharged.223    ///224    /// An error is emitted when `#[unsafe(...)]` is omitted, except when the attribute's edition225    /// is less than the one stored in `unsafe_since`. This handles attributes that were safe in226    /// earlier editions, but become unsafe in later ones.227    Unsafe { unsafe_since: Option<Edition> },228}229230/// An even simpler version of [`SingleAttributeParser`]:231/// now automatically check that there are no arguments provided to the attribute.232///233/// [`WithoutArgs<T> where T: NoArgsAttributeParser`](WithoutArgs) implements [`SingleAttributeParser`].234//235pub(crate) trait NoArgsAttributeParser: 'static {236    const PATH: &[Symbol];237    const ON_DUPLICATE: OnDuplicate = OnDuplicate::Error;238    const ALLOWED_TARGETS: AllowedTargets;239    const SAFETY: AttributeSafety = AttributeSafety::Normal;240241    /// Create the [`AttributeKind`] given attribute's [`Span`].242    const CREATE: fn(Span) -> AttributeKind;243}244245pub(crate) struct WithoutArgs<T: NoArgsAttributeParser>(PhantomData<T>);246247impl<T: NoArgsAttributeParser> Default for WithoutArgs<T> {248    fn default() -> Self {249        Self(Default::default())250    }251}252253impl<T: NoArgsAttributeParser> SingleAttributeParser for WithoutArgs<T> {254    const PATH: &[Symbol] = T::PATH;255    const ON_DUPLICATE: OnDuplicate = T::ON_DUPLICATE;256    const SAFETY: AttributeSafety = T::SAFETY;257    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;258    const TEMPLATE: AttributeTemplate = template!(Word);259260    fn convert(cx: &mut AcceptContext<'_, '_>, args: &ArgParser) -> Option<AttributeKind> {261        let _ = cx.expect_no_args(args);262        Some(T::CREATE(cx.attr_span))263    }264}265266type ConvertFn<E> = fn(ThinVec<E>, Span) -> AttributeKind;267268/// Alternative to [`AttributeParser`] that automatically handles state management.269/// If multiple attributes appear on an element, combines the values of each into a270/// [`ThinVec`].271/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].272///273/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple274/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.275pub(crate) trait CombineAttributeParser: 'static {276    const PATH: &[rustc_span::Symbol];277278    type Item;279    /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.280    ///281    /// For example, individual representations from `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,282    ///  where `x` is a vec of these individual reprs.283    const CONVERT: ConvertFn<Self::Item>;284    const SAFETY: AttributeSafety = AttributeSafety::Normal;285286    const ALLOWED_TARGETS: AllowedTargets;287288    /// The template this attribute parser should implement. Used for diagnostics.289    const TEMPLATE: AttributeTemplate;290291    /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]292    fn extend(293        cx: &mut AcceptContext<'_, '_>,294        args: &ArgParser,295    ) -> impl IntoIterator<Item = Self::Item>;296}297298/// Use in combination with [`CombineAttributeParser`].299/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].300pub(crate) struct Combine<T: CombineAttributeParser> {301    phantom: PhantomData<T>,302    /// A list of all items produced by parsing attributes so far. One attribute can produce any amount of items.303    items: ThinVec<<T as CombineAttributeParser>::Item>,304    /// The full span of the first attribute that was encountered.305    first_span: Option<Span>,306}307308impl<T: CombineAttributeParser> Default for Combine<T> {309    fn default() -> Self {310        Self {311            phantom: Default::default(),312            items: Default::default(),313            first_span: Default::default(),314        }315    }316}317318impl<T: CombineAttributeParser> AttributeParser for Combine<T> {319    const ATTRIBUTES: AcceptMapping<Self> =320        &[(T::PATH, T::TEMPLATE, |group: &mut Combine<T>, cx, args| {321            // Keep track of the span of the first attribute, for diagnostics322            group.first_span.get_or_insert(cx.attr_span);323            group.items.extend(T::extend(cx, args))324        })];325    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;326    const SAFETY: AttributeSafety = T::SAFETY;327328    fn finalize(self, _cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind> {329        if let Some(first_span) = self.first_span {330            Some(T::CONVERT(self.items, first_span))331        } else {332            None333        }334    }335}