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 /// ```edition2018
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 /// ```edition2018
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)]
78 macro_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)]
112 macro_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]
138 macro_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)]
146 macro_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]
160 macro_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]
168 macro_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]
184 macro_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]
192 macro_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]
218 macro_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)]
225 macro_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 #[cfg_attr(rustfmt, rustfmt_skip)]
235 macro_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]
288 macro_rules! custom_punctuation_unexpected {
289     () => {};
290 }
291 
292 // Not public API.
293 #[doc(hidden)]
294 #[macro_export]
295 macro_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]
305 macro_rules! custom_punctuation_concat {
306     ($($tt:tt)*) => {
307         concat!($($tt)*)
308     };
309 }
310