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>>( 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] 128 macro_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] 168 macro_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] 176 macro_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] 191 macro_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] 199 macro_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] 216 macro_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] 224 macro_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] 257 macro_rules! impl_extra_traits_for_custom_keyword { 258 ($ident:ident) => {}; 259 } 260