custom_keyword.rs

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