Module syn::synom

Parsing interface for parsing a token stream into a syntax tree node.

Parsing in Syn is built on parser functions that take in a Cursor and produce a PResult<T> where T is some syntax tree node. Cursor is a cheaply copyable cursor over a range of tokens in a token stream, and PResult is a result that packages together a parsed syntax tree node T with a stream of remaining unparsed tokens after T represented as another Cursor, or a ParseError if parsing failed.

This Cursor- and PResult-based interface is convenient for parser combinators and parser implementations, but not necessarily when you just have some tokens that you want to parse. For that we expose the following two entry points.

The syn::parse* functions

The syn::parse, syn::parse2, and syn::parse_str functions serve as an entry point for parsing syntax tree nodes that can be parsed in an obvious default way. These functions can return any syntax tree node that implements the Synom trait, which includes most types in Syn.

use syn::Type;

let t: Type = syn::parse_str("std::collections::HashMap<String, Value>")?;

The parse_quote! macro also uses this approach.

The Parser trait

Some types can be parsed in several ways depending on context. For example an Attribute can be either "outer" like #[...] or "inner" like #![...] and parsing the wrong one would be a bug. Similarly Punctuated may or may not allow trailing punctuation, and parsing it the wrong way would either reject valid input or accept invalid input.

The Synom trait is not implemented in these cases because there is no good behavior to consider the default.

// Can't parse `Punctuated` without knowing whether trailing punctuation
// should be allowed in this context.
let path: Punctuated<PathSegment, Token![::]> = syn::parse(tokens)?;

In these cases the types provide a choice of parser functions rather than a single Synom implementation, and those parser functions can be invoked through the Parser trait.

use syn::synom::Parser;
use syn::punctuated::Punctuated;
use syn::{PathSegment, Expr, Attribute};

// Parse a nonempty sequence of path segments separated by `::` punctuation
// with no trailing punctuation.
let parser = Punctuated::<PathSegment, Token![::]>::parse_separated_nonempty;
let path = parser.parse(tokens)?;

// Parse a possibly empty sequence of expressions terminated by commas with
// an optional trailing punctuation.
let parser = Punctuated::<Expr, Token![,]>::parse_terminated;
let args = parser.parse(tokens)?;

// Parse zero or more outer attributes but not inner attributes.
named!(outer_attrs -> Vec<Attribute>, many0!(Attribute::parse_outer));
let attrs = outer_attrs.parse(tokens)?;

Implementing a parser function

Parser functions are usually implemented using the nom-style parser combinator macros provided by Syn, but may also be implemented without macros be using the low-level Cursor API directly.

The following parser combinator macros are available and a Synom parsing example is provided for each one.

• alt!
• braces!
• brackets!
• call!
• cond!
• cond_reduce!
• custom_keyword!
• do_parse!
• epsilon!
• input_end!
• keyword!
• many0!
• map!
• not!
• option!
• parens!
• punct!
• reject!
• switch!
• syn!
• tuple!
• value!

This module is available if Syn is built with the "parsing" feature.

Modules

ext	Extension traits that are made available within the call! parser.

Structs

ParseError

Error returned when a Synom parser cannot parse the input tokens.

Traits

Parser	Parser that can parse Rust tokens into a particular syntax tree node.
Synom	Parsing interface implemented by all types that can be parsed in a default way from a token stream.

Type Definitions

PResult

The result of a Synom parser.