syn

Syn is the foundational parsing library of the Rust procedural-macro ecosystem. It takes a stream of Rust tokens and parses it into a rich, typed syntax tree that can represent nearly all stable Rust source code plus some unstable syntax, rooted at entry points like File, Item, Expr, and Type.

Built around parser functions with the signature fn(ParseStream) -> Result<T>, Syn lets macro authors parse derive inputs, attributes, and entirely custom syntaxes while preserving Span location information for precise, user-friendly compiler error messages. Its aggressive feature gating keeps compile times low by pulling in only the functionality a given macro actually needs.

What You Get

• A complete typed syntax tree for Rust source, rooted at File, Item, Expr, Type, and DeriveInput.
• A Parse trait and ParseStream API for building parsers for derive inputs, attributes, and fully custom syntaxes.
• Span-aware error reporting so macros can point compiler errors at the exact offending token.
• Optional visit, visit-mut, and fold traversal traits, plus printing back to token streams via quote.
• Fine-grained Cargo feature flags (derive, full, parsing, printing, and more) to minimize compile-time cost.

Common Use Cases

• Parsing DeriveInput inside a #[proc_macro_derive] to generate trait implementations.
• Reading and validating attribute arguments in attribute-like procedural macros.
• Implementing function-like macros with bespoke DSL syntax via custom Parse impls.
• Statically analyzing or transforming Rust source in build scripts and tooling.

Under The Hood

Architecture Syn is organized as one crate whose ~50 source modules (src/expr.rs, src/item.rs, src/ty.rs, src/pat.rs, src/generics.rs, and peers) each define the syntax-tree types and Parse impls for one region of the Rust grammar. Parsing flows from a proc_macro2::TokenStream through src/buffer.rs’s cheaply copyable Cursor into the ParseStream/ParseBuffer machinery in src/parse.rs, which drives per-node fn(ParseStream) -> Result<T> parsers; src/lookahead.rs and src/precedence.rs handle disambiguation and expression precedence. A large body of repetitive trait code (Clone, Debug, Eq, Hash, Visit, VisitMut, Fold) is machine-generated by the codegen/ tool from the syn.json grammar description and checked in under src/gen/.

Tech Stack Pure Rust (edition 2021, minimum rustc 1.71) with a deliberately tiny dependency set: proc-macro2 for the token shim, optional quote for the printing feature, and unicode-ident for identifier validation. Behavior is sliced across fine-grained Cargo features (derive, full, parsing, printing, visit, visit-mut, fold, clone-impls, extra-traits, proc-macro) so callers compile only what they use. A build.rs handles rustc version detection.

Code Quality Maturity and rigor are high: 27 integration test files under tests/ (snapshot tests via insta, regression suites, and a corpus test that parses real crates from crates.io), fuzz targets under fuzz/, and benchmarks under benches/. Error handling is threaded consistently through the crate’s own syn::Error/Result types with span attribution, and the generated-vs-handwritten split keeps the mechanical trait impls consistent across hundreds of node types.

API Design The public API is the de-facto standard for the Rust macro ecosystem, which is itself strong evidence of its ergonomics. The Parse trait plus parse_macro_input! reduces a derive macro to a few lines, while ParseStream combinators make custom syntaxes approachable. Documentation is thorough — extensive rustdoc on lib.rs, worked examples/ (heapsize, lazy-static, dump-syntax, trace-var), and a companion proc-macro workshop. The main learning curve is the breadth of node types and the feature-flag matrix rather than any inconsistency in the API surface.