syn/custom_keyword.rs
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]: parse::ParseBuffer::peek
30/// [Parsing]: 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(local_inner_macros)]
90macro_rules! custom_keyword {
91 ($ident:ident) => {
92 #[allow(non_camel_case_types)]
93 pub struct $ident {
94 pub span: $crate::export::Span,
95 }
96
97 #[doc(hidden)]
98 #[allow(non_snake_case)]
99 pub fn $ident<__S: $crate::export::IntoSpans<[$crate::export::Span; 1]>>(
100 span: __S,
101 ) -> $ident {
102 $ident {
103 span: $crate::export::IntoSpans::into_spans(span)[0],
104 }
105 }
106
107 impl $crate::export::Default for $ident {
108 fn default() -> Self {
109 $ident {
110 span: $crate::export::Span::call_site(),
111 }
112 }
113 }
114
115 impl_parse_for_custom_keyword!($ident);
116 impl_to_tokens_for_custom_keyword!($ident);
117 impl_clone_for_custom_keyword!($ident);
118 impl_extra_traits_for_custom_keyword!($ident);
119 };
120}
121
122// Not public API.
123#[cfg(feature = "parsing")]
124#[doc(hidden)]
125#[macro_export]
126macro_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::export::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::export::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::export::Some((ident, rest)) = cursor.ident() {
147 if ident == stringify!($ident) {
148 return $crate::export::Ok(($ident { span: ident.span() }, rest));
149 }
150 }
151 $crate::export::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]
166macro_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]
174macro_rules! impl_to_tokens_for_custom_keyword {
175 ($ident:ident) => {
176 impl $crate::export::ToTokens for $ident {
177 fn to_tokens(&self, tokens: &mut $crate::export::TokenStream2) {
178 let ident = $crate::Ident::new(stringify!($ident), self.span);
179 $crate::export::TokenStreamExt::append(tokens, ident);
180 }
181 }
182 };
183}
184
185// Not public API.
186#[cfg(not(feature = "printing"))]
187#[doc(hidden)]
188#[macro_export]
189macro_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]
197macro_rules! impl_clone_for_custom_keyword {
198 ($ident:ident) => {
199 impl $crate::export::Copy for $ident {}
200
201 impl $crate::export::Clone for $ident {
202 fn clone(&self) -> Self {
203 *self
204 }
205 }
206 };
207}
208
209// Not public API.
210#[cfg(not(feature = "clone-impls"))]
211#[doc(hidden)]
212#[macro_export]
213macro_rules! impl_clone_for_custom_keyword {
214 ($ident:ident) => {};
215}
216
217// Not public API.
218#[cfg(feature = "extra-traits")]
219#[doc(hidden)]
220#[macro_export]
221macro_rules! impl_extra_traits_for_custom_keyword {
222 ($ident:ident) => {
223 impl $crate::export::Debug for $ident {
224 fn fmt(&self, f: &mut $crate::export::Formatter) -> $crate::export::fmt::Result {
225 $crate::export::Formatter::write_str(
226 f,
227 concat!("Keyword [", stringify!($ident), "]"),
228 )
229 }
230 }
231
232 impl $crate::export::Eq for $ident {}
233
234 impl $crate::export::PartialEq for $ident {
235 fn eq(&self, _other: &Self) -> $crate::export::bool {
236 true
237 }
238 }
239
240 impl $crate::export::Hash for $ident {
241 fn hash<__H: $crate::export::Hasher>(&self, _state: &mut __H) {}
242 }
243 };
244}
245
246// Not public API.
247#[cfg(not(feature = "extra-traits"))]
248#[doc(hidden)]
249#[macro_export]
250macro_rules! impl_extra_traits_for_custom_keyword {
251 ($ident:ident) => {};
252}