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