Syn is a library for parsing Rust code, largely geared toward use in procedural macros but generally applicable as a Rust parser outside of that too.

Syn was originally a sidequest on the effort to making Serde's derive macros work on stable Rust in 2016, but has since taken off as a foundational library in its own right. These days it appears in support of diverse use cases like:

• convenient interop between Rust-based Wasm modules and JavaScript,
• easy command line interfaces,
• a polished async experience, and
• a concurrency framework for embedded real time systems.

Excitingly, the fraction of open source Rust projects that rely on Syn is still climbing aggressively (see red line). This reflects how important procedural macros are to the experience we want people to have when working with Rust — empowering everyone to build reliable and efficient software.

This 1.0 release signifies that Syn is a polished library with a stable design and role and that it offers a user experience we can stand behind as the way we recommend for all Rustaceans to write procedural macros.

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.

Note: in combination with this release, please see also the release notes for quote 1.0 which resolves multiple longstanding limitations of the quote macro.

Breaking changes

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

Items

• The syntax tree for function signatures has been redesigned. The types MethodSig and FnDecl have been unified into one type Signature that is common across all varieties of function signatures.

• The syntax tree for function arguments has been redesigned. The new type is FnArg which represents one argument of a function, associated function, trait function, or foreign function. Arguments of closures are no longer treated as FnArg and are simply a Pat instead.

• The Fields type now implements IntoIterator, in addition to the previously existing IntoIterator impls on &Fields and &mut Fields. This may require changing .into_iter() calls to .iter() when used on a value of type &Fields.

• The representation of Item::Macro2 2.0-style declarative macros have been collapsed into a single token stream pending figuring out what the syntax should be in rust-lang/rust#39412.

• Item::Existential and ImplItem::Existential have been removed in favor of RFC 2515.

Expressions

• Expr::Await is a new variant of expression for postfix .await syntax per ongoing work on rust-lang/rust#50547.

• Expr::InPlace has been removed as a result of RFC 2387.

Types

• BareFnArgName has been eliminated in favor of Ident for representing the arguments of a Type::BareFn.

Patterns

• Pat::Or is a new variant of pattern as specified by RFC 2535.

• Pat::Type is a new variant of pattern for type ascription as specified by RFC 2522.

• Pat::Rest is a new variant of pattern representing the .. pattern as specified by RFC 2707.

• The Pat::Slice and Pat::Tuple patterns have been redesigned to accomodate RFC 2359.

• Pat::Ref has been renamed to Pat::Reference to align with Expr::Reference and Type::Reference.

Tokens

• The Lit::Int and Lit::Float literal types have been redesigned to represent arbitrarily large numbers and arbitrary suffixes. Rather than .value(), there is a .base10_digits() accessor which the caller should parse into the appropriate representation.

• The types of the token representation of the self and Self tokens have been renamed from Self_ / CapSelf to SelfValue / SelfType respectively. This does not affect you if you are referring to them as Token![self] and Token![Self].

• The Lit::Verbatim literal escape hatch now holds a proc_macro2::Literal primitive token directly, rather than the previous LitVerbatim wrapper.

Attributes

• The Attribute::interpret_meta method is removed in favor of Attribute::parse_meta which produces a better error.

• The variants of Meta now contain a Path rather than a single Ident as specified by RFC 2103.

• Function parameters now hold attributes as specified by RFC 2565.

More

• The argument of Path::is_ident is now taken by reference. The common case of using this method with a string literal will continue to work: path.is_ident("...").

• The type returned by Punctuated::into_iter no longer has a P type parameter, as it only returns sequence elements without punctuation.

• The first, last, and last_mut accessors of Punctuated now return the element T only, no longer a punctuated pair. The old paired behavior of .first() can be written as .pairs().next(), .last() can be written as .pairs().next_back(), and .last_mut() can be written as .pairs_mut().next_back().

• Various uses of tts as a field name in the syntax tree have been renamed to tokens to eliminate the nonstandard abbreviation.