This release contains a batch of syntax tree improvements to incorporate ongoing Rust language development from the past 3.5 years since syn 1.

It never seems like an ideal time to finalize a syntax tree design, considering the frankly alarming number of syntax-disrupting language features currently in flight: keyword generics, restrictions, capabilities and contexts, conditional constness, new varieties of literals, dyn revamp such as explicitly dyn-safe traits and dyn-star, expression syntax in various phases of being added or being torn out (const blocks, try blocks, raw references), auto traits and negative impls, generalizations to higher rank trait bounds, async closures and static async trait methods, postfix keywords, pattern types, return type notation, unsafe attributes, …

The plan continues to be the same as laid out originally in the 1.0.0 release announcement:

Be aware that the underlying Rust language will continue to evolve. Syn is able to accommodate most kinds of Rust grammar changes via the nonexhaustive enums and Verbatim variants in the syntax tree, but we will plan to put out new major versions on a 12 to 24 month cadence to incorporate ongoing language changes as needed.

If anything, the takeaway from the 3.5 year longevity of syn 1 is that this period was tamer from a language development perspective than anticipated, but that is unlikely to last and I think around 24 months is still the correct cadence to expect between releases going forward.

[API documentation for 2.0]

Breaking changes

• Minimum required Rust version is raised from rustc 1.31 to 1.56.

Expressions

• Support for box expr syntax has been deleted, as it has been deleted recently from rustc.

• Support for type ascription syntax expr: Type in expression position has been deleted.

• Support for unstable &raw const expr raw-pointer reference syntax has been deleted.

• The representation of generic arguments has been unified between method calls and non-method paths into a single GenericArgument type, which supersedes the previous GenericMethodArgument and MethodTurbofish.

• Generic arguments now distinguish between associated types (AssocType) and associated constant values (AssocConst). Previously these would be parsed ambiguously as Binding.

• The binary assignment operators in BinOp have been renamed to align with the naming used by the standard library's core::ops module's traits. For example BinOp::AddEq is now called BinOp::AddAssign.

• Expr::Struct struct construction expressions now support structs which are a variant of an enum associated type of a trait, as in <Type as Trait>::Assoc::Variant { ... }, which has recently been added to Rust.

• Expr::Range now follows the start and end naming used by the standard library's RangeBounds trait, rather than from/to or lo/hi.

• Expr::AssignOp has been merged into Expr::Binary, which now represents both non-assignment and assignment binary operators.

• Stricter parsing of ranges. None of the following are valid expressions, but were previously accepted by syn: ..=, lo..=, ..., ...hi, lo..., lo...hi.

• Expr::Closure now includes a representation for for<...> lifetimes.

Statements

• Variants Stmt::Expr (tail-position expression without trailing semicolon) and Stmt::Semi (non-tail expression with trailing semicolon) have been combined into Stmt::Expr with the optional semicolon represented by Option<Token![;]>.

• The syntax tree for Stmt::Local has been extended to handle let/else syntax.

• Macros in statement position are now uniformly parsed as Stmt::Macro. Previously these would be disambiguated to Stmt::Item, although it was ambiguous whether a macro in statement position would expand to an item (like thread_local! { ... }) vs an expression (like println! { ... }).

Patterns

• Pattern parsing for all the different syntactic positions in which patterns are allowed has been split into Pat::parse_single (for function- and closure-argument position, where top-level | is not allowed), Pat::parse_multi (where | is allowed) and Pat::parse_multi_with_leading_vert (for the pattern of match arms, which allow an optional leading |). Previously only a single parse behavior was supported and behaved like the new parse_single.

• The Pat syntax tree now shares more common data structures with the Expr syntax tree where possible, such as for literals, paths, macros, and ranges in pattern position.

• Parsing of struct field patterns does a better job rejecting bogus syntax such as Struct { 0 asdf } and Struct { ref mut 0: asdf }, which were previously incorrectly accepted.

• Pat::Range now supports one-sided ranges by representing the start and end bound of the range by Option<Expr>.

• Pat::Struct keeps track of attributes on the optional .. "rest" part of the pattern, as in let Struct { x, #[cfg(any())] .. } = _;.

• Parsing unary negation now enforces that only literal patterns can be unarily negated. For example -self::CONST and -const { 0i32 } are not valid syntax in pattern position.

• Pat::TupleStruct no longer wraps a value of type PatTuple but represents that information in its fields directly.

• A single parenthesized pattern without trailing comma inside the parentheses is no longer considered a Pat::Tuple, it will be parsed as Pat::Paren.

• One-sided range patterns are no longer allowed inside of slice patterns. [lo..] and [..=hi] are not considered valid pattern syntax by Rust.

Items

• Typed self in a method signature, such as self: Pin<&mut Self>, will now be parsed as FnArg::Receiver. This means self, whether with or without an explicit type, is always treated as a Receiver. Previously only the &self and &mut self shorthand receivers were parsed as Receiver.

• TraitItem::Method and ImplItem::Method have been renamed to TraitItem::Fn and ImplItem::Fn, as they do not necessarily represent methods if the function signature contains no self.

• Item::Macro2 has been deleted as "macros 2.0" syntax is no longer considered on track for stabilization.

• Various item kinds now hold Generics which didn't used to have them.

• The variadic argument of an extern function signature can now be given an optional parameter name.

• WherePredicate::Eq is no longer supported.

• Visibility::Crate is no longer supported. This syntax has been removed from rustc.

• Public visibility is now represented by a single Token![pub] token rather than the old VisPublic struct.

• LifetimeDef is now called LifetimeParam. This name makes more sense in the context of the GenericParam enum (which also includes TypeParam and ConstParam), and is the name that the Rust Reference uses.

• Modules and extern blocks (Item::Mod and Item::ForeignMod) can now be marked unsafe.

Attributes

• The syntax tree for Attribute has been redesigned. The new API better accommodates attributes which mix structured and unstructured content at different levels of nesting.

• AttributeArgs has been removed. Use Punctuated<Meta, Token![,]>.

• For parsing attribute contents, parse_meta() is superseded by a new parsing library called syn::meta, and the parse_nested_meta method on Attribute.

Tokens

• In string literals, the handling of non-ASCII whitespace after trailing \ now matches what is implemented by rustc. Space, horizontal tab, line feed, and carriage return are the only 4 whitespace characters which are supposed to be stripped from the beginning of the next line.

• The delimiter tokens syn::token::Paren, Bracket, and Brace now store 2 spans (the open and close punctuation separately) rather than just 1. Use .join() to obtain a single Span spanning the whole group.

• Keyword construction now requires a single span; an array of 1 span is no longer accepted. Use Token![trait](span) instead of Token![trait]([span]).

• Some token types have been renamed to conform with terminology used by the Rust Reference. These are Add->Plus, Bang->Not, Colon2->PathSep, Div->Slash, Dot2->DotDot, Dot3->DotDotDot, Rem->Percent, and Sub->Minus.

More

• Several enums have been made #[non_exhaustive] in anticipation of upcoming language changes. This includes WherePredicate, Lit, and GenericArgument.

• The impl Extend<Pair<T, P>> for Punctuated<T, P> now requires P: Default and will push a default punctuation between the pre-existing elements and the new ones, if there is not already a trailing punctuation. Previously it would panic in this situation.

• ParseStream::parse_terminated now takes a peek-style punctuation argument instead of turbofish. Replace input.parse_terminated::<_, Token![,]>(Thing::parse) with input.parse_terminated(Thing::parse, Token![,]).