1//! Traits for parsing attributes.2//!3//! This module defines traits for attribute parsers, little state machines that recognize and parse4//! 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 and13//! accepts no arguments14//! - [`SingleAttributeParser`]: makes it easy to implement an attribute which should error if it15//! appears more than once in a list of attributes16//! - [`CombineAttributeParser`]: makes it easy to implement an attribute which should combine the17//! contents of attributes, if an attribute appear multiple times in a list18//!19//! Attributes should be added to `crate::context::ATTRIBUTE_PARSERS` to be parsed.2021use std::marker::PhantomData;2223use rustc_feature::AttributeStability;24use rustc_hir::attrs::AttributeKind;25use rustc_span::edition::Edition;26use rustc_span::{Span, Symbol};27use thin_vec::ThinVec;2829use crate::context::{AcceptContext, FinalizeContext};30use crate::parser::ArgParser;31use crate::session_diagnostics::UnusedMultiple;32use crate::target_checking::AllowedTargets;33use crate::{AttributeTemplate, template};3435/// All the parsers require roughly the same imports, so this prelude has most of the often-needed ones.36mod prelude;3738pub(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 unroll;78pub(crate) mod util;7980type AcceptFn<T> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess>, &ArgParser);81type AcceptMapping<T> =82    &'static [(&'static [Symbol], AttributeTemplate, AttributeStability, AcceptFn<T>)];8384/// An [`AttributeParser`] is a type which searches for syntactic attributes.85///86/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.87/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the88/// attribute it is looking for was not yet seen.89///90/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].91/// These are listed as pairs, of symbols and function pointers. The function pointer will92/// be called when that attribute is found on an item, which can influence the state of the little93/// state machine.94///95/// Finally, after all attributes on an item have been seen, and possibly been accepted,96/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report97/// whether it has seen the attribute it has been looking for.98///99/// The state machine is automatically reset to parse attributes on the next item.100///101/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]102/// or [`CombineAttributeParser`] instead.103pub(crate) trait AttributeParser: Default + 'static {104    /// The symbols for the attributes that this parser is interested in.105    ///106    /// If an attribute has this symbol, the `accept` function will be called on it.107    const ATTRIBUTES: AcceptMapping<Self>;108    const ALLOWED_TARGETS: AllowedTargets;109    const SAFETY: AttributeSafety = AttributeSafety::Normal;110111    /// The parser has gotten a chance to accept the attributes on an item,112    /// here it can produce an attribute.113    ///114    /// All finalize methods of all parsers are unconditionally called.115    /// This means you can't unconditionally return `Some` here,116    /// that'd be equivalent to unconditionally applying an attribute to117    /// every single syntax item that could have attributes applied to it.118    /// Your accept mappings should determine whether this returns something.119    fn finalize(self, cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind>;120}121122/// Alternative to [`AttributeParser`] that automatically handles state management.123/// A slightly simpler and more restricted way to convert attributes.124/// Assumes that an attribute can only appear a single time on an item,125/// and errors when it sees more.126///127/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].128///129/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple130/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.131pub(crate) trait SingleAttributeParser: 'static {132    /// The single path of the attribute this parser accepts.133    ///134    /// If you need the parser to accept more than one path, use [`AttributeParser`] instead135    const PATH: &[Symbol];136137    /// Configures what to do when when the same attribute is138    /// applied more than once on the same syntax node.139    const ON_DUPLICATE: OnDuplicate = OnDuplicate::Error;140    const SAFETY: AttributeSafety = AttributeSafety::Normal;141    const STABILITY: AttributeStability;142143    const ALLOWED_TARGETS: AllowedTargets;144145    /// The template this attribute parser should implement. Used for diagnostics.146    const TEMPLATE: AttributeTemplate;147148    /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]149    fn convert(cx: &mut AcceptContext<'_, '_>, args: &ArgParser) -> Option<AttributeKind>;150}151152/// Use in combination with [`SingleAttributeParser`].153/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].154pub(crate) struct Single<T: SingleAttributeParser>(PhantomData<T>, Option<(AttributeKind, Span)>);155156impl<T: SingleAttributeParser> Default for Single<T> {157    fn default() -> Self {158        Self(Default::default(), Default::default())159    }160}161162impl<T: SingleAttributeParser> AttributeParser for Single<T> {163    const ATTRIBUTES: AcceptMapping<Self> = &[(164        T::PATH,165        <T as SingleAttributeParser>::TEMPLATE,166        T::STABILITY,167        |group: &mut Single<T>, cx, args| {168            if let Some(pa) = T::convert(cx, args) {169                if let Some((_, used)) = group.1 {170                    T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);171                } else {172                    group.1 = Some((pa, cx.attr_span));173                }174            }175        },176    )];177    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;178    const SAFETY: AttributeSafety = T::SAFETY;179180    fn finalize(self, _cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind> {181        Some(self.1?.0)182    }183}184185pub(crate) enum OnDuplicate {186    /// Give a default warning187    Warn,188189    /// Duplicates will be a warning, with a note that this will be an error in the future.190    WarnButFutureError,191192    /// Give a default error193    Error,194195    /// Ignore duplicates196    Ignore,197198    /// Custom function called when a duplicate attribute is found.199    ///200    /// - `unused` is the span of the attribute that was unused or bad because of some201    ///   duplicate reason202    /// - `used` is the span of the attribute that was used in favor of the unused attribute203    Custom(fn(cx: &AcceptContext<'_, '_>, used: Span, unused: Span)),204}205206impl OnDuplicate {207    fn exec<P: SingleAttributeParser>(208        &self,209        cx: &mut AcceptContext<'_, '_>,210        used: Span,211        unused: Span,212    ) {213        match self {214            OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),215            OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),216            OnDuplicate::Error => {217                cx.emit_err(UnusedMultiple {218                    this: unused,219                    other: used,220                    name: Symbol::intern(221                        &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),222                    ),223                });224            }225            OnDuplicate::Ignore => {}226            OnDuplicate::Custom(f) => f(cx, used, unused),227        }228    }229}230231#[derive(Copy, Clone, PartialEq, Debug)]232pub enum AttributeSafety {233    /// Normal attribute that does not need `#[unsafe(...)]`234    Normal,235    /// Unsafe attribute that requires safety obligations to be discharged.236    ///237    /// An error is emitted when `#[unsafe(...)]` is omitted, except when the attribute's edition238    /// is less than the one stored in `unsafe_since`. This handles attributes that were safe in239    /// earlier editions, but become unsafe in later ones.240    Unsafe {241        /// The `note` is emitted during the `unsafe_code`, and explains to the user why this attribute is unsafe.242        note: &'static str,243        unsafe_since: Option<Edition>,244    },245}246247/// An even simpler version of [`SingleAttributeParser`]:248/// now automatically check that there are no arguments provided to the attribute.249///250/// [`WithoutArgs<T> where T: NoArgsAttributeParser`](WithoutArgs) implements [`SingleAttributeParser`].251//252pub(crate) trait NoArgsAttributeParser: 'static {253    const PATH: &[Symbol];254    const ON_DUPLICATE: OnDuplicate = OnDuplicate::Error;255    const ALLOWED_TARGETS: AllowedTargets;256    const SAFETY: AttributeSafety = AttributeSafety::Normal;257    const STABILITY: AttributeStability;258259    /// Create the [`AttributeKind`] given attribute's [`Span`].260    const CREATE: fn(Span) -> AttributeKind;261}262263pub(crate) struct WithoutArgs<T: NoArgsAttributeParser>(PhantomData<T>);264265impl<T: NoArgsAttributeParser> Default for WithoutArgs<T> {266    fn default() -> Self {267        Self(Default::default())268    }269}270271impl<T: NoArgsAttributeParser> SingleAttributeParser for WithoutArgs<T> {272    const PATH: &[Symbol] = T::PATH;273    const ON_DUPLICATE: OnDuplicate = T::ON_DUPLICATE;274    const SAFETY: AttributeSafety = T::SAFETY;275    const STABILITY: AttributeStability = T::STABILITY;276    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;277    const TEMPLATE: AttributeTemplate = template!(Word);278279    fn convert(cx: &mut AcceptContext<'_, '_>, args: &ArgParser) -> Option<AttributeKind> {280        let _ = cx.expect_no_args(args);281        Some(T::CREATE(cx.attr_span))282    }283}284285type ConvertFn<E> = fn(ThinVec<E>, Span) -> AttributeKind;286287/// Alternative to [`AttributeParser`] that automatically handles state management.288/// If multiple attributes appear on an element, combines the values of each into a289/// [`ThinVec`].290/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].291///292/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple293/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.294pub(crate) trait CombineAttributeParser: 'static {295    const PATH: &[rustc_span::Symbol];296297    type Item;298    /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.299    ///300    /// For example, individual representations from `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,301    ///  where `x` is a vec of these individual reprs.302    const CONVERT: ConvertFn<Self::Item>;303    const SAFETY: AttributeSafety = AttributeSafety::Normal;304    const STABILITY: AttributeStability;305306    const ALLOWED_TARGETS: AllowedTargets;307308    /// The template this attribute parser should implement. Used for diagnostics.309    const TEMPLATE: AttributeTemplate;310311    /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]312    fn extend(313        cx: &mut AcceptContext<'_, '_>,314        args: &ArgParser,315    ) -> impl IntoIterator<Item = Self::Item>;316}317318/// Use in combination with [`CombineAttributeParser`].319/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].320pub(crate) struct Combine<T: CombineAttributeParser> {321    phantom: PhantomData<T>,322    /// A list of all items produced by parsing attributes so far. One attribute can produce any amount of items.323    items: ThinVec<<T as CombineAttributeParser>::Item>,324    /// The full span of the first attribute that was encountered.325    first_span: Option<Span>,326}327328impl<T: CombineAttributeParser> Default for Combine<T> {329    fn default() -> Self {330        Self {331            phantom: Default::default(),332            items: Default::default(),333            first_span: Default::default(),334        }335    }336}337338impl<T: CombineAttributeParser> AttributeParser for Combine<T> {339    const ATTRIBUTES: AcceptMapping<Self> =340        &[(T::PATH, T::TEMPLATE, T::STABILITY, |group: &mut Combine<T>, cx, args| {341            // Keep track of the span of the first attribute, for diagnostics342            group.first_span.get_or_insert(cx.attr_span);343            group.items.extend(T::extend(cx, args))344        })];345    const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;346    const SAFETY: AttributeSafety = T::SAFETY;347348    fn finalize(self, _cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind> {349        if let Some(first_span) = self.first_span {350            Some(T::CONVERT(self.items, first_span))351        } else {352            None353        }354    }355}