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]
90macro_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>>(
100            span: __S,
101        ) -> $ident {
102            $ident {
103                span: $crate::__private::IntoSpans::into_spans(span),
104            }
105        }
106
107        const _: () = {
108            impl $crate::__private::Default for $ident {
109                fn default() -> Self {
110                    $ident {
111                        span: $crate::__private::Span::call_site(),
112                    }
113                }
114            }
115
116            $crate::impl_parse_for_custom_keyword!($ident);
117            $crate::impl_to_tokens_for_custom_keyword!($ident);
118            $crate::impl_clone_for_custom_keyword!($ident);
119            $crate::impl_extra_traits_for_custom_keyword!($ident);
120        };
121    };
122}
123
124// Not public API.
125#[cfg(feature = "parsing")]
126#[doc(hidden)]
127#[macro_export]
128macro_rules! impl_parse_for_custom_keyword {
129    ($ident:ident) => {
130        // For peek.
131        impl $crate::__private::CustomToken for $ident {
132            fn peek(cursor: $crate::buffer::Cursor) -> $crate::__private::bool {
133                if let $crate::__private::Some((ident, _rest)) = cursor.ident() {
134                    ident == $crate::__private::stringify!($ident)
135                } else {
136                    false
137                }
138            }
139
140            fn display() -> &'static $crate::__private::str {
141                $crate::__private::concat!("`", $crate::__private::stringify!($ident), "`")
142            }
143        }
144
145        impl $crate::parse::Parse for $ident {
146            fn parse(input: $crate::parse::ParseStream) -> $crate::parse::Result<$ident> {
147                input.step(|cursor| {
148                    if let $crate::__private::Some((ident, rest)) = cursor.ident() {
149                        if ident == $crate::__private::stringify!($ident) {
150                            return $crate::__private::Ok(($ident { span: ident.span() }, rest));
151                        }
152                    }
153                    $crate::__private::Err(cursor.error($crate::__private::concat!(
154                        "expected `",
155                        $crate::__private::stringify!($ident),
156                        "`",
157                    )))
158                })
159            }
160        }
161    };
162}
163
164// Not public API.
165#[cfg(not(feature = "parsing"))]
166#[doc(hidden)]
167#[macro_export]
168macro_rules! impl_parse_for_custom_keyword {
169    ($ident:ident) => {};
170}
171
172// Not public API.
173#[cfg(feature = "printing")]
174#[doc(hidden)]
175#[macro_export]
176macro_rules! impl_to_tokens_for_custom_keyword {
177    ($ident:ident) => {
178        impl $crate::__private::ToTokens for $ident {
179            fn to_tokens(&self, tokens: &mut $crate::__private::TokenStream2) {
180                let ident = $crate::Ident::new($crate::__private::stringify!($ident), self.span);
181                $crate::__private::TokenStreamExt::append(tokens, ident);
182            }
183        }
184    };
185}
186
187// Not public API.
188#[cfg(not(feature = "printing"))]
189#[doc(hidden)]
190#[macro_export]
191macro_rules! impl_to_tokens_for_custom_keyword {
192    ($ident:ident) => {};
193}
194
195// Not public API.
196#[cfg(feature = "clone-impls")]
197#[doc(hidden)]
198#[macro_export]
199macro_rules! impl_clone_for_custom_keyword {
200    ($ident:ident) => {
201        impl $crate::__private::Copy for $ident {}
202
203        #[allow(clippy::expl_impl_clone_on_copy)]
204        impl $crate::__private::Clone for $ident {
205            fn clone(&self) -> Self {
206                *self
207            }
208        }
209    };
210}
211
212// Not public API.
213#[cfg(not(feature = "clone-impls"))]
214#[doc(hidden)]
215#[macro_export]
216macro_rules! impl_clone_for_custom_keyword {
217    ($ident:ident) => {};
218}
219
220// Not public API.
221#[cfg(feature = "extra-traits")]
222#[doc(hidden)]
223#[macro_export]
224macro_rules! impl_extra_traits_for_custom_keyword {
225    ($ident:ident) => {
226        impl $crate::__private::Debug for $ident {
227            fn fmt(&self, f: &mut $crate::__private::Formatter) -> $crate::__private::FmtResult {
228                $crate::__private::Formatter::write_str(
229                    f,
230                    $crate::__private::concat!(
231                        "Keyword [",
232                        $crate::__private::stringify!($ident),
233                        "]",
234                    ),
235                )
236            }
237        }
238
239        impl $crate::__private::Eq for $ident {}
240
241        impl $crate::__private::PartialEq for $ident {
242            fn eq(&self, _other: &Self) -> $crate::__private::bool {
243                true
244            }
245        }
246
247        impl $crate::__private::Hash for $ident {
248            fn hash<__H: $crate::__private::Hasher>(&self, _state: &mut __H) {}
249        }
250    };
251}
252
253// Not public API.
254#[cfg(not(feature = "extra-traits"))]
255#[doc(hidden)]
256#[macro_export]
257macro_rules! impl_extra_traits_for_custom_keyword {
258    ($ident:ident) => {};
259}
260