commit | caf1757c74591de79a3d2fc74acb2af5f8929e85 | [log] [tgz] |
---|---|---|
author | David Tolnay <dtolnay@gmail.com> | Fri May 26 16:42:55 2017 -0700 |
committer | David Tolnay <dtolnay@gmail.com> | Fri May 26 16:42:55 2017 -0700 |
tree | 950b2bae71225635992b8609057f2b0993e056f1 | |
parent | d630f9d842b19b552af12b75c87afcc941741669 [diff] |
Disable publish until proc-macro2 is figured out
Parse Rust source code without a Syntex dependency, intended for use with Macros 1.1.
Designed for fast compile time.
syn
(from scratch including all dependencies): 6 secondssyntex
/quasi
/aster
stack: 60+ secondsIf you get stuck with Macros 1.1 I am happy to provide help even if the issue is not related to syn. Please file a ticket in this repo.
[dependencies] syn = "0.11" quote = "0.3" [lib] proc-macro = true
extern crate proc_macro; use proc_macro::TokenStream; extern crate syn; #[macro_use] extern crate quote; #[proc_macro_derive(MyMacro)] pub fn my_macro(input: TokenStream) -> TokenStream { let source = input.to_string(); // Parse the string representation into a syntax tree let ast = syn::parse_derive_input(&source).unwrap(); // Build the output, possibly using quasi-quotation let expanded = quote! { // ... }; // Parse back to a token stream and return it expanded.parse().unwrap() }
Suppose we have the following simple trait which returns the number of fields in a struct:
trait NumFields { fn num_fields() -> usize; }
A complete Macros 1.1 implementation of #[derive(NumFields)]
based on syn
and quote
looks like this:
extern crate proc_macro; use proc_macro::TokenStream; extern crate syn; #[macro_use] extern crate quote; #[proc_macro_derive(NumFields)] pub fn num_fields(input: TokenStream) -> TokenStream { let source = input.to_string(); // Parse the string representation into a syntax tree let ast = syn::parse_derive_input(&source).unwrap(); // Build the output let expanded = expand_num_fields(&ast); // Return the generated impl as a TokenStream expanded.parse().unwrap() } fn expand_num_fields(ast: &syn::DeriveInput) -> quote::Tokens { let n = match ast.body { syn::Body::Struct(ref data) => data.fields().len(), syn::Body::Enum(_) => panic!("#[derive(NumFields)] can only be used with structs"), }; // Used in the quasi-quotation below as `#name` let name = &ast.ident; // Helper is provided for handling complex generic types correctly and effortlessly let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl(); quote! { // The generated impl impl #impl_generics ::mycrate::NumFields for #name #ty_generics #where_clause { fn num_fields() -> usize { #n } } } }
For a more elaborate example that involves trait bounds, enums, and different kinds of structs, check out DeepClone
and deep-clone-derive
.
Macros 1.1 has a restriction that your proc-macro crate must export nothing but proc_macro_derive
functions, and also proc_macro_derive
procedural macros cannot be used from the same crate in which they are defined. These restrictions may be lifted in the future but for now they make writing tests a bit trickier than for other types of code.
In particular, you will not be able to write test functions like #[test] fn it_works() { ... }
in line with your code. Instead, either put tests in a tests
directory or in a separate crate entirely.
Additionally, if your procedural macro implements a particular trait, that trait must be defined in a separate crate from the procedural macro.
As a concrete example, suppose your procedural macro crate is called my_derive
and it implements a trait called my_crate::MyTrait
. Your unit tests for the procedural macro can go in my_derive/tests/test.rs
or into a separate crate my_tests/tests/test.rs
. Either way the test would look something like this:
#[macro_use] extern crate my_derive; extern crate my_crate; use my_crate::MyTrait; #[test] fn it_works() { #[derive(MyTrait)] struct S { /* ... */ } /* test the thing */ }
When developing a procedural macro it can be helpful to look at what the generated code looks like. Use cargo rustc -- -Zunstable-options --pretty=expanded
or the cargo expand
subcommand.
To show the expanded code for some crate that uses your procedural macro, run cargo expand
from that crate. To show the expanded code for one of your own test cases, run cargo expand --test the_test_case
where the last argument is the name of the test file without the .rs
extension.
This write-up by Brandon W Maister discusses debugging in more detail: Debugging Rust's new Custom Derive system.
Syn puts a lot of functionality behind optional features in order to optimize compile time for the most common use cases. These are the available features and their effect on compile time. Dependencies are included in the compile times.
Features | Compile time | Functionality |
---|---|---|
(none) | 3 sec | The data structures representing the AST of Rust structs, enums, and types. |
parsing | 6 sec | Parsing Rust source code containing structs and enums into an AST. |
printing | 4 sec | Printing an AST of structs and enums as Rust source code. |
parsing, printing | 6 sec | This is the default. Parsing and printing of Rust structs and enums. This is typically what you want for implementing Macros 1.1 custom derives. |
full | 4 sec | The data structures representing the full AST of all possible Rust code. |
full, parsing | 9 sec | Parsing any valid Rust source code to an AST. |
full, printing | 6 sec | Turning an AST into Rust source code. |
full, parsing, printing | 11 sec | Parsing and printing any Rust syntax. |
Licensed under either of
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.