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