syn

Syn operates on the proc-macro2 token representation rather than the compiler's built-in proc_macro crate. This allows Syn code to run in contexts like unit tests or build.rs outside of a procedural macro environment.

Best Practice: Write all your logic against proc-macro2. The only exception is the signature of your procedural macro entry points, which must use proc_macro::TokenStream as required by the Rust language. The proc-macro2 crate will automatically switch to using the compiler's data structures when running inside a procedural macro.

The syn_codegen crate is an internal tool used to generate the files in the gen/ directory of the syn repository. This ensures that implementations for the Fold, Visit, and VisitMut traits remain synchronized with the actual AST.

Note: This program is intentionally slow and is not executed during the standard syn build process to optimize compile times. Only run this if you are modifying the AST and need to update the generated trait implementations.

Use the syn-dev project skeleton to troubleshoot syn parsers, particularly when adding support for new Rust syntax.

To use it:

1. Place a sample of the syntax you are working on into main.rs.
2. Run cargo check.

If the input parses successfully, the tool will reveal the resulting syntax tree. If the input fails to parse, it will display the error message and the position where the failure occurred.

The lazy-static example demonstrates how to use syn to inspect macro input and emit diagnostic messages (warnings and errors) tied to specific token spans.

• Warnings: Can be used to suggest better practices (e.g., warning against uncreative names like FOO).
• Errors: Can be used to prevent compilation of invalid or nonsensical syntax (e.g., refusing to lazily initialize the unit type ()).

To inspect the code generated by your procedural macro, you can use cargo expand or the unstable Rust compiler flags.

Using cargo-expand

To see the expanded code for a crate:

cargo expand

To see the expanded code for a specific test case:

cargo expand --test the_test_case

Using rustc flags

Alternatively, use the following command:

cargo rustc -- -Zunstable-options -Zunpretty=expanded

When building a procedural macro crate, ensure your Cargo.toml is configured with proc-macro = true and includes syn and quote as dependencies.

# Cargo.toml
[package]
...

[lib]
proc-macro = true

[dependencies]
syn = "3"
quote = "1"

When parsing Rust syntax, use these macros to handle delimited groups:

• bracketed!: Parses content inside square brackets [...].
• braced!: Parses content inside curly braces {...}.
• parenthesized!: Parses content inside parentheses (...).

The syn-codegen crate provides canonical Rust data structures for parsing the machine-readable syn.json file provided with every Syn release. This allows you to programmatically inspect the Syn syntax tree (types, tokens, and their structures) in Rust code.

To use it, include the syn.json file from the Syn repository and deserialize it into the Definitions struct using serde_json.

use syn_codegen::Definitions;

// Load the syn.json file
const SYN: &str = include_str!("../../syn.json");

fn main() {
    // Deserialize the JSON into the Definitions struct
    let defs: Definitions = serde_json::from_str(SYN).unwrap();

    // Iterate through the defined types
    for node in &defs.types {
        println!("syn::{}", node.ident);
    }
}

When writing procedural macros, you should report errors by emitting a compile_error! invocation in the generated code rather than panicking.

1. During initial parsing: Use the parse_macro_input! macro. It automatically converts syn::Result errors into compile_error! tokens.
2. For errors occurring after parsing: Use Error::to_compile_error() or Error::into_compile_error() to manually convert a syn::Error into a proc_macro2::TokenStream containing the error message.