[−][src]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 |
Ident | An identifier |
LitFloat | Note: any - signs will be tokenized as preceeding |
LitInt | An integer literal |
Literal | A literal token |
Punct | A punctuation token. |
TokenStream | A stream of |
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 |
TokenTree | A single node in the token tree, i.e. a single token. May contain more
tokens via |
Traits
AsNative |