1 | //! Parsing interface for parsing a token stream into a syntax tree node. |
2 | //! |
3 | //! Parsing in Syn is built on parser functions that take in a [`ParseStream`] |
4 | //! and produce a [`Result<T>`] where `T` is some syntax tree node. Underlying |
5 | //! these parser functions is a lower level mechanism built around the |
6 | //! [`Cursor`] type. `Cursor` is a cheaply copyable cursor over a range of |
7 | //! tokens in a token stream. |
8 | //! |
9 | //! [`Result<T>`]: Result |
10 | //! [`Cursor`]: crate::buffer::Cursor |
11 | //! |
12 | //! # Example |
13 | //! |
14 | //! Here is a snippet of parsing code to get a feel for the style of the |
15 | //! library. We define data structures for a subset of Rust syntax including |
16 | //! enums (not shown) and structs, then provide implementations of the [`Parse`] |
17 | //! trait to parse these syntax tree data structures from a token stream. |
18 | //! |
19 | //! Once `Parse` impls have been defined, they can be called conveniently from a |
20 | //! procedural macro through [`parse_macro_input!`] as shown at the bottom of |
21 | //! the snippet. If the caller provides syntactically invalid input to the |
22 | //! procedural macro, they will receive a helpful compiler error message |
23 | //! pointing out the exact token that triggered the failure to parse. |
24 | //! |
25 | //! [`parse_macro_input!`]: crate::parse_macro_input! |
26 | //! |
27 | //! ``` |
28 | //! # extern crate proc_macro; |
29 | //! # |
30 | //! use proc_macro::TokenStream; |
31 | //! use syn::{braced, parse_macro_input, token, Field, Ident, Result, Token}; |
32 | //! use syn::parse::{Parse, ParseStream}; |
33 | //! use syn::punctuated::Punctuated; |
34 | //! |
35 | //! enum Item { |
36 | //! Struct(ItemStruct), |
37 | //! Enum(ItemEnum), |
38 | //! } |
39 | //! |
40 | //! struct ItemStruct { |
41 | //! struct_token: Token![struct], |
42 | //! ident: Ident, |
43 | //! brace_token: token::Brace, |
44 | //! fields: Punctuated<Field, Token![,]>, |
45 | //! } |
46 | //! # |
47 | //! # enum ItemEnum {} |
48 | //! |
49 | //! impl Parse for Item { |
50 | //! fn parse(input: ParseStream) -> Result<Self> { |
51 | //! let lookahead = input.lookahead1(); |
52 | //! if lookahead.peek(Token![struct]) { |
53 | //! input.parse().map(Item::Struct) |
54 | //! } else if lookahead.peek(Token![enum]) { |
55 | //! input.parse().map(Item::Enum) |
56 | //! } else { |
57 | //! Err(lookahead.error()) |
58 | //! } |
59 | //! } |
60 | //! } |
61 | //! |
62 | //! impl Parse for ItemStruct { |
63 | //! fn parse(input: ParseStream) -> Result<Self> { |
64 | //! let content; |
65 | //! Ok(ItemStruct { |
66 | //! struct_token: input.parse()?, |
67 | //! ident: input.parse()?, |
68 | //! brace_token: braced!(content in input), |
69 | //! fields: content.parse_terminated(Field::parse_named)?, |
70 | //! }) |
71 | //! } |
72 | //! } |
73 | //! # |
74 | //! # impl Parse for ItemEnum { |
75 | //! # fn parse(input: ParseStream) -> Result<Self> { |
76 | //! # unimplemented!() |
77 | //! # } |
78 | //! # } |
79 | //! |
80 | //! # const IGNORE: &str = stringify! { |
81 | //! #[proc_macro] |
82 | //! # }; |
83 | //! pub fn my_macro(tokens: TokenStream) -> TokenStream { |
84 | //! let input = parse_macro_input!(tokens as Item); |
85 | //! |
86 | //! /* ... */ |
87 | //! # "" .parse().unwrap() |
88 | //! } |
89 | //! ``` |
90 | //! |
91 | //! # The `syn::parse*` functions |
92 | //! |
93 | //! The [`syn::parse`], [`syn::parse2`], and [`syn::parse_str`] functions serve |
94 | //! as an entry point for parsing syntax tree nodes that can be parsed in an |
95 | //! obvious default way. These functions can return any syntax tree node that |
96 | //! implements the [`Parse`] trait, which includes most types in Syn. |
97 | //! |
98 | //! [`syn::parse`]: crate::parse() |
99 | //! [`syn::parse2`]: crate::parse2() |
100 | //! [`syn::parse_str`]: crate::parse_str() |
101 | //! |
102 | //! ``` |
103 | //! use syn::Type; |
104 | //! |
105 | //! # fn run_parser() -> syn::Result<()> { |
106 | //! let t: Type = syn::parse_str("std::collections::HashMap<String, Value>" )?; |
107 | //! # Ok(()) |
108 | //! # } |
109 | //! # |
110 | //! # run_parser().unwrap(); |
111 | //! ``` |
112 | //! |
113 | //! The [`parse_quote!`] macro also uses this approach. |
114 | //! |
115 | //! [`parse_quote!`]: crate::parse_quote! |
116 | //! |
117 | //! # The `Parser` trait |
118 | //! |
119 | //! Some types can be parsed in several ways depending on context. For example |
120 | //! an [`Attribute`] can be either "outer" like `#[...]` or "inner" like |
121 | //! `#![...]` and parsing the wrong one would be a bug. Similarly [`Punctuated`] |
122 | //! may or may not allow trailing punctuation, and parsing it the wrong way |
123 | //! would either reject valid input or accept invalid input. |
124 | //! |
125 | //! [`Attribute`]: crate::Attribute |
126 | //! [`Punctuated`]: crate::punctuated |
127 | //! |
128 | //! The `Parse` trait is not implemented in these cases because there is no good |
129 | //! behavior to consider the default. |
130 | //! |
131 | //! ```compile_fail |
132 | //! # extern crate proc_macro; |
133 | //! # |
134 | //! # use syn::punctuated::Punctuated; |
135 | //! # use syn::{PathSegment, Result, Token}; |
136 | //! # |
137 | //! # fn f(tokens: proc_macro::TokenStream) -> Result<()> { |
138 | //! # |
139 | //! // Can't parse `Punctuated` without knowing whether trailing punctuation |
140 | //! // should be allowed in this context. |
141 | //! let path: Punctuated<PathSegment, Token![::]> = syn::parse(tokens)?; |
142 | //! # |
143 | //! # Ok(()) |
144 | //! # } |
145 | //! ``` |
146 | //! |
147 | //! In these cases the types provide a choice of parser functions rather than a |
148 | //! single `Parse` implementation, and those parser functions can be invoked |
149 | //! through the [`Parser`] trait. |
150 | //! |
151 | //! |
152 | //! ``` |
153 | //! # extern crate proc_macro; |
154 | //! # |
155 | //! use proc_macro::TokenStream; |
156 | //! use syn::parse::Parser; |
157 | //! use syn::punctuated::Punctuated; |
158 | //! use syn::{Attribute, Expr, PathSegment, Result, Token}; |
159 | //! |
160 | //! fn call_some_parser_methods(input: TokenStream) -> Result<()> { |
161 | //! // Parse a nonempty sequence of path segments separated by `::` punctuation |
162 | //! // with no trailing punctuation. |
163 | //! let tokens = input.clone(); |
164 | //! let parser = Punctuated::<PathSegment, Token![::]>::parse_separated_nonempty; |
165 | //! let _path = parser.parse(tokens)?; |
166 | //! |
167 | //! // Parse a possibly empty sequence of expressions terminated by commas with |
168 | //! // an optional trailing punctuation. |
169 | //! let tokens = input.clone(); |
170 | //! let parser = Punctuated::<Expr, Token![,]>::parse_terminated; |
171 | //! let _args = parser.parse(tokens)?; |
172 | //! |
173 | //! // Parse zero or more outer attributes but not inner attributes. |
174 | //! let tokens = input.clone(); |
175 | //! let parser = Attribute::parse_outer; |
176 | //! let _attrs = parser.parse(tokens)?; |
177 | //! |
178 | //! Ok(()) |
179 | //! } |
180 | //! ``` |
181 | //! |
182 | //! --- |
183 | //! |
184 | //! *This module is available only if Syn is built with the `"parsing"` feature.* |
185 | |
186 | #[path = "discouraged.rs" ] |
187 | pub mod discouraged; |
188 | |
189 | use crate::buffer::{Cursor, TokenBuffer}; |
190 | use crate::error; |
191 | use crate::lookahead; |
192 | #[cfg (all( |
193 | not(all(target_arch = "wasm32" , any(target_os = "unknown" , target_os = "wasi" ))), |
194 | feature = "proc-macro" |
195 | ))] |
196 | use crate::proc_macro; |
197 | use crate::punctuated::Punctuated; |
198 | use crate::token::Token; |
199 | use proc_macro2::{self, Delimiter, Group, Literal, Punct, Span, TokenStream, TokenTree}; |
200 | use std::cell::Cell; |
201 | use std::fmt::{self, Debug, Display}; |
202 | #[cfg (feature = "extra-traits" )] |
203 | use std::hash::{Hash, Hasher}; |
204 | use std::marker::PhantomData; |
205 | use std::mem; |
206 | use std::ops::Deref; |
207 | use std::rc::Rc; |
208 | use std::str::FromStr; |
209 | |
210 | pub use crate::error::{Error, Result}; |
211 | pub use crate::lookahead::{Lookahead1, Peek}; |
212 | |
213 | /// Parsing interface implemented by all types that can be parsed in a default |
214 | /// way from a token stream. |
215 | /// |
216 | /// Refer to the [module documentation] for details about implementing and using |
217 | /// the `Parse` trait. |
218 | /// |
219 | /// [module documentation]: self |
220 | pub trait Parse: Sized { |
221 | fn parse(input: ParseStream) -> Result<Self>; |
222 | } |
223 | |
224 | /// Input to a Syn parser function. |
225 | /// |
226 | /// See the methods of this type under the documentation of [`ParseBuffer`]. For |
227 | /// an overview of parsing in Syn, refer to the [module documentation]. |
228 | /// |
229 | /// [module documentation]: self |
230 | pub type ParseStream<'a> = &'a ParseBuffer<'a>; |
231 | |
232 | /// Cursor position within a buffered token stream. |
233 | /// |
234 | /// This type is more commonly used through the type alias [`ParseStream`] which |
235 | /// is an alias for `&ParseBuffer`. |
236 | /// |
237 | /// `ParseStream` is the input type for all parser functions in Syn. They have |
238 | /// the signature `fn(ParseStream) -> Result<T>`. |
239 | /// |
240 | /// ## Calling a parser function |
241 | /// |
242 | /// There is no public way to construct a `ParseBuffer`. Instead, if you are |
243 | /// looking to invoke a parser function that requires `ParseStream` as input, |
244 | /// you will need to go through one of the public parsing entry points. |
245 | /// |
246 | /// - The [`parse_macro_input!`] macro if parsing input of a procedural macro; |
247 | /// - One of [the `syn::parse*` functions][syn-parse]; or |
248 | /// - A method of the [`Parser`] trait. |
249 | /// |
250 | /// [`parse_macro_input!`]: crate::parse_macro_input! |
251 | /// [syn-parse]: self#the-synparse-functions |
252 | pub struct ParseBuffer<'a> { |
253 | scope: Span, |
254 | // Instead of Cell<Cursor<'a>> so that ParseBuffer<'a> is covariant in 'a. |
255 | // The rest of the code in this module needs to be careful that only a |
256 | // cursor derived from this `cell` is ever assigned to this `cell`. |
257 | // |
258 | // Cell<Cursor<'a>> cannot be covariant in 'a because then we could take a |
259 | // ParseBuffer<'a>, upcast to ParseBuffer<'short> for some lifetime shorter |
260 | // than 'a, and then assign a Cursor<'short> into the Cell. |
261 | // |
262 | // By extension, it would not be safe to expose an API that accepts a |
263 | // Cursor<'a> and trusts that it lives as long as the cursor currently in |
264 | // the cell. |
265 | cell: Cell<Cursor<'static>>, |
266 | marker: PhantomData<Cursor<'a>>, |
267 | unexpected: Cell<Option<Rc<Cell<Unexpected>>>>, |
268 | } |
269 | |
270 | impl<'a> Drop for ParseBuffer<'a> { |
271 | fn drop(&mut self) { |
272 | if let Some(unexpected_span: Span) = span_of_unexpected_ignoring_nones(self.cursor()) { |
273 | let (inner: Rc> | , old_span: Option) = inner_unexpected(self); |
274 | if old_span.is_none() { |
275 | inner.set(val:Unexpected::Some(unexpected_span)); |
276 | } |
277 | } |
278 | } |
279 | } |
280 | |
281 | impl<'a> Display for ParseBuffer<'a> { |
282 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
283 | Display::fmt(&self.cursor().token_stream(), f) |
284 | } |
285 | } |
286 | |
287 | impl<'a> Debug for ParseBuffer<'a> { |
288 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
289 | Debug::fmt(&self.cursor().token_stream(), f) |
290 | } |
291 | } |
292 | |
293 | /// Cursor state associated with speculative parsing. |
294 | /// |
295 | /// This type is the input of the closure provided to [`ParseStream::step`]. |
296 | /// |
297 | /// [`ParseStream::step`]: ParseBuffer::step |
298 | /// |
299 | /// # Example |
300 | /// |
301 | /// ``` |
302 | /// use proc_macro2::TokenTree; |
303 | /// use syn::Result; |
304 | /// use syn::parse::ParseStream; |
305 | /// |
306 | /// // This function advances the stream past the next occurrence of `@`. If |
307 | /// // no `@` is present in the stream, the stream position is unchanged and |
308 | /// // an error is returned. |
309 | /// fn skip_past_next_at(input: ParseStream) -> Result<()> { |
310 | /// input.step(|cursor| { |
311 | /// let mut rest = *cursor; |
312 | /// while let Some((tt, next)) = rest.token_tree() { |
313 | /// match &tt { |
314 | /// TokenTree::Punct(punct) if punct.as_char() == '@' => { |
315 | /// return Ok(((), next)); |
316 | /// } |
317 | /// _ => rest = next, |
318 | /// } |
319 | /// } |
320 | /// Err(cursor.error("no `@` was found after this point" )) |
321 | /// }) |
322 | /// } |
323 | /// # |
324 | /// # fn remainder_after_skipping_past_next_at( |
325 | /// # input: ParseStream, |
326 | /// # ) -> Result<proc_macro2::TokenStream> { |
327 | /// # skip_past_next_at(input)?; |
328 | /// # input.parse() |
329 | /// # } |
330 | /// # |
331 | /// # use syn::parse::Parser; |
332 | /// # let remainder = remainder_after_skipping_past_next_at |
333 | /// # .parse_str("a @ b c" ) |
334 | /// # .unwrap(); |
335 | /// # assert_eq!(remainder.to_string(), "b c" ); |
336 | /// ``` |
337 | pub struct StepCursor<'c, 'a> { |
338 | scope: Span, |
339 | // This field is covariant in 'c. |
340 | cursor: Cursor<'c>, |
341 | // This field is contravariant in 'c. Together these make StepCursor |
342 | // invariant in 'c. Also covariant in 'a. The user cannot cast 'c to a |
343 | // different lifetime but can upcast into a StepCursor with a shorter |
344 | // lifetime 'a. |
345 | // |
346 | // As long as we only ever construct a StepCursor for which 'c outlives 'a, |
347 | // this means if ever a StepCursor<'c, 'a> exists we are guaranteed that 'c |
348 | // outlives 'a. |
349 | marker: PhantomData<fn(Cursor<'c>) -> Cursor<'a>>, |
350 | } |
351 | |
352 | impl<'c, 'a> Deref for StepCursor<'c, 'a> { |
353 | type Target = Cursor<'c>; |
354 | |
355 | fn deref(&self) -> &Self::Target { |
356 | &self.cursor |
357 | } |
358 | } |
359 | |
360 | impl<'c, 'a> Copy for StepCursor<'c, 'a> {} |
361 | |
362 | impl<'c, 'a> Clone for StepCursor<'c, 'a> { |
363 | fn clone(&self) -> Self { |
364 | *self |
365 | } |
366 | } |
367 | |
368 | impl<'c, 'a> StepCursor<'c, 'a> { |
369 | /// Triggers an error at the current position of the parse stream. |
370 | /// |
371 | /// The `ParseStream::step` invocation will return this same error without |
372 | /// advancing the stream state. |
373 | pub fn error<T: Display>(self, message: T) -> Error { |
374 | error::new_at(self.scope, self.cursor, message) |
375 | } |
376 | } |
377 | |
378 | pub(crate) fn advance_step_cursor<'c, 'a>(proof: StepCursor<'c, 'a>, to: Cursor<'c>) -> Cursor<'a> { |
379 | // Refer to the comments within the StepCursor definition. We use the |
380 | // fact that a StepCursor<'c, 'a> exists as proof that 'c outlives 'a. |
381 | // Cursor is covariant in its lifetime parameter so we can cast a |
382 | // Cursor<'c> to one with the shorter lifetime Cursor<'a>. |
383 | let _ = proof; |
384 | unsafe { mem::transmute::<Cursor<'c>, Cursor<'a>>(src:to) } |
385 | } |
386 | |
387 | pub(crate) fn new_parse_buffer( |
388 | scope: Span, |
389 | cursor: Cursor, |
390 | unexpected: Rc<Cell<Unexpected>>, |
391 | ) -> ParseBuffer { |
392 | ParseBuffer { |
393 | scope, |
394 | // See comment on `cell` in the struct definition. |
395 | cell: Cell::new(unsafe { mem::transmute::<Cursor, Cursor<'static>>(src:cursor) }), |
396 | marker: PhantomData, |
397 | unexpected: Cell::new(Some(unexpected)), |
398 | } |
399 | } |
400 | |
401 | pub(crate) enum Unexpected { |
402 | None, |
403 | Some(Span), |
404 | Chain(Rc<Cell<Unexpected>>), |
405 | } |
406 | |
407 | impl Default for Unexpected { |
408 | fn default() -> Self { |
409 | Unexpected::None |
410 | } |
411 | } |
412 | |
413 | impl Clone for Unexpected { |
414 | fn clone(&self) -> Self { |
415 | match self { |
416 | Unexpected::None => Unexpected::None, |
417 | Unexpected::Some(span: &Span) => Unexpected::Some(*span), |
418 | Unexpected::Chain(next: &Rc> | ) => Unexpected::Chain(next.clone()), |
419 | } |
420 | } |
421 | } |
422 | |
423 | // We call this on Cell<Unexpected> and Cell<Option<T>> where temporarily |
424 | // swapping in a None is cheap. |
425 | fn cell_clone<T: Default + Clone>(cell: &Cell<T>) -> T { |
426 | let prev: T = cell.take(); |
427 | let ret: T = prev.clone(); |
428 | cell.set(val:prev); |
429 | ret |
430 | } |
431 | |
432 | fn inner_unexpected(buffer: &ParseBuffer) -> (Rc<Cell<Unexpected>>, Option<Span>) { |
433 | let mut unexpected: Rc> | = get_unexpected(buffer); |
434 | loop { |
435 | match cell_clone(&unexpected) { |
436 | Unexpected::None => return (unexpected, None), |
437 | Unexpected::Some(span: Span) => return (unexpected, Some(span)), |
438 | Unexpected::Chain(next: Rc> | ) => unexpected = next, |
439 | } |
440 | } |
441 | } |
442 | |
443 | pub(crate) fn get_unexpected(buffer: &ParseBuffer) -> Rc<Cell<Unexpected>> { |
444 | cell_clone(&buffer.unexpected).unwrap() |
445 | } |
446 | |
447 | fn span_of_unexpected_ignoring_nones(mut cursor: Cursor) -> Option<Span> { |
448 | if cursor.eof() { |
449 | return None; |
450 | } |
451 | while let Some((inner: Cursor<'_>, _span: Span, rest: Cursor<'_>)) = cursor.group(delim:Delimiter::None) { |
452 | if let Some(unexpected: Span) = span_of_unexpected_ignoring_nones(cursor:inner) { |
453 | return Some(unexpected); |
454 | } |
455 | cursor = rest; |
456 | } |
457 | if cursor.eof() { |
458 | None |
459 | } else { |
460 | Some(cursor.span()) |
461 | } |
462 | } |
463 | |
464 | impl<'a> ParseBuffer<'a> { |
465 | /// Parses a syntax tree node of type `T`, advancing the position of our |
466 | /// parse stream past it. |
467 | pub fn parse<T: Parse>(&self) -> Result<T> { |
468 | T::parse(self) |
469 | } |
470 | |
471 | /// Calls the given parser function to parse a syntax tree node of type `T` |
472 | /// from this stream. |
473 | /// |
474 | /// # Example |
475 | /// |
476 | /// The parser below invokes [`Attribute::parse_outer`] to parse a vector of |
477 | /// zero or more outer attributes. |
478 | /// |
479 | /// [`Attribute::parse_outer`]: crate::Attribute::parse_outer |
480 | /// |
481 | /// ``` |
482 | /// use syn::{Attribute, Ident, Result, Token}; |
483 | /// use syn::parse::{Parse, ParseStream}; |
484 | /// |
485 | /// // Parses a unit struct with attributes. |
486 | /// // |
487 | /// // #[path = "s.tmpl"] |
488 | /// // struct S; |
489 | /// struct UnitStruct { |
490 | /// attrs: Vec<Attribute>, |
491 | /// struct_token: Token![struct], |
492 | /// name: Ident, |
493 | /// semi_token: Token![;], |
494 | /// } |
495 | /// |
496 | /// impl Parse for UnitStruct { |
497 | /// fn parse(input: ParseStream) -> Result<Self> { |
498 | /// Ok(UnitStruct { |
499 | /// attrs: input.call(Attribute::parse_outer)?, |
500 | /// struct_token: input.parse()?, |
501 | /// name: input.parse()?, |
502 | /// semi_token: input.parse()?, |
503 | /// }) |
504 | /// } |
505 | /// } |
506 | /// ``` |
507 | pub fn call<T>(&self, function: fn(ParseStream) -> Result<T>) -> Result<T> { |
508 | function(self) |
509 | } |
510 | |
511 | /// Looks at the next token in the parse stream to determine whether it |
512 | /// matches the requested type of token. |
513 | /// |
514 | /// Does not advance the position of the parse stream. |
515 | /// |
516 | /// # Syntax |
517 | /// |
518 | /// Note that this method does not use turbofish syntax. Pass the peek type |
519 | /// inside of parentheses. |
520 | /// |
521 | /// - `input.peek(Token![struct])` |
522 | /// - `input.peek(Token![==])` |
523 | /// - `input.peek(Ident)` *(does not accept keywords)* |
524 | /// - `input.peek(Ident::peek_any)` |
525 | /// - `input.peek(Lifetime)` |
526 | /// - `input.peek(token::Brace)` |
527 | /// |
528 | /// # Example |
529 | /// |
530 | /// In this example we finish parsing the list of supertraits when the next |
531 | /// token in the input is either `where` or an opening curly brace. |
532 | /// |
533 | /// ``` |
534 | /// use syn::{braced, token, Generics, Ident, Result, Token, TypeParamBound}; |
535 | /// use syn::parse::{Parse, ParseStream}; |
536 | /// use syn::punctuated::Punctuated; |
537 | /// |
538 | /// // Parses a trait definition containing no associated items. |
539 | /// // |
540 | /// // trait Marker<'de, T>: A + B<'de> where Box<T>: Clone {} |
541 | /// struct MarkerTrait { |
542 | /// trait_token: Token![trait], |
543 | /// ident: Ident, |
544 | /// generics: Generics, |
545 | /// colon_token: Option<Token![:]>, |
546 | /// supertraits: Punctuated<TypeParamBound, Token![+]>, |
547 | /// brace_token: token::Brace, |
548 | /// } |
549 | /// |
550 | /// impl Parse for MarkerTrait { |
551 | /// fn parse(input: ParseStream) -> Result<Self> { |
552 | /// let trait_token: Token![trait] = input.parse()?; |
553 | /// let ident: Ident = input.parse()?; |
554 | /// let mut generics: Generics = input.parse()?; |
555 | /// let colon_token: Option<Token![:]> = input.parse()?; |
556 | /// |
557 | /// let mut supertraits = Punctuated::new(); |
558 | /// if colon_token.is_some() { |
559 | /// loop { |
560 | /// supertraits.push_value(input.parse()?); |
561 | /// if input.peek(Token![where]) || input.peek(token::Brace) { |
562 | /// break; |
563 | /// } |
564 | /// supertraits.push_punct(input.parse()?); |
565 | /// } |
566 | /// } |
567 | /// |
568 | /// generics.where_clause = input.parse()?; |
569 | /// let content; |
570 | /// let empty_brace_token = braced!(content in input); |
571 | /// |
572 | /// Ok(MarkerTrait { |
573 | /// trait_token, |
574 | /// ident, |
575 | /// generics, |
576 | /// colon_token, |
577 | /// supertraits, |
578 | /// brace_token: empty_brace_token, |
579 | /// }) |
580 | /// } |
581 | /// } |
582 | /// ``` |
583 | pub fn peek<T: Peek>(&self, token: T) -> bool { |
584 | let _ = token; |
585 | T::Token::peek(self.cursor()) |
586 | } |
587 | |
588 | /// Looks at the second-next token in the parse stream. |
589 | /// |
590 | /// This is commonly useful as a way to implement contextual keywords. |
591 | /// |
592 | /// # Example |
593 | /// |
594 | /// This example needs to use `peek2` because the symbol `union` is not a |
595 | /// keyword in Rust. We can't use just `peek` and decide to parse a union if |
596 | /// the very next token is `union`, because someone is free to write a `mod |
597 | /// union` and a macro invocation that looks like `union::some_macro! { ... |
598 | /// }`. In other words `union` is a contextual keyword. |
599 | /// |
600 | /// ``` |
601 | /// use syn::{Ident, ItemUnion, Macro, Result, Token}; |
602 | /// use syn::parse::{Parse, ParseStream}; |
603 | /// |
604 | /// // Parses either a union or a macro invocation. |
605 | /// enum UnionOrMacro { |
606 | /// // union MaybeUninit<T> { uninit: (), value: T } |
607 | /// Union(ItemUnion), |
608 | /// // lazy_static! { ... } |
609 | /// Macro(Macro), |
610 | /// } |
611 | /// |
612 | /// impl Parse for UnionOrMacro { |
613 | /// fn parse(input: ParseStream) -> Result<Self> { |
614 | /// if input.peek(Token![union]) && input.peek2(Ident) { |
615 | /// input.parse().map(UnionOrMacro::Union) |
616 | /// } else { |
617 | /// input.parse().map(UnionOrMacro::Macro) |
618 | /// } |
619 | /// } |
620 | /// } |
621 | /// ``` |
622 | pub fn peek2<T: Peek>(&self, token: T) -> bool { |
623 | fn peek2(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { |
624 | if let Some(group) = buffer.cursor().group(Delimiter::None) { |
625 | if group.0.skip().map_or(false, peek) { |
626 | return true; |
627 | } |
628 | } |
629 | buffer.cursor().skip().map_or(false, peek) |
630 | } |
631 | |
632 | let _ = token; |
633 | peek2(self, T::Token::peek) |
634 | } |
635 | |
636 | /// Looks at the third-next token in the parse stream. |
637 | pub fn peek3<T: Peek>(&self, token: T) -> bool { |
638 | fn peek3(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { |
639 | if let Some(group) = buffer.cursor().group(Delimiter::None) { |
640 | if group.0.skip().and_then(Cursor::skip).map_or(false, peek) { |
641 | return true; |
642 | } |
643 | } |
644 | buffer |
645 | .cursor() |
646 | .skip() |
647 | .and_then(Cursor::skip) |
648 | .map_or(false, peek) |
649 | } |
650 | |
651 | let _ = token; |
652 | peek3(self, T::Token::peek) |
653 | } |
654 | |
655 | /// Parses zero or more occurrences of `T` separated by punctuation of type |
656 | /// `P`, with optional trailing punctuation. |
657 | /// |
658 | /// Parsing continues until the end of this parse stream. The entire content |
659 | /// of this parse stream must consist of `T` and `P`. |
660 | /// |
661 | /// # Example |
662 | /// |
663 | /// ``` |
664 | /// # use quote::quote; |
665 | /// # |
666 | /// use syn::{parenthesized, token, Ident, Result, Token, Type}; |
667 | /// use syn::parse::{Parse, ParseStream}; |
668 | /// use syn::punctuated::Punctuated; |
669 | /// |
670 | /// // Parse a simplified tuple struct syntax like: |
671 | /// // |
672 | /// // struct S(A, B); |
673 | /// struct TupleStruct { |
674 | /// struct_token: Token![struct], |
675 | /// ident: Ident, |
676 | /// paren_token: token::Paren, |
677 | /// fields: Punctuated<Type, Token![,]>, |
678 | /// semi_token: Token![;], |
679 | /// } |
680 | /// |
681 | /// impl Parse for TupleStruct { |
682 | /// fn parse(input: ParseStream) -> Result<Self> { |
683 | /// let content; |
684 | /// Ok(TupleStruct { |
685 | /// struct_token: input.parse()?, |
686 | /// ident: input.parse()?, |
687 | /// paren_token: parenthesized!(content in input), |
688 | /// fields: content.parse_terminated(Type::parse)?, |
689 | /// semi_token: input.parse()?, |
690 | /// }) |
691 | /// } |
692 | /// } |
693 | /// # |
694 | /// # let input = quote! { |
695 | /// # struct S(A, B); |
696 | /// # }; |
697 | /// # syn::parse2::<TupleStruct>(input).unwrap(); |
698 | /// ``` |
699 | pub fn parse_terminated<T, P: Parse>( |
700 | &self, |
701 | parser: fn(ParseStream) -> Result<T>, |
702 | ) -> Result<Punctuated<T, P>> { |
703 | Punctuated::parse_terminated_with(self, parser) |
704 | } |
705 | |
706 | /// Returns whether there are tokens remaining in this stream. |
707 | /// |
708 | /// This method returns true at the end of the content of a set of |
709 | /// delimiters, as well as at the very end of the complete macro input. |
710 | /// |
711 | /// # Example |
712 | /// |
713 | /// ``` |
714 | /// use syn::{braced, token, Ident, Item, Result, Token}; |
715 | /// use syn::parse::{Parse, ParseStream}; |
716 | /// |
717 | /// // Parses a Rust `mod m { ... }` containing zero or more items. |
718 | /// struct Mod { |
719 | /// mod_token: Token![mod], |
720 | /// name: Ident, |
721 | /// brace_token: token::Brace, |
722 | /// items: Vec<Item>, |
723 | /// } |
724 | /// |
725 | /// impl Parse for Mod { |
726 | /// fn parse(input: ParseStream) -> Result<Self> { |
727 | /// let content; |
728 | /// Ok(Mod { |
729 | /// mod_token: input.parse()?, |
730 | /// name: input.parse()?, |
731 | /// brace_token: braced!(content in input), |
732 | /// items: { |
733 | /// let mut items = Vec::new(); |
734 | /// while !content.is_empty() { |
735 | /// items.push(content.parse()?); |
736 | /// } |
737 | /// items |
738 | /// }, |
739 | /// }) |
740 | /// } |
741 | /// } |
742 | /// ``` |
743 | pub fn is_empty(&self) -> bool { |
744 | self.cursor().eof() |
745 | } |
746 | |
747 | /// Constructs a helper for peeking at the next token in this stream and |
748 | /// building an error message if it is not one of a set of expected tokens. |
749 | /// |
750 | /// # Example |
751 | /// |
752 | /// ``` |
753 | /// use syn::{ConstParam, Ident, Lifetime, LifetimeDef, Result, Token, TypeParam}; |
754 | /// use syn::parse::{Parse, ParseStream}; |
755 | /// |
756 | /// // A generic parameter, a single one of the comma-separated elements inside |
757 | /// // angle brackets in: |
758 | /// // |
759 | /// // fn f<T: Clone, 'a, 'b: 'a, const N: usize>() { ... } |
760 | /// // |
761 | /// // On invalid input, lookahead gives us a reasonable error message. |
762 | /// // |
763 | /// // error: expected one of: identifier, lifetime, `const` |
764 | /// // | |
765 | /// // 5 | fn f<!Sized>() {} |
766 | /// // | ^ |
767 | /// enum GenericParam { |
768 | /// Type(TypeParam), |
769 | /// Lifetime(LifetimeDef), |
770 | /// Const(ConstParam), |
771 | /// } |
772 | /// |
773 | /// impl Parse for GenericParam { |
774 | /// fn parse(input: ParseStream) -> Result<Self> { |
775 | /// let lookahead = input.lookahead1(); |
776 | /// if lookahead.peek(Ident) { |
777 | /// input.parse().map(GenericParam::Type) |
778 | /// } else if lookahead.peek(Lifetime) { |
779 | /// input.parse().map(GenericParam::Lifetime) |
780 | /// } else if lookahead.peek(Token![const]) { |
781 | /// input.parse().map(GenericParam::Const) |
782 | /// } else { |
783 | /// Err(lookahead.error()) |
784 | /// } |
785 | /// } |
786 | /// } |
787 | /// ``` |
788 | pub fn lookahead1(&self) -> Lookahead1<'a> { |
789 | lookahead::new(self.scope, self.cursor()) |
790 | } |
791 | |
792 | /// Forks a parse stream so that parsing tokens out of either the original |
793 | /// or the fork does not advance the position of the other. |
794 | /// |
795 | /// # Performance |
796 | /// |
797 | /// Forking a parse stream is a cheap fixed amount of work and does not |
798 | /// involve copying token buffers. Where you might hit performance problems |
799 | /// is if your macro ends up parsing a large amount of content more than |
800 | /// once. |
801 | /// |
802 | /// ``` |
803 | /// # use syn::{Expr, Result}; |
804 | /// # use syn::parse::ParseStream; |
805 | /// # |
806 | /// # fn bad(input: ParseStream) -> Result<Expr> { |
807 | /// // Do not do this. |
808 | /// if input.fork().parse::<Expr>().is_ok() { |
809 | /// return input.parse::<Expr>(); |
810 | /// } |
811 | /// # unimplemented!() |
812 | /// # } |
813 | /// ``` |
814 | /// |
815 | /// As a rule, avoid parsing an unbounded amount of tokens out of a forked |
816 | /// parse stream. Only use a fork when the amount of work performed against |
817 | /// the fork is small and bounded. |
818 | /// |
819 | /// When complex speculative parsing against the forked stream is |
820 | /// unavoidable, use [`parse::discouraged::Speculative`] to advance the |
821 | /// original stream once the fork's parse is determined to have been |
822 | /// successful. |
823 | /// |
824 | /// For a lower level way to perform speculative parsing at the token level, |
825 | /// consider using [`ParseStream::step`] instead. |
826 | /// |
827 | /// [`parse::discouraged::Speculative`]: discouraged::Speculative |
828 | /// [`ParseStream::step`]: ParseBuffer::step |
829 | /// |
830 | /// # Example |
831 | /// |
832 | /// The parse implementation shown here parses possibly restricted `pub` |
833 | /// visibilities. |
834 | /// |
835 | /// - `pub` |
836 | /// - `pub(crate)` |
837 | /// - `pub(self)` |
838 | /// - `pub(super)` |
839 | /// - `pub(in some::path)` |
840 | /// |
841 | /// To handle the case of visibilities inside of tuple structs, the parser |
842 | /// needs to distinguish parentheses that specify visibility restrictions |
843 | /// from parentheses that form part of a tuple type. |
844 | /// |
845 | /// ``` |
846 | /// # struct A; |
847 | /// # struct B; |
848 | /// # struct C; |
849 | /// # |
850 | /// struct S(pub(crate) A, pub (B, C)); |
851 | /// ``` |
852 | /// |
853 | /// In this example input the first tuple struct element of `S` has |
854 | /// `pub(crate)` visibility while the second tuple struct element has `pub` |
855 | /// visibility; the parentheses around `(B, C)` are part of the type rather |
856 | /// than part of a visibility restriction. |
857 | /// |
858 | /// The parser uses a forked parse stream to check the first token inside of |
859 | /// parentheses after the `pub` keyword. This is a small bounded amount of |
860 | /// work performed against the forked parse stream. |
861 | /// |
862 | /// ``` |
863 | /// use syn::{parenthesized, token, Ident, Path, Result, Token}; |
864 | /// use syn::ext::IdentExt; |
865 | /// use syn::parse::{Parse, ParseStream}; |
866 | /// |
867 | /// struct PubVisibility { |
868 | /// pub_token: Token![pub], |
869 | /// restricted: Option<Restricted>, |
870 | /// } |
871 | /// |
872 | /// struct Restricted { |
873 | /// paren_token: token::Paren, |
874 | /// in_token: Option<Token![in]>, |
875 | /// path: Path, |
876 | /// } |
877 | /// |
878 | /// impl Parse for PubVisibility { |
879 | /// fn parse(input: ParseStream) -> Result<Self> { |
880 | /// let pub_token: Token![pub] = input.parse()?; |
881 | /// |
882 | /// if input.peek(token::Paren) { |
883 | /// let ahead = input.fork(); |
884 | /// let mut content; |
885 | /// parenthesized!(content in ahead); |
886 | /// |
887 | /// if content.peek(Token![crate]) |
888 | /// || content.peek(Token![self]) |
889 | /// || content.peek(Token![super]) |
890 | /// { |
891 | /// return Ok(PubVisibility { |
892 | /// pub_token, |
893 | /// restricted: Some(Restricted { |
894 | /// paren_token: parenthesized!(content in input), |
895 | /// in_token: None, |
896 | /// path: Path::from(content.call(Ident::parse_any)?), |
897 | /// }), |
898 | /// }); |
899 | /// } else if content.peek(Token![in]) { |
900 | /// return Ok(PubVisibility { |
901 | /// pub_token, |
902 | /// restricted: Some(Restricted { |
903 | /// paren_token: parenthesized!(content in input), |
904 | /// in_token: Some(content.parse()?), |
905 | /// path: content.call(Path::parse_mod_style)?, |
906 | /// }), |
907 | /// }); |
908 | /// } |
909 | /// } |
910 | /// |
911 | /// Ok(PubVisibility { |
912 | /// pub_token, |
913 | /// restricted: None, |
914 | /// }) |
915 | /// } |
916 | /// } |
917 | /// ``` |
918 | pub fn fork(&self) -> Self { |
919 | ParseBuffer { |
920 | scope: self.scope, |
921 | cell: self.cell.clone(), |
922 | marker: PhantomData, |
923 | // Not the parent's unexpected. Nothing cares whether the clone |
924 | // parses all the way unless we `advance_to`. |
925 | unexpected: Cell::new(Some(Rc::new(Cell::new(Unexpected::None)))), |
926 | } |
927 | } |
928 | |
929 | /// Triggers an error at the current position of the parse stream. |
930 | /// |
931 | /// # Example |
932 | /// |
933 | /// ``` |
934 | /// use syn::{Expr, Result, Token}; |
935 | /// use syn::parse::{Parse, ParseStream}; |
936 | /// |
937 | /// // Some kind of loop: `while` or `for` or `loop`. |
938 | /// struct Loop { |
939 | /// expr: Expr, |
940 | /// } |
941 | /// |
942 | /// impl Parse for Loop { |
943 | /// fn parse(input: ParseStream) -> Result<Self> { |
944 | /// if input.peek(Token![while]) |
945 | /// || input.peek(Token![for]) |
946 | /// || input.peek(Token![loop]) |
947 | /// { |
948 | /// Ok(Loop { |
949 | /// expr: input.parse()?, |
950 | /// }) |
951 | /// } else { |
952 | /// Err(input.error("expected some kind of loop" )) |
953 | /// } |
954 | /// } |
955 | /// } |
956 | /// ``` |
957 | pub fn error<T: Display>(&self, message: T) -> Error { |
958 | error::new_at(self.scope, self.cursor(), message) |
959 | } |
960 | |
961 | /// Speculatively parses tokens from this parse stream, advancing the |
962 | /// position of this stream only if parsing succeeds. |
963 | /// |
964 | /// This is a powerful low-level API used for defining the `Parse` impls of |
965 | /// the basic built-in token types. It is not something that will be used |
966 | /// widely outside of the Syn codebase. |
967 | /// |
968 | /// # Example |
969 | /// |
970 | /// ``` |
971 | /// use proc_macro2::TokenTree; |
972 | /// use syn::Result; |
973 | /// use syn::parse::ParseStream; |
974 | /// |
975 | /// // This function advances the stream past the next occurrence of `@`. If |
976 | /// // no `@` is present in the stream, the stream position is unchanged and |
977 | /// // an error is returned. |
978 | /// fn skip_past_next_at(input: ParseStream) -> Result<()> { |
979 | /// input.step(|cursor| { |
980 | /// let mut rest = *cursor; |
981 | /// while let Some((tt, next)) = rest.token_tree() { |
982 | /// match &tt { |
983 | /// TokenTree::Punct(punct) if punct.as_char() == '@' => { |
984 | /// return Ok(((), next)); |
985 | /// } |
986 | /// _ => rest = next, |
987 | /// } |
988 | /// } |
989 | /// Err(cursor.error("no `@` was found after this point" )) |
990 | /// }) |
991 | /// } |
992 | /// # |
993 | /// # fn remainder_after_skipping_past_next_at( |
994 | /// # input: ParseStream, |
995 | /// # ) -> Result<proc_macro2::TokenStream> { |
996 | /// # skip_past_next_at(input)?; |
997 | /// # input.parse() |
998 | /// # } |
999 | /// # |
1000 | /// # use syn::parse::Parser; |
1001 | /// # let remainder = remainder_after_skipping_past_next_at |
1002 | /// # .parse_str("a @ b c" ) |
1003 | /// # .unwrap(); |
1004 | /// # assert_eq!(remainder.to_string(), "b c" ); |
1005 | /// ``` |
1006 | pub fn step<F, R>(&self, function: F) -> Result<R> |
1007 | where |
1008 | F: for<'c> FnOnce(StepCursor<'c, 'a>) -> Result<(R, Cursor<'c>)>, |
1009 | { |
1010 | // Since the user's function is required to work for any 'c, we know |
1011 | // that the Cursor<'c> they return is either derived from the input |
1012 | // StepCursor<'c, 'a> or from a Cursor<'static>. |
1013 | // |
1014 | // It would not be legal to write this function without the invariant |
1015 | // lifetime 'c in StepCursor<'c, 'a>. If this function were written only |
1016 | // in terms of 'a, the user could take our ParseBuffer<'a>, upcast it to |
1017 | // a ParseBuffer<'short> which some shorter lifetime than 'a, invoke |
1018 | // `step` on their ParseBuffer<'short> with a closure that returns |
1019 | // Cursor<'short>, and we would wrongly write that Cursor<'short> into |
1020 | // the Cell intended to hold Cursor<'a>. |
1021 | // |
1022 | // In some cases it may be necessary for R to contain a Cursor<'a>. |
1023 | // Within Syn we solve this using `advance_step_cursor` which uses the |
1024 | // existence of a StepCursor<'c, 'a> as proof that it is safe to cast |
1025 | // from Cursor<'c> to Cursor<'a>. If needed outside of Syn, it would be |
1026 | // safe to expose that API as a method on StepCursor. |
1027 | let (node, rest) = function(StepCursor { |
1028 | scope: self.scope, |
1029 | cursor: self.cell.get(), |
1030 | marker: PhantomData, |
1031 | })?; |
1032 | self.cell.set(rest); |
1033 | Ok(node) |
1034 | } |
1035 | |
1036 | /// Returns the `Span` of the next token in the parse stream, or |
1037 | /// `Span::call_site()` if this parse stream has completely exhausted its |
1038 | /// input `TokenStream`. |
1039 | pub fn span(&self) -> Span { |
1040 | let cursor = self.cursor(); |
1041 | if cursor.eof() { |
1042 | self.scope |
1043 | } else { |
1044 | crate::buffer::open_span_of_group(cursor) |
1045 | } |
1046 | } |
1047 | |
1048 | /// Provides low-level access to the token representation underlying this |
1049 | /// parse stream. |
1050 | /// |
1051 | /// Cursors are immutable so no operations you perform against the cursor |
1052 | /// will affect the state of this parse stream. |
1053 | pub fn cursor(&self) -> Cursor<'a> { |
1054 | self.cell.get() |
1055 | } |
1056 | |
1057 | fn check_unexpected(&self) -> Result<()> { |
1058 | match inner_unexpected(self).1 { |
1059 | Some(span) => Err(Error::new(span, "unexpected token" )), |
1060 | None => Ok(()), |
1061 | } |
1062 | } |
1063 | } |
1064 | |
1065 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1066 | impl<T: Parse> Parse for Box<T> { |
1067 | fn parse(input: ParseStream) -> Result<Self> { |
1068 | input.parse().map(op:Box::new) |
1069 | } |
1070 | } |
1071 | |
1072 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1073 | impl<T: Parse + Token> Parse for Option<T> { |
1074 | fn parse(input: ParseStream) -> Result<Self> { |
1075 | if T::peek(input.cursor()) { |
1076 | Ok(Some(input.parse()?)) |
1077 | } else { |
1078 | Ok(None) |
1079 | } |
1080 | } |
1081 | } |
1082 | |
1083 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1084 | impl Parse for TokenStream { |
1085 | fn parse(input: ParseStream) -> Result<Self> { |
1086 | input.step(|cursor: StepCursor<'_, '_>| Ok((cursor.token_stream(), Cursor::empty()))) |
1087 | } |
1088 | } |
1089 | |
1090 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1091 | impl Parse for TokenTree { |
1092 | fn parse(input: ParseStream) -> Result<Self> { |
1093 | input.step(|cursor: StepCursor<'_, '_>| match cursor.token_tree() { |
1094 | Some((tt: TokenTree, rest: Cursor<'_>)) => Ok((tt, rest)), |
1095 | None => Err(cursor.error(message:"expected token tree" )), |
1096 | }) |
1097 | } |
1098 | } |
1099 | |
1100 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1101 | impl Parse for Group { |
1102 | fn parse(input: ParseStream) -> Result<Self> { |
1103 | input.step(|cursor: StepCursor<'_, '_>| { |
1104 | for delim: &Delimiter in &[Delimiter::Parenthesis, Delimiter::Brace, Delimiter::Bracket] { |
1105 | if let Some((inside: Cursor<'_>, span: Span, rest: Cursor<'_>)) = cursor.group(*delim) { |
1106 | let mut group: Group = Group::new(*delim, inside.token_stream()); |
1107 | group.set_span(span); |
1108 | return Ok((group, rest)); |
1109 | } |
1110 | } |
1111 | Err(cursor.error(message:"expected group token" )) |
1112 | }) |
1113 | } |
1114 | } |
1115 | |
1116 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1117 | impl Parse for Punct { |
1118 | fn parse(input: ParseStream) -> Result<Self> { |
1119 | input.step(|cursor: StepCursor<'_, '_>| match cursor.punct() { |
1120 | Some((punct: Punct, rest: Cursor<'_>)) => Ok((punct, rest)), |
1121 | None => Err(cursor.error(message:"expected punctuation token" )), |
1122 | }) |
1123 | } |
1124 | } |
1125 | |
1126 | #[cfg_attr (doc_cfg, doc(cfg(feature = "parsing" )))] |
1127 | impl Parse for Literal { |
1128 | fn parse(input: ParseStream) -> Result<Self> { |
1129 | input.step(|cursor: StepCursor<'_, '_>| match cursor.literal() { |
1130 | Some((literal: Literal, rest: Cursor<'_>)) => Ok((literal, rest)), |
1131 | None => Err(cursor.error(message:"expected literal token" )), |
1132 | }) |
1133 | } |
1134 | } |
1135 | |
1136 | /// Parser that can parse Rust tokens into a particular syntax tree node. |
1137 | /// |
1138 | /// Refer to the [module documentation] for details about parsing in Syn. |
1139 | /// |
1140 | /// [module documentation]: self |
1141 | /// |
1142 | /// *This trait is available only if Syn is built with the `"parsing"` feature.* |
1143 | pub trait Parser: Sized { |
1144 | type Output; |
1145 | |
1146 | /// Parse a proc-macro2 token stream into the chosen syntax tree node. |
1147 | /// |
1148 | /// This function will check that the input is fully parsed. If there are |
1149 | /// any unparsed tokens at the end of the stream, an error is returned. |
1150 | fn parse2(self, tokens: TokenStream) -> Result<Self::Output>; |
1151 | |
1152 | /// Parse tokens of source code into the chosen syntax tree node. |
1153 | /// |
1154 | /// This function will check that the input is fully parsed. If there are |
1155 | /// any unparsed tokens at the end of the stream, an error is returned. |
1156 | /// |
1157 | /// *This method is available only if Syn is built with both the `"parsing"` and |
1158 | /// `"proc-macro"` features.* |
1159 | #[cfg (all( |
1160 | not(all(target_arch = "wasm32" , any(target_os = "unknown" , target_os = "wasi" ))), |
1161 | feature = "proc-macro" |
1162 | ))] |
1163 | fn parse(self, tokens: proc_macro::TokenStream) -> Result<Self::Output> { |
1164 | self.parse2(proc_macro2::TokenStream::from(tokens)) |
1165 | } |
1166 | |
1167 | /// Parse a string of Rust code into the chosen syntax tree node. |
1168 | /// |
1169 | /// This function will check that the input is fully parsed. If there are |
1170 | /// any unparsed tokens at the end of the string, an error is returned. |
1171 | /// |
1172 | /// # Hygiene |
1173 | /// |
1174 | /// Every span in the resulting syntax tree will be set to resolve at the |
1175 | /// macro call site. |
1176 | fn parse_str(self, s: &str) -> Result<Self::Output> { |
1177 | self.parse2(proc_macro2::TokenStream::from_str(s)?) |
1178 | } |
1179 | |
1180 | // Not public API. |
1181 | #[doc (hidden)] |
1182 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1183 | fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { |
1184 | let _ = scope; |
1185 | self.parse2(tokens) |
1186 | } |
1187 | |
1188 | // Not public API. |
1189 | #[doc (hidden)] |
1190 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1191 | fn __parse_stream(self, input: ParseStream) -> Result<Self::Output> { |
1192 | input.parse().and_then(|tokens| self.parse2(tokens)) |
1193 | } |
1194 | } |
1195 | |
1196 | fn tokens_to_parse_buffer(tokens: &TokenBuffer) -> ParseBuffer { |
1197 | let scope: Span = Span::call_site(); |
1198 | let cursor: Cursor<'_> = tokens.begin(); |
1199 | let unexpected: Rc> | = Rc::new(Cell::new(Unexpected::None)); |
1200 | new_parse_buffer(scope, cursor, unexpected) |
1201 | } |
1202 | |
1203 | impl<F, T> Parser for F |
1204 | where |
1205 | F: FnOnce(ParseStream) -> Result<T>, |
1206 | { |
1207 | type Output = T; |
1208 | |
1209 | fn parse2(self, tokens: TokenStream) -> Result<T> { |
1210 | let buf = TokenBuffer::new2(tokens); |
1211 | let state = tokens_to_parse_buffer(&buf); |
1212 | let node = self(&state)?; |
1213 | state.check_unexpected()?; |
1214 | if let Some(unexpected_span) = span_of_unexpected_ignoring_nones(state.cursor()) { |
1215 | Err(Error::new(unexpected_span, "unexpected token" )) |
1216 | } else { |
1217 | Ok(node) |
1218 | } |
1219 | } |
1220 | |
1221 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1222 | fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { |
1223 | let buf = TokenBuffer::new2(tokens); |
1224 | let cursor = buf.begin(); |
1225 | let unexpected = Rc::new(Cell::new(Unexpected::None)); |
1226 | let state = new_parse_buffer(scope, cursor, unexpected); |
1227 | let node = self(&state)?; |
1228 | state.check_unexpected()?; |
1229 | if let Some(unexpected_span) = span_of_unexpected_ignoring_nones(state.cursor()) { |
1230 | Err(Error::new(unexpected_span, "unexpected token" )) |
1231 | } else { |
1232 | Ok(node) |
1233 | } |
1234 | } |
1235 | |
1236 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1237 | fn __parse_stream(self, input: ParseStream) -> Result<Self::Output> { |
1238 | self(input) |
1239 | } |
1240 | } |
1241 | |
1242 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1243 | pub(crate) fn parse_scoped<F: Parser>(f: F, scope: Span, tokens: TokenStream) -> Result<F::Output> { |
1244 | f.__parse_scoped(scope, tokens) |
1245 | } |
1246 | |
1247 | #[cfg (any(feature = "full" , feature = "derive" ))] |
1248 | pub(crate) fn parse_stream<F: Parser>(f: F, input: ParseStream) -> Result<F::Output> { |
1249 | f.__parse_stream(input) |
1250 | } |
1251 | |
1252 | /// An empty syntax tree node that consumes no tokens when parsed. |
1253 | /// |
1254 | /// This is useful for attribute macros that want to ensure they are not |
1255 | /// provided any attribute args. |
1256 | /// |
1257 | /// ``` |
1258 | /// # extern crate proc_macro; |
1259 | /// # |
1260 | /// use proc_macro::TokenStream; |
1261 | /// use syn::parse_macro_input; |
1262 | /// use syn::parse::Nothing; |
1263 | /// |
1264 | /// # const IGNORE: &str = stringify! { |
1265 | /// #[proc_macro_attribute] |
1266 | /// # }; |
1267 | /// pub fn my_attr(args: TokenStream, input: TokenStream) -> TokenStream { |
1268 | /// parse_macro_input!(args as Nothing); |
1269 | /// |
1270 | /// /* ... */ |
1271 | /// # "" .parse().unwrap() |
1272 | /// } |
1273 | /// ``` |
1274 | /// |
1275 | /// ```text |
1276 | /// error: unexpected token |
1277 | /// --> src/main.rs:3:19 |
1278 | /// | |
1279 | /// 3 | #[my_attr(asdf)] |
1280 | /// | ^^^^ |
1281 | /// ``` |
1282 | pub struct Nothing; |
1283 | |
1284 | impl Parse for Nothing { |
1285 | fn parse(_input: ParseStream) -> Result<Self> { |
1286 | Ok(Nothing) |
1287 | } |
1288 | } |
1289 | |
1290 | #[cfg (feature = "extra-traits" )] |
1291 | #[cfg_attr (doc_cfg, doc(cfg(feature = "extra-traits" )))] |
1292 | impl Debug for Nothing { |
1293 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
1294 | f.write_str(data:"Nothing" ) |
1295 | } |
1296 | } |
1297 | |
1298 | #[cfg (feature = "extra-traits" )] |
1299 | #[cfg_attr (doc_cfg, doc(cfg(feature = "extra-traits" )))] |
1300 | impl Eq for Nothing {} |
1301 | |
1302 | #[cfg (feature = "extra-traits" )] |
1303 | #[cfg_attr (doc_cfg, doc(cfg(feature = "extra-traits" )))] |
1304 | impl PartialEq for Nothing { |
1305 | fn eq(&self, _other: &Self) -> bool { |
1306 | true |
1307 | } |
1308 | } |
1309 | |
1310 | #[cfg (feature = "extra-traits" )] |
1311 | #[cfg_attr (doc_cfg, doc(cfg(feature = "extra-traits" )))] |
1312 | impl Hash for Nothing { |
1313 | fn hash<H: Hasher>(&self, _state: &mut H) {} |
1314 | } |
1315 | |