syn/
custom_punctuation.rs

1/// Define a type that supports parsing and printing a multi-character symbol
2/// as if it were a punctuation token.
3///
4/// # Usage
5///
6/// ```
7/// syn::custom_punctuation!(LeftRightArrow, <=>);
8/// ```
9///
10/// The generated syntax tree node supports the following operations just like
11/// any built-in punctuation token.
12///
13/// - [Peeking] — `input.peek(LeftRightArrow)`
14///
15/// - [Parsing] — `input.parse::<LeftRightArrow>()?`
16///
17/// - [Printing] — `quote!( ... #lrarrow ... )`
18///
19/// - Construction from a [`Span`] — `let lrarrow = LeftRightArrow(sp)`
20///
21/// - Construction from multiple [`Span`] — `let lrarrow = LeftRightArrow([sp, sp, sp])`
22///
23/// - Field access to its spans — `let spans = lrarrow.spans`
24///
25/// [Peeking]: parse::ParseBuffer::peek
26/// [Parsing]: parse::ParseBuffer::parse
27/// [Printing]: quote::ToTokens
28/// [`Span`]: proc_macro2::Span
29///
30/// # Example
31///
32/// ```
33/// use proc_macro2::{TokenStream, TokenTree};
34/// use syn::parse::{Parse, ParseStream, Peek, Result};
35/// use syn::punctuated::Punctuated;
36/// use syn::Expr;
37///
38/// syn::custom_punctuation!(PathSeparator, </>);
39///
40/// // expr </> expr </> expr ...
41/// struct PathSegments {
42///     segments: Punctuated<Expr, PathSeparator>,
43/// }
44///
45/// impl Parse for PathSegments {
46///     fn parse(input: ParseStream) -> Result<Self> {
47///         let mut segments = Punctuated::new();
48///
49///         let first = parse_until(input, PathSeparator)?;
50///         segments.push_value(syn::parse2(first)?);
51///
52///         while input.peek(PathSeparator) {
53///             segments.push_punct(input.parse()?);
54///
55///             let next = parse_until(input, PathSeparator)?;
56///             segments.push_value(syn::parse2(next)?);
57///         }
58///
59///         Ok(PathSegments { segments })
60///     }
61/// }
62///
63/// fn parse_until<E: Peek>(input: ParseStream, end: E) -> Result<TokenStream> {
64///     let mut tokens = TokenStream::new();
65///     while !input.is_empty() && !input.peek(end) {
66///         let next: TokenTree = input.parse()?;
67///         tokens.extend(Some(next));
68///     }
69///     Ok(tokens)
70/// }
71///
72/// fn main() {
73///     let input = r#" a::b </> c::d::e "#;
74///     let _: PathSegments = syn::parse_str(input).unwrap();
75/// }
76/// ```
77#[macro_export(local_inner_macros)]
78macro_rules! custom_punctuation {
79    ($ident:ident, $($tt:tt)+) => {
80        pub struct $ident {
81            pub spans: custom_punctuation_repr!($($tt)+),
82        }
83
84        #[doc(hidden)]
85        #[allow(non_snake_case)]
86        pub fn $ident<__S: $crate::export::IntoSpans<custom_punctuation_repr!($($tt)+)>>(
87            spans: __S,
88        ) -> $ident {
89            let _validate_len = 0 $(+ custom_punctuation_len!(strict, $tt))*;
90            $ident {
91                spans: $crate::export::IntoSpans::into_spans(spans)
92            }
93        }
94
95        impl $crate::export::Default for $ident {
96            fn default() -> Self {
97                $ident($crate::export::Span::call_site())
98            }
99        }
100
101        impl_parse_for_custom_punctuation!($ident, $($tt)+);
102        impl_to_tokens_for_custom_punctuation!($ident, $($tt)+);
103        impl_clone_for_custom_punctuation!($ident, $($tt)+);
104        impl_extra_traits_for_custom_punctuation!($ident, $($tt)+);
105    };
106}
107
108// Not public API.
109#[cfg(feature = "parsing")]
110#[doc(hidden)]
111#[macro_export(local_inner_macros)]
112macro_rules! impl_parse_for_custom_punctuation {
113    ($ident:ident, $($tt:tt)+) => {
114        impl $crate::token::CustomToken for $ident {
115            fn peek(cursor: $crate::buffer::Cursor) -> bool {
116                $crate::token::parsing::peek_punct(cursor, stringify_punct!($($tt)+))
117            }
118
119            fn display() -> &'static $crate::export::str {
120                custom_punctuation_concat!("`", stringify_punct!($($tt)+), "`")
121            }
122        }
123
124        impl $crate::parse::Parse for $ident {
125            fn parse(input: $crate::parse::ParseStream) -> $crate::parse::Result<$ident> {
126                let spans: custom_punctuation_repr!($($tt)+) =
127                    $crate::token::parsing::punct(input, stringify_punct!($($tt)+))?;
128                Ok($ident(spans))
129            }
130        }
131    };
132}
133
134// Not public API.
135#[cfg(not(feature = "parsing"))]
136#[doc(hidden)]
137#[macro_export]
138macro_rules! impl_parse_for_custom_punctuation {
139    ($ident:ident, $($tt:tt)+) => {};
140}
141
142// Not public API.
143#[cfg(feature = "printing")]
144#[doc(hidden)]
145#[macro_export(local_inner_macros)]
146macro_rules! impl_to_tokens_for_custom_punctuation {
147    ($ident:ident, $($tt:tt)+) => {
148        impl $crate::export::ToTokens for $ident {
149            fn to_tokens(&self, tokens: &mut $crate::export::TokenStream2) {
150                $crate::token::printing::punct(stringify_punct!($($tt)+), &self.spans, tokens)
151            }
152        }
153    };
154}
155
156// Not public API.
157#[cfg(not(feature = "printing"))]
158#[doc(hidden)]
159#[macro_export]
160macro_rules! impl_to_tokens_for_custom_punctuation {
161    ($ident:ident, $($tt:tt)+) => {};
162}
163
164// Not public API.
165#[cfg(feature = "clone-impls")]
166#[doc(hidden)]
167#[macro_export]
168macro_rules! impl_clone_for_custom_punctuation {
169    ($ident:ident, $($tt:tt)+) => {
170        impl $crate::export::Copy for $ident {}
171
172        impl $crate::export::Clone for $ident {
173            fn clone(&self) -> Self {
174                *self
175            }
176        }
177    };
178}
179
180// Not public API.
181#[cfg(not(feature = "clone-impls"))]
182#[doc(hidden)]
183#[macro_export]
184macro_rules! impl_clone_for_custom_punctuation {
185    ($ident:ident, $($tt:tt)+) => {};
186}
187
188// Not public API.
189#[cfg(feature = "extra-traits")]
190#[doc(hidden)]
191#[macro_export]
192macro_rules! impl_extra_traits_for_custom_punctuation {
193    ($ident:ident, $($tt:tt)+) => {
194        impl $crate::export::Debug for $ident {
195            fn fmt(&self, f: &mut $crate::export::Formatter) -> $crate::export::fmt::Result {
196                $crate::export::Formatter::write_str(f, stringify!($ident))
197            }
198        }
199
200        impl $crate::export::Eq for $ident {}
201
202        impl $crate::export::PartialEq for $ident {
203            fn eq(&self, _other: &Self) -> $crate::export::bool {
204                true
205            }
206        }
207
208        impl $crate::export::Hash for $ident {
209            fn hash<__H: $crate::export::Hasher>(&self, _state: &mut __H) {}
210        }
211    };
212}
213
214// Not public API.
215#[cfg(not(feature = "extra-traits"))]
216#[doc(hidden)]
217#[macro_export]
218macro_rules! impl_extra_traits_for_custom_punctuation {
219    ($ident:ident, $($tt:tt)+) => {};
220}
221
222// Not public API.
223#[doc(hidden)]
224#[macro_export(local_inner_macros)]
225macro_rules! custom_punctuation_repr {
226    ($($tt:tt)+) => {
227        [$crate::export::Span; 0 $(+ custom_punctuation_len!(lenient, $tt))+]
228    };
229}
230
231// Not public API.
232#[doc(hidden)]
233#[macro_export(local_inner_macros)]
234#[rustfmt::skip]
235macro_rules! custom_punctuation_len {
236    ($mode:ident, +)     => { 1 };
237    ($mode:ident, +=)    => { 2 };
238    ($mode:ident, &)     => { 1 };
239    ($mode:ident, &&)    => { 2 };
240    ($mode:ident, &=)    => { 2 };
241    ($mode:ident, @)     => { 1 };
242    ($mode:ident, !)     => { 1 };
243    ($mode:ident, ^)     => { 1 };
244    ($mode:ident, ^=)    => { 2 };
245    ($mode:ident, :)     => { 1 };
246    ($mode:ident, ::)    => { 2 };
247    ($mode:ident, ,)     => { 1 };
248    ($mode:ident, /)     => { 1 };
249    ($mode:ident, /=)    => { 2 };
250    ($mode:ident, .)     => { 1 };
251    ($mode:ident, ..)    => { 2 };
252    ($mode:ident, ...)   => { 3 };
253    ($mode:ident, ..=)   => { 3 };
254    ($mode:ident, =)     => { 1 };
255    ($mode:ident, ==)    => { 2 };
256    ($mode:ident, >=)    => { 2 };
257    ($mode:ident, >)     => { 1 };
258    ($mode:ident, <=)    => { 2 };
259    ($mode:ident, <)     => { 1 };
260    ($mode:ident, *=)    => { 2 };
261    ($mode:ident, !=)    => { 2 };
262    ($mode:ident, |)     => { 1 };
263    ($mode:ident, |=)    => { 2 };
264    ($mode:ident, ||)    => { 2 };
265    ($mode:ident, #)     => { 1 };
266    ($mode:ident, ?)     => { 1 };
267    ($mode:ident, ->)    => { 2 };
268    ($mode:ident, <-)    => { 2 };
269    ($mode:ident, %)     => { 1 };
270    ($mode:ident, %=)    => { 2 };
271    ($mode:ident, =>)    => { 2 };
272    ($mode:ident, ;)     => { 1 };
273    ($mode:ident, <<)    => { 2 };
274    ($mode:ident, <<=)   => { 3 };
275    ($mode:ident, >>)    => { 2 };
276    ($mode:ident, >>=)   => { 3 };
277    ($mode:ident, *)     => { 1 };
278    ($mode:ident, -)     => { 1 };
279    ($mode:ident, -=)    => { 2 };
280    ($mode:ident, ~)     => { 1 };
281    (lenient, $tt:tt)    => { 0 };
282    (strict, $tt:tt)     => {{ custom_punctuation_unexpected!($tt); 0 }};
283}
284
285// Not public API.
286#[doc(hidden)]
287#[macro_export]
288macro_rules! custom_punctuation_unexpected {
289    () => {};
290}
291
292// Not public API.
293#[doc(hidden)]
294#[macro_export]
295macro_rules! stringify_punct {
296    ($($tt:tt)+) => {
297        concat!($(stringify!($tt)),+)
298    };
299}
300
301// Not public API.
302// Without this, local_inner_macros breaks when looking for concat!
303#[doc(hidden)]
304#[macro_export]
305macro_rules! custom_punctuation_concat {
306    ($($tt:tt)*) => {
307        concat!($($tt)*)
308    };
309}