[][src]Crate absolution

absolution

Build Status Current Version License: MIT/Apache-2.0

"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