Crate 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 yet useful for any attribute-style proc macro.

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 more examples

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Structs

Group	A group of tokens, typically surrounded by Delimiters.
Ident	An identifier
LitFloat	Note: any - signs will be tokenized as preceeding Puncts
LitInt	An integer literal
Literal	A literal token
Punct	A punctuation token.
TokenStream	A stream of TokenTrees. This is typically what a proc macro will receive

Enums

Delimiter	Describes how a sequence of token trees is delimited.
LitKind	The kind of literal
PunctKind	The specific kind of punctuation token
Spacing	Whether an Punct is followed immediately by another Punct or followed by another token or whitespace.
TokenTree	A single node in the token tree, i.e. a single token. May contain more tokens via Group.

Traits

AsNative