1 /// Define a type that supports parsing and printing a given identifier as if it
2 /// were a keyword.
3 ///
4 /// # Usage
5 ///
6 /// As a convention, it is recommended that this macro be invoked within a
7 /// module called `kw` or `keyword` and that the resulting parser be invoked
8 /// with a `kw::` or `keyword::` prefix.
9 ///
10 /// ```
11 /// mod kw {
12 ///     syn::custom_keyword!(whatever);
13 /// }
14 /// ```
15 ///
16 /// The generated syntax tree node supports the following operations just like
17 /// any built-in keyword token.
18 ///
19 /// - [Peeking] — `input.peek(kw::whatever)`
20 ///
21 /// - [Parsing] — `input.parse::<kw::whatever>()?`
22 ///
23 /// - [Printing] — `quote!( ... #whatever_token ... )`
24 ///
25 /// - Construction from a [`Span`] — `let whatever_token = kw::whatever(sp)`
26 ///
27 /// - Field access to its span — `let sp = whatever_token.span`
28 ///
29 /// [Peeking]: crate::parse::ParseBuffer::peek
30 /// [Parsing]: crate::parse::ParseBuffer::parse
31 /// [Printing]: quote::ToTokens
32 /// [`Span`]: proc_macro2::Span
33 ///
34 /// # Example
35 ///
36 /// This example parses input that looks like `bool = true` or `str = "value"`.
37 /// The key must be either the identifier `bool` or the identifier `str`. If
38 /// `bool`, the value may be either `true` or `false`. If `str`, the value may
39 /// be any string literal.
40 ///
41 /// The symbols `bool` and `str` are not reserved keywords in Rust so these are
42 /// not considered keywords in the `syn::token` module. Like any other
43 /// identifier that is not a keyword, these can be declared as custom keywords
44 /// by crates that need to use them as such.
45 ///
46 /// ```
47 /// use syn::{LitBool, LitStr, Result, Token};
48 /// use syn::parse::{Parse, ParseStream};
49 ///
50 /// mod kw {
51 ///     syn::custom_keyword!(bool);
52 ///     syn::custom_keyword!(str);
53 /// }
54 ///
55 /// enum Argument {
56 ///     Bool {
57 ///         bool_token: kw::bool,
58 ///         eq_token: Token![=],
59 ///         value: LitBool,
60 ///     },
61 ///     Str {
62 ///         str_token: kw::str,
63 ///         eq_token: Token![=],
64 ///         value: LitStr,
65 ///     },
66 /// }
67 ///
68 /// impl Parse for Argument {
69 ///     fn parse(input: ParseStream) -> Result<Self> {
70 ///         let lookahead = input.lookahead1();
71 ///         if lookahead.peek(kw::bool) {
72 ///             Ok(Argument::Bool {
73 ///                 bool_token: input.parse::<kw::bool>()?,
74 ///                 eq_token: input.parse()?,
75 ///                 value: input.parse()?,
76 ///             })
77 ///         } else if lookahead.peek(kw::str) {
78 ///             Ok(Argument::Str {
79 ///                 str_token: input.parse::<kw::str>()?,
80 ///                 eq_token: input.parse()?,
81 ///                 value: input.parse()?,
82 ///             })
83 ///         } else {
84 ///             Err(lookahead.error())
85 ///         }
86 ///     }
87 /// }
88 /// ```
89 #[macro_export]
90 macro_rules! custom_keyword {
91     ($ident:ident) => {
92         #[allow(non_camel_case_types)]
93         pub struct $ident {
94             pub span: $crate::__private::Span,
95         }
96 
97         #[doc(hidden)]
98         #[allow(dead_code, non_snake_case)]
99         pub fn $ident<__S: $crate::__private::IntoSpans<[$crate::__private::Span; 1]>>(
100             span: __S,
101         ) -> $ident {
102             $ident {
103                 span: $crate::__private::IntoSpans::into_spans(span)[0],
104             }
105         }
106 
107         impl $crate::__private::Default for $ident {
108             fn default() -> Self {
109                 $ident {
110                     span: $crate::__private::Span::call_site(),
111                 }
112             }
113         }
114 
115         $crate::impl_parse_for_custom_keyword!($ident);
116         $crate::impl_to_tokens_for_custom_keyword!($ident);
117         $crate::impl_clone_for_custom_keyword!($ident);
118         $crate::impl_extra_traits_for_custom_keyword!($ident);
119     };
120 }
121 
122 // Not public API.
123 #[cfg(feature = "parsing")]
124 #[doc(hidden)]
125 #[macro_export]
126 macro_rules! impl_parse_for_custom_keyword {
127     ($ident:ident) => {
128         // For peek.
129         impl $crate::token::CustomToken for $ident {
130             fn peek(cursor: $crate::buffer::Cursor) -> $crate::__private::bool {
131                 if let Some((ident, _rest)) = cursor.ident() {
132                     ident == stringify!($ident)
133                 } else {
134                     false
135                 }
136             }
137 
138             fn display() -> &'static $crate::__private::str {
139                 concat!("`", stringify!($ident), "`")
140             }
141         }
142 
143         impl $crate::parse::Parse for $ident {
144             fn parse(input: $crate::parse::ParseStream) -> $crate::parse::Result<$ident> {
145                 input.step(|cursor| {
146                     if let $crate::__private::Some((ident, rest)) = cursor.ident() {
147                         if ident == stringify!($ident) {
148                             return $crate::__private::Ok(($ident { span: ident.span() }, rest));
149                         }
150                     }
151                     $crate::__private::Err(cursor.error(concat!(
152                         "expected `",
153                         stringify!($ident),
154                         "`"
155                     )))
156                 })
157             }
158         }
159     };
160 }
161 
162 // Not public API.
163 #[cfg(not(feature = "parsing"))]
164 #[doc(hidden)]
165 #[macro_export]
166 macro_rules! impl_parse_for_custom_keyword {
167     ($ident:ident) => {};
168 }
169 
170 // Not public API.
171 #[cfg(feature = "printing")]
172 #[doc(hidden)]
173 #[macro_export]
174 macro_rules! impl_to_tokens_for_custom_keyword {
175     ($ident:ident) => {
176         impl $crate::__private::ToTokens for $ident {
177             fn to_tokens(&self, tokens: &mut $crate::__private::TokenStream2) {
178                 let ident = $crate::Ident::new(stringify!($ident), self.span);
179                 $crate::__private::TokenStreamExt::append(tokens, ident);
180             }
181         }
182     };
183 }
184 
185 // Not public API.
186 #[cfg(not(feature = "printing"))]
187 #[doc(hidden)]
188 #[macro_export]
189 macro_rules! impl_to_tokens_for_custom_keyword {
190     ($ident:ident) => {};
191 }
192 
193 // Not public API.
194 #[cfg(feature = "clone-impls")]
195 #[doc(hidden)]
196 #[macro_export]
197 macro_rules! impl_clone_for_custom_keyword {
198     ($ident:ident) => {
199         impl $crate::__private::Copy for $ident {}
200 
201         #[allow(clippy::expl_impl_clone_on_copy)]
202         impl $crate::__private::Clone for $ident {
203             fn clone(&self) -> Self {
204                 *self
205             }
206         }
207     };
208 }
209 
210 // Not public API.
211 #[cfg(not(feature = "clone-impls"))]
212 #[doc(hidden)]
213 #[macro_export]
214 macro_rules! impl_clone_for_custom_keyword {
215     ($ident:ident) => {};
216 }
217 
218 // Not public API.
219 #[cfg(feature = "extra-traits")]
220 #[doc(hidden)]
221 #[macro_export]
222 macro_rules! impl_extra_traits_for_custom_keyword {
223     ($ident:ident) => {
224         impl $crate::__private::Debug for $ident {
225             fn fmt(&self, f: &mut $crate::__private::Formatter) -> $crate::__private::fmt::Result {
226                 $crate::__private::Formatter::write_str(
227                     f,
228                     concat!("Keyword [", stringify!($ident), "]"),
229                 )
230             }
231         }
232 
233         impl $crate::__private::Eq for $ident {}
234 
235         impl $crate::__private::PartialEq for $ident {
236             fn eq(&self, _other: &Self) -> $crate::__private::bool {
237                 true
238             }
239         }
240 
241         impl $crate::__private::Hash for $ident {
242             fn hash<__H: $crate::__private::Hasher>(&self, _state: &mut __H) {}
243         }
244     };
245 }
246 
247 // Not public API.
248 #[cfg(not(feature = "extra-traits"))]
249 #[doc(hidden)]
250 #[macro_export]
251 macro_rules! impl_extra_traits_for_custom_keyword {
252     ($ident:ident) => {};
253 }
254