18 //! enums (not shown) and structs, then provide implementations of the [`Parse`]
19 //! trait to parse these syntax tree data structures from a token stream.
21 //! Once `Parse` impls have been defined, they can be called conveniently from a
25 //! pointing out the exact token that triggered the failure to parse.
34 //! use syn::parse::{Parse, ParseStream};
51 //! impl Parse for Item {
52 //!     fn parse(input: ParseStream) -> Result<Self> {
55 //!             input.parse().map(Item::Struct)
57 //!             input.parse().map(Item::Enum)
64 //! impl Parse for ItemStruct {
65 //!     fn parse(input: ParseStream) -> Result<Self> {
68 //!             struct_token: input.parse()?,
69 //!             ident: input.parse()?,
76 //! # impl Parse for ItemEnum {
77 //! #     fn parse(input: ParseStream) -> Result<Self> {
93 //! # The `syn::parse*` functions
95 //! The [`syn::parse`], [`syn::parse2`], and [`syn::parse_str`] functions serve
98 //! implements the [`Parse`] trait, which includes most types in Syn.
100 //! [`syn::parse`]: crate::parse()
130 //! The `Parse` trait is not implemented in these cases because there is no good
141 //! // Can't parse `Punctuated` without knowing whether trailing punctuation
143 //! let path: Punctuated<PathSegment, Token![::]> = syn::parse(tokens)?;
150 //! single `Parse` implementation, and those parser functions can be invoked
158 //! use syn::parse::Parser;
163 //!     // Parse a nonempty sequence of path segments separated by `::` punctuation
167 //!     let _path = parser.parse(tokens)?;
169 //!     // Parse a possibly empty sequence of expressions terminated by commas with
173 //!     let _args = parser.parse(tokens)?;
175 //!     // Parse zero or more outer attributes but not inner attributes.
178 //!     let _attrs = parser.parse(tokens)?;
213 /// the `Parse` trait.
216 pub trait Parse: Sized {  trait
217     fn parse(input: ParseStream) -> Result<Self>;  in parse()  method
243 /// - One of [the `syn::parse*` functions][syn-parse]; or
247 /// [syn-parse]: self#the-synparse-functions
304 /// use syn::parse::ParseStream;
328 /// #     input.parse()
331 /// # use syn::parse::Parser;
369     /// Triggers an error at the current position of the parse stream.
466     /// parse stream past it.
467     pub fn parse<T: Parse>(&self) -> Result<T> {  in parse()  method
468         T::parse(self)  in parse()
471     /// Calls the given parser function to parse a syntax tree node of type `T`
476     /// The parser below invokes [`Attribute::parse_outer`] to parse a vector of
483     /// use syn::parse::{Parse, ParseStream};
496     /// impl Parse for UnitStruct {
497     ///     fn parse(input: ParseStream) -> Result<Self> {
500     ///             struct_token: input.parse()?,
501     ///             name: input.parse()?,
502     ///             semi_token: input.parse()?,
511     /// Looks at the next token in the parse stream to determine whether it
514     /// Does not advance the position of the parse stream.
535     /// use syn::parse::{Parse, ParseStream};
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()?;
560     ///                 supertraits.push_value(input.parse()?);
564     ///                 supertraits.push_punct(input.parse()?);
568     ///         generics.where_clause = input.parse()?;
588     /// Looks at the second-next token in the parse stream.
595     /// keyword in Rust. We can't use just `peek` and decide to parse a union if
602     /// use syn::parse::{Parse, ParseStream};
612     /// impl Parse for UnionOrMacro {
613     ///     fn parse(input: ParseStream) -> Result<Self> {
615     ///             input.parse().map(UnionOrMacro::Union)
617     ///             input.parse().map(UnionOrMacro::Macro)
631     /// Looks at the third-next token in the parse stream.
648     /// Parsing continues until the end of this parse stream. The entire content
649     /// of this parse stream must consist of `T` and `P`.
657     /// use syn::parse::{Parse, ParseStream};
660     /// // Parse a simplified tuple struct syntax like:
671     /// impl Parse for TupleStruct {
672     ///     fn parse(input: ParseStream) -> Result<Self> {
675     ///             struct_token: input.parse()?,
676     ///             ident: input.parse()?,
678     ///             fields: content.parse_terminated(Type::parse, Token![,])?,
679     ///             semi_token: input.parse()?,
702     /// use syn::parse::{Parse, ParseStream};
711     /// impl Parse for Fin {
712     ///     fn parse(input: ParseStream) -> Result<Self> {
713     ///         Ok(Self(input.parse()?, input.parse()?))
721     /// impl Parse for Thing {
722     ///     fn parse(input: ParseStream) -> Result<Self> {
743         P::Token: Parse,  in parse_terminated()  argument
757 …  /// <code>.<a href="#method.peek">peek</a>(<a href="struct.End.html">syn::parse::End</a>)</code>.
758     /// Use `.peek2(End)` or `.peek3(End)` to look for the end of a parse stream
765     /// use syn::parse::{Parse, ParseStream};
775     /// impl Parse for Mod {
776     ///     fn parse(input: ParseStream) -> Result<Self> {
779     ///             mod_token: input.parse()?,
780     ///             name: input.parse()?,
785     ///                     items.push(content.parse()?);
804     /// use syn::parse::{Parse, ParseStream};
823     /// impl Parse for GenericParam {
824     ///     fn parse(input: ParseStream) -> Result<Self> {
827     ///             input.parse().map(GenericParam::Type)
829     ///             input.parse().map(GenericParam::Lifetime)
831     ///             input.parse().map(GenericParam::Const)
842     /// Forks a parse stream so that parsing tokens out of either the original
847     /// Forking a parse stream is a cheap fixed amount of work and does not
854     /// # use syn::parse::ParseStream;
858     /// if input.fork().parse::<Expr>().is_ok() {
859     ///     return input.parse::<Expr>();
866     /// parse stream. Only use a fork when the amount of work performed against
870     /// unavoidable, use [`parse::discouraged::Speculative`] to advance the
871     /// original stream once the fork's parse is determined to have been
877     /// [`parse::discouraged::Speculative`]: discouraged::Speculative
882     /// The parse implementation shown here parses possibly restricted `pub`
908     /// The parser uses a forked parse stream to check the first token inside of
910     /// work performed against the forked parse stream.
915     /// use syn::parse::{Parse, ParseStream};
928     /// impl Parse for PubVisibility {
929     ///     fn parse(input: ParseStream) -> Result<Self> {
930     ///         let pub_token: Token![pub] = input.parse()?;
954     ///                         in_token: Some(content.parse()?),
979     /// Triggers an error at the current position of the parse stream.
985     /// use syn::parse::{Parse, ParseStream};
992     /// impl Parse for Loop {
993     ///     fn parse(input: ParseStream) -> Result<Self> {
999     ///                 expr: input.parse()?,
1011     /// Speculatively parses tokens from this parse stream, advancing the
1014     /// This is a powerful low-level API used for defining the `Parse` impls of
1023     /// use syn::parse::ParseStream;
1047     /// #     input.parse()
1050     /// # use syn::parse::Parser;
1086     /// Returns the `Span` of the next token in the parse stream, or
1087     /// `Span::call_site()` if this parse stream has completely exhausted its
1099     /// parse stream.
1102     /// will affect the state of this parse stream.
1109     /// use syn::parse::{ParseStream, Result};
1140     ///     use syn::parse::{Parse, Parser};
1143     ///     // Parse syn::Type as a TokenStream, surrounded by angle brackets.
1145     ///         let _langle: Token![<] = input.parse()?;
1146     ///         let ty = recognize_token_stream(syn::Type::parse)(input)?;
1147     ///         let _rangle: Token![>] = input.parse()?;
1168 impl<T: Parse> Parse for Box<T> {
1169     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1170         input.parse().map(Box::new)  in parse()
1175 impl<T: Parse + Token> Parse for Option<T> {
1176     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1178             Ok(Some(input.parse()?))  in parse()
1186 impl Parse for TokenStream {
1187     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1193 impl Parse for TokenTree {
1194     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1203 impl Parse for Group {
1204     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1217 impl Parse for Punct {
1218     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1227 impl Parse for Literal {
1228     fn parse(input: ParseStream) -> Result<Self> {  in parse()  method
1236 /// Parser that can parse Rust tokens into a particular syntax tree node.
1244     /// Parse a proc-macro2 token stream into the chosen syntax tree node.
1250     /// Parse tokens of source code into the chosen syntax tree node.
1256     fn parse(self, tokens: proc_macro::TokenStream) -> Result<Self::Output> {  in parse()  method
1260     /// Parse a string of Rust code into the chosen syntax tree node.
1349 /// use syn::parse::Nothing;
1371 impl Parse for Nothing {
1372     fn parse(_input: ParseStream) -> Result<Self> {  in parse()  method