syn/
parse.rs

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