Expand description
parsyng is a toolkit for writing Rust procedural macros: a parser for Rust
syntax plus a token-stream builder, filling the role that syn and
quote fill together, but built to be easier to use.
It gives you:
ast— a tree of Rust syntax types (items, expressions, types, patterns, generics, …), each implementingParseto turn aTokenStreaminto a typed value andToTokensto turn it back into one.quote!andquote_spanned!— build a token stream from almost-literal Rust syntax, interpolating#variables and repeating#(#items),*sequences, the same way thequotecrate does.proc_macro,proc_macro_attributeandproc_macro_derive— drop-in replacements for#[proc_macro],#[proc_macro_attribute]and#[proc_macro_derive]that let the annotated function take typed,Parse-implementing arguments and return anyToTokensvalue, instead of hand-rollingproc_macro::TokenStreamparsing and error reporting.ParseandToTokensderive macros, for implementing both traits on your own structs and enums field-by-field.
§Quick start
A minimal function-like macro that doubles an integer literal:
// in a crate with `[lib] proc-macro = true`
#[parsyng::proc_macro]
pub fn double(n: u32) -> u32 {
n * 2
}// in a crate depending on the macro crate above
assert_eq!(double!(21), 42);The attribute parses n out of the macro’s input using Parse (erroring
out with a compile_error! if that fails), calls the function body, and
turns the returned u32 back into tokens with ToTokens — no manual
TokenStream plumbing required. See proc_macro for the full
picture, including how to accept and return Result<T, Diagnostics> for
fallible macros.
For a #[derive(...)]-style macro built directly on the ast types
(the heapsize example, ported from syn’s own documentation), see
examples/heapsize in the repository.
§Building token streams with quote!
use parsyng::quote;
let name = "world";
let tokens = quote! {
println!("Hello, {}!", #name);
};#ident interpolates a value that implements ToTokens, #{ expr }
interpolates the result of an arbitrary expression, and #(...)* /
#(...),* repeats its body once per item yielded by an Iterator. See
quote! for the full syntax.
§Parsing token streams
use parsyng::ast::item::ItemStruct;
use parsyng::parse::ParseBuffer;
use parsyng::quote;
let source = quote! {
struct Point { x: f64, y: f64 }
};
let mut buffer = ParseBuffer::new(source);
let item: ItemStruct = buffer.parse().unwrap();
assert_eq!(item.ident().to_string(), "Point");Every ast node can be parsed this way. Parse is also implemented
for many standard types (u8..u128, bool, Option<T>, Vec<T>,
tuples, …) as well as combinators like combinator::Punctuated and
combinator::Either, so custom ast-like types built out of them get
parsing for free.
§Why not syn/unsynn/moxy?
The most widely used crate for writing procedural macros is syn. It is
powerful and relatively easy to use, but it also has some flaws this crate
tries to fix, without the trade-offs of alternatives like unsynn and
moxy:
- One dependency: a single crate in your
Cargo.toml, instead ofsyn,quoteandproc-macro2. - Boilerplate:
syn/quote-based macros need to hand-write a lot of boilerplate (parsing the input, matching on theResult, converting the output), even for simple macros. Theproc_macro/proc_macro_attribute/proc_macro_derivehelper attributes remove it. - Speed:
syntakes a while to compile, andmoxyeven longer.parsyngcompiles significantly faster thansyn/quote,unsynnandmoxy, and parses faster at runtime too; seeBENCH.mdfor the numbers. - Grammar: unlike
unsynn, which ships no Rust grammar,parsyngcomes with anastcovering all of stable Rust (with thefullfeature). - Simplicity:
moxyintroduces many new concepts for writing macros.parsyngstays close to thesyn/quotemodel (Parse,ToTokens,quote!), without adding much complexity.
§Minimum supported Rust version
Rust 1.95 or newer (edition 2024).
§Feature flags
parsing(default) — theParsemachinery, theast,parse_quote!and the helper attributes. Without it onlyquote!,quote_spanned!,format_ident!andToTokensremain.full— the whole Rust grammar: expressions, statements, patterns, function signatures, every item kind (ast::item::Item) and whole source files (ast::crate_source::Crate). Without it, the AST covers what derive macros need (types, paths, generics,whereclauses, attributes, visibility, literals, structs and enums,DeriveInput), which compiles noticeably faster.extra-traits—Debugimplementations for the AST and combinator types.fallback— use theparsyng-fallbackcrate, a pure-Rust implementation of the token types (parsyng’s counterpart ofproc-macro2), instead of the compiler’s built-inproc_macro. Required to callquote!,parse_quote!or anyParse/ToTokensimplementation outside of an actual macro invocation (for example, in unit tests or abuild.rs), since the realproc_macrocrate panics when used outside the compiler’s macro expansion context. Unlikeproc_macro2, it never forwards to the compiler; a proc-macro crate built with it still works, but its macros lose spans, so only enable it for code running outside the compiler (e.g. as a dev-dependency feature for tests).debug-pretty— when a macro built withproc_macro& co. is annotated with thedebugargument (e.g.#[parsyng::proc_macro(debug)]), pipe its generated output throughrustfmtbefore printing it, instead of printing the raw, unformatted token stream. Seeexamples/debug-attributefor why this is useful when a macro emits invalid syntax that the Rust parser itself can’t explain.
Modules§
- ast
parsing - A tree of Rust syntax types, each implementing
Parseto build itself from aParseBufferandToTokensto turn itself back into tokens. - combinator
parsing - Generic building blocks for
Parse/ToTokensimplementations. - error
- Error reporting for
Parseimplementations. - parse
parsing - The
ParseBuffercursor and theParse/Peektraits it drives. - proc_
macro Non- fallback - A support library for macro authors when defining new macros.
- proc_
macro_ ext - Helpers for proc-macro specific token manipulation.
Placeholder extension trait for
Literal, reserved for future proc-macro-specific token helpers.
Macros§
- Token
- Names a keyword or punctuation token type by its surface syntax. See the module docs for details.
- format_
ident - Build an
Identusingformat!-style syntax, spanned atSpan::call_site. - parse_
quote parsing - Build a value of any
Parsetype from an almost-literal snippet of Rust syntax, combiningquote!andparse::ParseBuffer::parsein one step. - quote
- Generates a [
proc_macro::TokenStream] from its input while interpolating variables. This works similarly to rust declarative macros, but using#instead of$for interpolation. - quote_
spanned - Like
quote!, but every generated token is built with the given [Span] instead of [Span::call_site].
Structs§
- Index
- The index of a tuple field, turning into an unsuffixed integer literal.
Traits§
- Parse
parsing - A type that can be parsed from a
ParseBuffer. - ToTokens
- A type that can be appended to a
TokenStream.
Attribute Macros§
- proc_
macro parsing - Helper attribute to build new procedural macros. This replaces the
standard library’s
#[proc_macro]attribute. - proc_
macro_ attribute parsing - Helper attribute to build new procedural macro attributes. This replaces
the standard library’s
#[proc_macro_attribute]attribute. - proc_
macro_ derive parsing - Helper attribute to build new derive macros. This replaces the standard
library’s
#[proc_macro_derive]attribute.