11//! Data structures for representing parsed attributes in the Rust compiler.
22//!
33//! For detailed documentation about attribute processing,
4- //! see [rustc_attr_parsing](https://doc.rust-lang.org/nightly/nightly-rustc /rustc_attr_parsing/index.html).
4+ //! see [rustc_attr_parsing](.. /rustc_attr_parsing/index.html).
55
66// tidy-alphabetical-start
77#![ feature( const_default) ]
@@ -20,7 +20,6 @@ pub use lang_items::*;
2020pub use pretty_printing:: PrintAttribute ;
2121pub use stability:: * ;
2222
23- // FIXME remove pub on some of these modules? It's fairly inconsistent.
2423mod attr;
2524mod canonical_symbols;
2625mod data_structures;
@@ -35,40 +34,38 @@ pub mod weak_lang_items;
3534
3635/// A trait for types that can provide a list of attributes given a `TyCtxt`.
3736///
38- /// It allows `find_attr!` to accept either a `DefId`, `LocalDefId`, `OwnerId`, or `HirId`.
39- /// It is defined here with a generic `Tcx` because `rustc_hir` can't depend on `rustc_middle`.
40- /// The concrete implementations are in `rustc_middle`.
37+ /// It is an implementation detail of the [`find_attr!`] macro to be able to accept either a
38+ /// [`DefId`], [`LocalDefId`], [`OwnerId`], or [`HirId`]. It is defined here with a generic `Tcx`
39+ /// because this crate can't depend on `rustc_middle`. The concrete implementations are in
40+ /// `rustc_middle`.
41+ ///
42+ /// Not to be confused with [`rustc_ast::ast_traits::HasAttrs`].
43+ ///
44+ /// [`DefId`]: rustc_span::def_id::DefId
45+ /// [`LocalDefId`]: rustc_span::def_id::LocalDefId
46+ /// [`OwnerId`]: ../rustc_hir/struct.OwnerId.html
47+ /// [`HirId`]: ../rustc_hir/struct.HirId.html
4148pub trait HasAttrs < ' tcx , Tcx > {
42- fn get_attrs ( self , tcx : & Tcx ) -> & ' tcx [ crate :: attr :: Attribute ] ;
49+ fn get_attrs ( self , tcx : & Tcx ) -> & ' tcx [ crate :: Attribute ] ;
4350}
4451
45- /// Finds attributes in sequences of attributes by pattern matching.
52+ /// Finds attributes by pattern matching.
4653///
4754/// A little like `matches` but for attributes.
4855///
49- /// ```rust,ignore (illustrative)
50- /// // finds the repr attribute
51- /// if let Some(r) = find_attr!(attrs, AttributeKind::Repr(r) => r) {
52- ///
53- /// }
54- ///
55- /// // checks if one has matched
56- /// if find_attr!(attrs, AttributeKind::Repr(_)) {
57- ///
58- /// }
59- /// ```
56+ /// Note that this macro accepts several "id" types: [`DefId`], [`LocalDefId`], [`OwnerId`] and
57+ /// [`HirId`].
6058///
61- /// Often this requires you to first end up with a list of attributes.
62- /// Often these are available through the `tcx`.
59+ /// # Examples
6360///
64- /// As a convenience, this macro can do that for you!
61+ /// It is most commonly used to check whether something has an attribute or to get its contents
62+ /// if it is present:
63+ /// ```rust,ignore (illustrative)
64+ /// let is_naked: bool = find_attr!(tcx, def_id, Naked(..));
6565///
66- /// Instead of providing an attribute list, provide the `tcx` and an id
67- /// (a `DefId`, `LocalDefId`, `OwnerId` or `HirId`).
66+ /// let is_visible: bool = find_attr!(tcx, def_id, Doc(doc) if doc.hidden.is_none());
6867///
69- /// ```rust,ignore (illustrative)
70- /// find_attr!(tcx, def_id, <pattern>)
71- /// find_attr!(tcx, hir_id, <pattern>)
68+ /// let link_name: Option<Symbol> = find_attr!(tcx, def_id, LinkName { name, .. } => *name);
7269/// ```
7370///
7471/// Another common case is finding attributes applied to the root of the current crate.
@@ -77,6 +74,27 @@ pub trait HasAttrs<'tcx, Tcx> {
7774/// ```rust, ignore (illustrative)
7875/// find_attr!(tcx, crate, <pattern>)
7976/// ```
77+ ///
78+ /// If you already have a list of attributes in scope, you can also use that:
79+ ///
80+ /// ```rust,ignore (illustrative)
81+ /// let attrs = <list of attributes>;
82+ ///
83+ /// // finds the repr attribute
84+ /// if let Some(r) = find_attr!(attrs, Repr(r) => r) {
85+ ///
86+ /// }
87+ ///
88+ /// // checks if one has matched
89+ /// if find_attr!(attrs, Repr(_)) {
90+ ///
91+ /// }
92+ /// ```
93+ ///
94+ /// [`DefId`]: rustc_span::def_id::DefId
95+ /// [`LocalDefId`]: rustc_span::def_id::LocalDefId
96+ /// [`OwnerId`]: ../rustc_hir/struct.OwnerId.html
97+ /// [`HirId`]: ../rustc_hir/struct.HirId.html
8098#[ macro_export]
8199macro_rules! find_attr {
82100 ( $tcx: expr, crate , $pattern: pat $( if $guard: expr) ?) => {
@@ -89,14 +107,14 @@ macro_rules! find_attr {
89107 ( $tcx: expr, $id: expr, $pattern: pat $( if $guard: expr) ?) => {
90108 $crate:: find_attr!( $tcx, $id, $pattern $( if $guard) ? => ( ) ) . is_some( )
91109 } ;
110+
92111 ( $tcx: expr, $id: expr, $pattern: pat $( if $guard: expr) ? => $e: expr) => { {
93112 $crate:: find_attr!(
94113 $crate:: HasAttrs :: get_attrs( $id, & $tcx) ,
95114 $pattern $( if $guard) ? => $e
96115 )
97116 } } ;
98117
99-
100118 ( $attributes_list: expr, $pattern: pat $( if $guard: expr) ?) => { {
101119 $crate:: find_attr!( $attributes_list, $pattern $( if $guard) ? => ( ) ) . is_some( )
102120 } } ;
0 commit comments