Lines Matching +full:proc +full:- +full:macro +full:- +full:api
4 [<img alt="github" src="https://img.shields.io/badge/github-dtolnay/syn-8da0cb?style=for-the-badge&…
5 [<img alt="crates.io" src="https://img.shields.io/crates/v/syn.svg?style=for-the-badge&color=fc8d62…
6 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-syn-66c2a5?style=for-the-badge&labelC…
7 …/github/actions/workflow/status/dtolnay/syn/ci.yml?branch=master&style=for-the-badge" height="20">…
15 - **Data structures** — Syn provides a complete syntax tree that can represent
21 - **Derives** — Of particular interest to derive macros is [`syn::DeriveInput`]
22 which is any of the three legal input items to a derive macro. An example
24 user-defined trait.
26 - **Parsing** — Parsing in Syn is built around [parser functions] with the
27 signature `fn(ParseStream) -> Result<T>`. Every syntax tree node defined by
32 - **Location information** — Every token parsed by Syn is associated with a
34 token. These spans allow a procedural macro to display detailed error messages
38 - **Feature flags** — Functionality is aggressively feature gated so your
58 working through [this procedural macro workshop][workshop] to get familiar with
62 [workshop]: https://github.com/dtolnay/proc-macro-workshop
66 ## Example of a derive macro
68 The canonical derive macro using Syn looks like this. We write an ordinary Rust
71 compiler passes their data structure as tokens into our macro. We get to execute
75 [`TokenStream`]: https://doc.rust-lang.org/proc_macro/struct.TokenStream.html
83 proc-macro = true
92 pub fn my_macro(input: TokenStream) -> TokenStream {
96 // Build the output, possibly using quasi-quotation
107 derive macro. The example derives a `HeapSize` trait which computes an estimate
115 fn heap_size_of_children(&self) -> usize;
119 The derive macro allows users to write `#[derive(HeapSize)]` on data structures
136 The token-based procedural macro API provides great control over where the
149 macro as shown in the `heapsize` example, token-based macros in Syn are able to
154 --> src/main.rs:7:5
164 The [`lazy-static`] example directory shows the implementation of a
165 `functionlike!(...)` procedural macro in which the input tokens are parsed using
166 Syn's parsing API.
168 [`lazy-static`]: examples/lazy-static
171 procedural macro.
175 static ref USERNAME: Regex = Regex::new("^[a-z0-9_-]{3,16}$").unwrap();
180 the macro input.
184 --> src/main.rs:10:16
194 When testing macros, we often care not just that the macro can be used
195 successfully but also that when the macro is provided with invalid input it
197 to write tests for errors that are emitted by your macro or errors detected by
198 the Rust compiler in the expanded code following misuse of the macro. Such tests
208 When developing a procedural macro it can be helpful to look at what the
209 generated code looks like. Use `cargo rustc -- -Zunstable-options
210 --pretty=expanded` or the [`cargo expand`] subcommand.
212 [`cargo expand`]: https://github.com/dtolnay/cargo-expand
214 To show the expanded code for some crate that uses your procedural macro, run
216 test cases, run `cargo expand --test the_test_case` where the last argument is
219 This write-up by Brandon W Maister discusses debugging in more detail:
222 [debugging]: https://quodlibetor.github.io/posts/debugging-rusts-new-custom-derive-system/
232 - **`derive`** *(enabled by default)* — Data structures for representing the
233 possible input to a derive macro, including structs and enums and types.
234 - **`full`** — Data structures for representing the syntax tree of all valid
236 - **`parsing`** *(enabled by default)* — Ability to parse input tokens into a
238 - **`printing`** *(enabled by default)* — Ability to print a syntax tree node as
240 - **`visit`** — Trait for traversing a syntax tree.
241 - **`visit-mut`** — Trait for traversing and mutating in place a syntax tree.
242 - **`fold`** — Trait for transforming an owned syntax tree.
243 - **`clone-impls`** *(enabled by default)* — Clone impls for all syntax tree
245 - **`extra-traits`** — Debug, Eq, PartialEq, Hash impls for all syntax tree
247 - **`proc-macro`** *(enabled by default)* — Runtime dependency on the dynamic
252 ## Proc macro shim
254 Syn operates on the token representation provided by the [proc-macro2] crate
255 from crates.io rather than using the compiler's built in proc-macro crate
257 procedural macro, such as in unit tests or build.rs, and we avoid needing
258 incompatible ecosystems for proc macros vs non-macro use cases.
260 In general all of your code should be written against proc-macro2 rather than
261 proc-macro. The one exception is in the signatures of procedural macro entry
264 The proc-macro2 crate will automatically detect and use the compiler's data
265 structures when a procedural macro is active.
267 [proc-macro2]: https://docs.rs/proc-macro2/1.0/proc_macro2/
274 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
275 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
282 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall