• Documentation improvements

• Add Error::new_range(start..end, "msg") (#2068, #2070)
• Add Cursor::prev_span

• Parse const traits (#2056, #2057, #2058, #2063, #2064)
• Parse unsafe binder types (#2065)
• Parse impl restrictions (#2066)

This release contains adjustments to the syntax tree to account for ongoing Rust language development from the 3 years since syn 2.0.0 and to anticipate some in-flight Rust language RFCs.

These include: default values in fields, pinned type sugar, raw lifetimes, generator blocks and functions, unnamed enum variants, attributes in tuple types and tuple patterns, named arguments in parenthesized generic argument lists, lightweight clones, const traits, const function pointers, mutability restricted fields, supertrait auto implementation, final associated functions, trait implementability restrictions, const blocks in path arguments, item-level const blocks, return type notation, never patterns, function delegation, mutable by-reference bindings, in-place initialization, field projections, explicitly dyn-compatible traits, view types, file-level frontmatter, generic const arguments, guard patterns, lazy type aliases, explicitly safe foreign items, super let, unsafe fields, pattern types, heterogeneous try-blocks, function contracts, async function trait bounds, static closure coroutine syntax, unsafe binder types, move expressions, for-await loops, and postfix keywords.

[API documentation for 3.0]

Breaking changes

Modifiers

To reserve more room for language evolution, there are 10 new non-exhaustive structs in the syntax tree having the following commonality:

• Name ending in Modifiers. {BlockModifiers, ClosureModifiers, ConstModifiers, FieldModifiers, FnModifiers, ImplModifiers, LocalModifiers, TraitBoundModifiers, TraitModifiers, TypeModifiers}

• Each implements Default. The default value is guaranteed to comprise no tokens.

• Non-exhaustive. Can only be instantiated by Syn's parser or by creating and then mutating ▁▁Modifiers::default().

• Does not implement Parse. When parsing, they are parsed by the enclosing syntax tree node.

• Does not implement ToTokens. In some cases the syntax that these nodes might hold in the future is not necessarily contiguous tokens.

• Provides .require_empty() -> Result<()> which returns a meaningfully spanned error if the modifiers are different from the empty default. This enables a caller to reject syntax it does not recognize without knowing what that syntax may be.

Types

• Type::BareFn has been renamed to Type::FnPtr to mirror the compiler's terminology. Together with this, BareVariadic is renamed to FnPtrVariadic.

• The mutually exclusive const_token and mutability fields of Type::Ptr have been unified into an enum of type PointerMutability, which was already previously used by Expr::RawAddr.

• Every Type variant now holds attributes, which can represent the attributes of element types inside a tuple type, or attributes for a function return type.

• BareFnArg is renamed to NamedArg and is used in ParenthesizedGenericArguments, in addition to the existing use in Type::FnPtr.

Expressions

• In Expr::Closure, the fields or1_token and or2_token have been renamed to inputs_begin and inputs_end to indicate the beginning and ending | token of the closure inputs.

Statements

• Attributes are now preserved on all expression kinds in statement position. Previously, parsing would silently lose attributes on some expression statements without a dedicated Expr variant, such as tail-call expressions.

Patterns

• The guard field of Arm is replaced by a new Pat::Guard variant held in the arm's pat.

Items

• The unsafety field of Signature, which represented the presence or absence of unsafe, is replaced by a 3-way Safety enum which may be safe, unsafe, or default. ForeignItem::Static also gets a Safety.

• Some of the fields of Receiver have been split to a non-exhaustive ReceiverKind enum to create room for proposed new kinds of method receivers, such as pinned.

• Type aliases now hold a WhereClausePlacement to distinguish between early placement (which is the default for item-level type aliases and is deprecated in associated type aliases) and late placement (which is the default for associated type aliases and is unstable in item-level type aliases). Parsing and printing a syntax tree will now preserve the where-clause placement rather than rewriting it to the default placement for the item kind.

Generics

• WherePredicate::Lifetime and WherePredicate::Type have a new field holding the attributes on the where-predicates.

• GenericParam::Type and GenericParam::Const now match the rest of the syntax tree in holding their optional default using a single Option of tuple, rather than a pair of Option.

Literals

• The Parse implementation of Lifetime no longer permits keyword lifetimes, matching a change in Rust 1.81 to deny such lifetimes pre-expansion. Lifetime::parse_any may be used to parse lifetimes permissive of keywords.

• LitInt and LitFloat no longer implement From<proc_macro2::Literal>. Use Lit::new(literal) and then match Lit::Int or Lit::Float.

• The StrStyle enum was unused and has been deleted.

More

• File contains a new Option<Frontmatter>, but does not yet parse frontmatter in syn::parse_file until that language feature progresses closer to stabilization.

• Some enums no longer provide From impls. Construct the variant by name instead, such as Expr::Array(e) in place of e.into().

• The pop method of Punctuated<T, P> now returns Option<T> discarding the trailing punctuation if any, rather than Option<Pair<T, P>>. A new method pop_pair provides the old behavior.

• Syntax tree traversal (visit, visit_mut, fold) no longer provides a method for processing Span. This was already incompletely supported and never walked most of the spans in a syntax tree.

• The Speculative and AnyDelimiter traits have been sealed and cannot be implemented for types outside of Syn's ParseStream.

• Preserve attributes on tail-call expressions in statement position (#1994)
• Parse field-representing types builtin in type position (#1996)

• Documentation improvements

• Fix parsing of self:: pattern in first function argument (#1970)

• Optimize parse_fn_arg_or_variadic for less lookahead on erroneous receiver (#1968)

• Enable GenericArgument::Constraint parsing in non-full mode (#1966)

• Make std dependencies more easily discoverable in source code (#1956, thanks @tamird)