Skip to main content

Crate parsyng

Crate parsyng 

Source
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 implementing Parse to turn a TokenStream into a typed value and ToTokens to turn it back into one.
  • quote! and quote_spanned! — build a token stream from almost-literal Rust syntax, interpolating #variables and repeating #(#items),* sequences, the same way the quote crate does.
  • proc_macro, proc_macro_attribute and proc_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 any ToTokens value, instead of hand-rolling proc_macro::TokenStream parsing and error reporting.
  • Parse and ToTokens derive 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 of syn, quote and proc-macro2.
  • Boilerplate: syn/quote-based macros need to hand-write a lot of boilerplate (parsing the input, matching on the Result, converting the output), even for simple macros. The proc_macro / proc_macro_attribute / proc_macro_derive helper attributes remove it.
  • Speed: syn takes a while to compile, and moxy even longer. parsyng compiles significantly faster than syn/quote, unsynn and moxy, and parses faster at runtime too; see BENCH.md for the numbers.
  • Grammar: unlike unsynn, which ships no Rust grammar, parsyng comes with an ast covering all of stable Rust (with the full feature).
  • Simplicity: moxy introduces many new concepts for writing macros. parsyng stays close to the syn/quote model (Parse, ToTokens, quote!), without adding much complexity.

§Minimum supported Rust version

Rust 1.95 or newer (edition 2024).

§Feature flags

  • parsing (default) — the Parse machinery, the ast, parse_quote! and the helper attributes. Without it only quote!, quote_spanned!, format_ident! and ToTokens remain.
  • 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, where clauses, attributes, visibility, literals, structs and enums, DeriveInput), which compiles noticeably faster.
  • extra-traits — Debug implementations for the AST and combinator types.
  • fallback — use the parsyng-fallback crate, a pure-Rust implementation of the token types (parsyng’s counterpart of proc-macro2), instead of the compiler’s built-in proc_macro. Required to call quote!, parse_quote! or any Parse/ToTokens implementation outside of an actual macro invocation (for example, in unit tests or a build.rs), since the real proc_macro crate panics when used outside the compiler’s macro expansion context. Unlike proc_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 with proc_macro & co. is annotated with the debug argument (e.g. #[parsyng::proc_macro(debug)]), pipe its generated output through rustfmt before printing it, instead of printing the raw, unformatted token stream. See examples/debug-attribute for why this is useful when a macro emits invalid syntax that the Rust parser itself can’t explain.

Modules§

astparsing
A tree of Rust syntax types, each implementing Parse to build itself from a ParseBuffer and ToTokens to turn itself back into tokens.
combinatorparsing
Generic building blocks for Parse/ToTokens implementations.
error
Error reporting for Parse implementations.
parseparsing
The ParseBuffer cursor and the Parse/Peek traits it drives.
proc_macroNon-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 Ident using format!-style syntax, spanned at Span::call_site.
parse_quoteparsing
Build a value of any Parse type from an almost-literal snippet of Rust syntax, combining quote! and parse::ParseBuffer::parse in 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§

Parseparsing
A type that can be parsed from a ParseBuffer.
ToTokens
A type that can be appended to a TokenStream.

Attribute Macros§

proc_macroparsing
Helper attribute to build new procedural macros. This replaces the standard library’s #[proc_macro] attribute.
proc_macro_attributeparsing
Helper attribute to build new procedural macro attributes. This replaces the standard library’s #[proc_macro_attribute] attribute.
proc_macro_deriveparsing
Helper attribute to build new derive macros. This replaces the standard library’s #[proc_macro_derive] attribute.

Derive Macros§

Parseparsing
Derives Parse by parsing each field, in declaration order, with its own Parse implementation.
ToTokensparsing
Derives ToTokens by appending each field’s own tokens, in declaration order.