Manishearth/absolution

absolution

"Freedom from syn"

This crate provides an introspectible token tree representation for writing Rust proc macros. It's still somewhat unstable: It's usable, however I haven't quite decided what I want the API to look like and may publish breaking changes. I welcome feedback of all kinds!

The proc-macro2 crate provides a token tree representation, however for backwards compatibility reasons, this representation isn't very introspectible and you have to further parse it to do almost anything with it. For example, the Literal type does not actually expose any further information about the contained literal, only that it is a literal.

Typically people pull in the awesome syn crate if they wish to introspect the code further than this; syn parses Rust code into a full, introspectible AST that is easy to work with. This is great when writing custom derives, where your proc macro is being applied to some Rust item.

However, bang-style procedural macros, like format!(), typically don't need to introspect the Rust AST, they just need to look at the tokens. For example, a very simple format!() implementation just needs to be able to read the initial format string, and then get the comma delimited token trees for the arguments. Pulling in an entire Rust parser into your dependency tree for this is somewhat overkill.

absolution provides an introspectible token tree representation, structured similarly to that of proc-macro2, for use in designing bang-style procedural macros.

Currently the proc-macro-hack crate still relies on syn to work, so this crate is not easy to use for any attribute-style proc macro. You can still use this crate with a manually-executed proc macro hack.

To use, simply use Into to convert from proc_macro or proc_macro2 token streams to absolution ones, and quote! to convert back.

extern crate proc_macro;
use absolution::{Ident, LitKind, Literal, TokenStream, TokenTree};
use quote::quote;

#[proc_macro]
pub fn make_func(tt: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let stream: TokenStream = tt.into();
    let first_token = &stream.tokens[0];
    let s = if let TokenTree::Literal(Literal {
        kind: LitKind::Str(s),
        ..
    }) = &first_token
    {
        s
    } else {
        panic!("Must start with a string!")
    };

    let ident = Ident {
        ident: s.to_string(),
        span: first_token.span(),
    };

    quote!(
        fn #ident() -> &'static str {
            #first_token
        }
    )
    .into()
}

See examples/string-enum for a more involved example.

License