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: Span, delimiter: Delimiter)) = span_of_unexpected_ignoring_nones(self.cursor())
267 {
268 let (inner: Rc>, old_span: Option<(Span, Delimiter)>) = inner_unexpected(self);
269 if old_span.is_none() {
270 inner.set(val: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>>(src: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>>(src: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: &Span, delimiter: &Delimiter) => Unexpected::Some(*span, *delimiter),
416 Unexpected::Chain(next: &Rc>) => 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: T = cell.take();
425 let ret: T = prev.clone();
426 cell.set(val:prev);
427 ret
428}
429
430fn inner_unexpected(buffer: &ParseBuffer) -> (Rc<Cell<Unexpected>>, Option<(Span, Delimiter)>) {
431 let mut unexpected: Rc> = get_unexpected(buffer);
432 loop {
433 match cell_clone(&unexpected) {
434 Unexpected::None => return (unexpected, None),
435 Unexpected::Some(span: Span, delimiter: Delimiter) => return (unexpected, Some((span, delimiter))),
436 Unexpected::Chain(next: Rc>) => 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: Cursor<'_>, _span: DelimSpan, rest: Cursor<'_>)) = cursor.group(delim:Delimiter::None) {
450 if let Some(unexpected: (Span, Delimiter)) = span_of_unexpected_ignoring_nones(cursor: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>(&self, function: fn(ParseStream) -> 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 &self,
736 parser: fn(ParseStream) -> 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(op: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: StepCursor<'_, '_>| 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: StepCursor<'_, '_>| match cursor.token_tree() {
1194 Some((tt: TokenTree, rest: Cursor<'_>)) => Ok((tt, rest)),
1195 None => Err(cursor.error(message:"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: StepCursor<'_, '_>| {
1204 if let Some((group: Group, rest: Cursor<'_>)) = cursor.any_group_token() {
1205 if group.delimiter() != Delimiter::None {
1206 return Ok((group, rest));
1207 }
1208 }
1209 Err(cursor.error(message:"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: StepCursor<'_, '_>| match cursor.punct() {
1218 Some((punct: Punct, rest: Cursor<'_>)) => Ok((punct, rest)),
1219 None => Err(cursor.error(message:"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: StepCursor<'_, '_>| match cursor.literal() {
1228 Some((literal: Literal, rest: Cursor<'_>)) => Ok((literal, rest)),
1229 None => Err(cursor.error(message:"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 = Span::call_site();
1281 let cursor: Cursor<'_> = tokens.begin();
1282 let unexpected: Rc> = 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: &'static str = 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, message: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(data:"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}
1420