Syn is a parsing library for parsing a stream of Rust tokens into a syntax
tree of Rust source code.

Currently this library is geared toward use in Rust procedural macros, but
contains some APIs that may be useful more generally.

Data structures — Syn provides a complete syntax tree that can
represent any valid Rust source code. The syntax tree is rooted at
syn::File which represents a full source file, but there are other
entry points that may be useful to procedural macros including
syn::Item, syn::Expr and syn::Type.

Custom derives — Of particular interest to custom derives is
syn::DeriveInput which is any of the three legal input items to a
derive macro. An example below shows using this type in a library that can
derive implementations of a trait of your own.

Parsing — Parsing in Syn is built around parser functions with the
signature fn(ParseStream) -> Result<T>. Every syntax tree node defined
by Syn is individually parsable and may be used as a building block for
custom syntaxes, or you may dream up your own brand new syntax without
involving any of our syntax tree types.

Location information — Every token parsed by Syn is associated with a
Span that tracks line and column information back to the source of that
token. These spans allow a procedural macro to display detailed error
messages pointing to all the right places in the user's code. There is an
example of this below.

Feature flags — Functionality is aggressively feature gated so your
procedural macros enable only what they need, and do not pay in compile
time for all the rest.

Version requirement: Syn supports any compiler version back to Rust's very
first support for procedural macros in Rust 1.15.0. Some features especially
around error reporting are only available in newer compilers or on the
nightly channel.

The canonical custom derive using Syn looks like this. We write an ordinary
Rust function tagged with a proc_macro_derive attribute and the name of
the trait we are deriving. Any time that derive appears in the user's code,
the Rust compiler passes their data structure as tokens into our macro. We
get to execute arbitrary Rust code to figure out what to do with those
tokens, then hand some tokens back to the compiler to compile into the
user's crate.

The heapsize example directory shows a complete working Macros 1.1
implementation of a custom derive. It works on any Rust compiler 1.15+.
The example derives a HeapSize trait which computes an estimate of the
amount of heap memory owned by a value.

pubtraitHeapSize {
/// Total number of bytes of heap memory owned by `self`.fnheap_size_of_children(&self) ->usize;
}

The custom derive allows users to write #[derive(HeapSize)] on data
structures in their program.

The token-based procedural macro API provides great control over where the
compiler's error messages are displayed in user code. Consider the error the
user sees if one of their field types does not implement HeapSize.

By tracking span information all the way through the expansion of a
procedural macro as shown in the heapsize example, token-based macros in
Syn are able to trigger errors that directly pinpoint the source of the
problem.

When developing a procedural macro it can be helpful to look at what the
generated code looks like. Use cargo rustc -- -Zunstable-options --pretty=expanded or the cargo expand subcommand.

To show the expanded code for some crate that uses your procedural macro,
run cargo expand from that crate. To show the expanded code for one of
your own test cases, run cargo expand --test the_test_case where the last
argument is the name of the test file without the .rs extension.