vendor/syn/README.md

   1 Parser for Rust source code
   2 ===========================
   3
   4 [![Build Status](https://api.travis-ci.org/dtolnay/syn.svg?branch=master)](https://travis-ci.org/dtolnay/syn)
   5 [![Latest Version](https://img.shields.io/crates/v/syn.svg)](https://crates.io/crates/syn)
   6 [![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/syn/0.15/syn/)
   7 [![Rustc Version 1.15+](https://img.shields.io/badge/rustc-1.15+-lightgray.svg)](https://blog.rust-lang.org/2017/02/02/Rust-1.15.html)
   8
   9 Syn is a parsing library for parsing a stream of Rust tokens into a syntax tree
  10 of Rust source code.
  11
  12 Currently this library is geared toward use in Rust procedural macros, but
  13 contains some APIs that may be useful more generally.
  14
  15 [custom derive]: https://github.com/rust-lang/rfcs/blob/master/text/1681-macros-1.1.md
  16
  17 - **Data structures** — Syn provides a complete syntax tree that can represent
  18   any valid Rust source code. The syntax tree is rooted at [`syn::File`] which
  19   represents a full source file, but there are other entry points that may be
  20   useful to procedural macros including [`syn::Item`], [`syn::Expr`] and
  21   [`syn::Type`].
  22
  23 - **Custom derives** — Of particular interest to custom derives is
  24   [`syn::DeriveInput`] which is any of the three legal input items to a derive
  25   macro. An example below shows using this type in a library that can derive
  26   implementations of a trait of your own.
  27
  28 - **Parsing** — Parsing in Syn is built around [parser functions] with the
  29   signature `fn(ParseStream) -> Result<T>`. Every syntax tree node defined by
  30   Syn is individually parsable and may be used as a building block for custom
  31   syntaxes, or you may dream up your own brand new syntax without involving any
  32   of our syntax tree types.
  33
  34 - **Location information** — Every token parsed by Syn is associated with a
  35   `Span` that tracks line and column information back to the source of that
  36   token. These spans allow a procedural macro to display detailed error messages
  37   pointing to all the right places in the user's code. There is an example of
  38   this below.
  39
  40 - **Feature flags** — Functionality is aggressively feature gated so your
  41   procedural macros enable only what they need, and do not pay in compile time
  42   for all the rest.
  43
  44 [`syn::File`]: https://docs.rs/syn/0.15/syn/struct.File.html
  45 [`syn::Item`]: https://docs.rs/syn/0.15/syn/enum.Item.html
  46 [`syn::Expr`]: https://docs.rs/syn/0.15/syn/enum.Expr.html
  47 [`syn::Type`]: https://docs.rs/syn/0.15/syn/enum.Type.html
  48 [`syn::DeriveInput`]: https://docs.rs/syn/0.15/syn/struct.DeriveInput.html
  49 [parser functions]: https://docs.rs/syn/0.15/syn/parse/index.html
  50
  51 If you get stuck with anything involving procedural macros in Rust I am happy to
  52 provide help even if the issue is not related to Syn. Please file a ticket in
  53 this repo.
  54
  55 *Version requirement: Syn supports any compiler version back to Rust's very
  56 first support for procedural macros in Rust 1.15.0. Some features especially
  57 around error reporting are only available in newer compilers or on the nightly
  58 channel.*
  59
  60 [*Release notes*](https://github.com/dtolnay/syn/releases)
  61
  62 ## Example of a custom derive
  63
  64 The canonical custom derive using Syn looks like this. We write an ordinary Rust
  65 function tagged with a `proc_macro_derive` attribute and the name of the trait
  66 we are deriving. Any time that derive appears in the user's code, the Rust
  67 compiler passes their data structure as tokens into our macro. We get to execute
  68 arbitrary Rust code to figure out what to do with those tokens, then hand some
  69 tokens back to the compiler to compile into the user's crate.
  70
  71 [`TokenStream`]: https://doc.rust-lang.org/proc_macro/struct.TokenStream.html
  72
  73 ```toml
  74 [dependencies]
  75 syn = "0.15"
  76 quote = "0.6"
  77
  78 [lib]
  79 proc-macro = true
  80 ```
  81
  82 ```rust
  83 extern crate proc_macro;
  84
  85 use proc_macro::TokenStream;
  86 use quote::quote;
  87 use syn::{parse_macro_input, DeriveInput};
  88
  89 #[proc_macro_derive(MyMacro)]
  90 pub fn my_macro(input: TokenStream) -> TokenStream {
  91     // Parse the input tokens into a syntax tree
  92     let input = parse_macro_input!(input as DeriveInput);
  93
  94     // Build the output, possibly using quasi-quotation
  95     let expanded = quote! {
  96         // ...
  97     };
  98
  99     // Hand the output tokens back to the compiler
 100     TokenStream::from(expanded)
 101 }
 102 ```
 103
 104 The [`heapsize`] example directory shows a complete working Macros 1.1
 105 implementation of a custom derive. It works on any Rust compiler 1.15+. The
 106 example derives a `HeapSize` trait which computes an estimate of the amount of
 107 heap memory owned by a value.
 108
 109 [`heapsize`]: examples/heapsize
 110
 111 ```rust
 112 pub trait HeapSize {
 113     /// Total number of bytes of heap memory owned by `self`.
 114     fn heap_size_of_children(&self) -> usize;
 115 }
 116 ```
 117
 118 The custom derive allows users to write `#[derive(HeapSize)]` on data structures
 119 in their program.
 120
 121 ```rust
 122 #[derive(HeapSize)]
 123 struct Demo<'a, T: ?Sized> {
 124     a: Box<T>,
 125     b: u8,
 126     c: &'a str,
 127     d: String,
 128 }
 129 ```
 130
 131 ## Spans and error reporting
 132
 133 The token-based procedural macro API provides great control over where the
 134 compiler's error messages are displayed in user code. Consider the error the
 135 user sees if one of their field types does not implement `HeapSize`.
 136
 137 ```rust
 138 #[derive(HeapSize)]
 139 struct Broken {
 140     ok: String,
 141     bad: std::thread::Thread,
 142 }
 143 ```
 144
 145 By tracking span information all the way through the expansion of a procedural
 146 macro as shown in the `heapsize` example, token-based macros in Syn are able to
 147 trigger errors that directly pinpoint the source of the problem.
 148
 149 ```
 150 error[E0277]: the trait bound `std::thread::Thread: HeapSize` is not satisfied
 151  --> src/main.rs:7:5
 152   |
 153 7 |     bad: std::thread::Thread,
 154   |     ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `HeapSize` is not implemented for `std::thread::Thread`
 155 ```
 156
 157 ## Parsing a custom syntax
 158
 159 The [`lazy-static`] example directory shows the implementation of a
 160 `functionlike!(...)` procedural macro in which the input tokens are parsed using
 161 Syn's parsing API.
 162
 163 [`lazy-static`]: examples/lazy-static
 164
 165 The example reimplements the popular `lazy_static` crate from crates.io as a
 166 procedural macro.
 167
 168 ```
 169 lazy_static! {
 170     static ref USERNAME: Regex = Regex::new("^[a-z0-9_-]{3,16}$").unwrap();
 171 }
 172 ```
 173
 174 The implementation shows how to trigger custom warnings and error messages on
 175 the macro input.
 176
 177 ```
 178 warning: come on, pick a more creative name
 179   --> src/main.rs:10:16
 180    |
 181 10 |     static ref FOO: String = "lazy_static".to_owned();
 182    |                ^^^
 183 ```
 184
 185 ## Testing
 186
 187 When testing macros, we often care not just that the macro can be used
 188 successfully but also that when the macro is provided with invalid input it
 189 produces maximally helpful error messages. Consider using the [`trybuild`] crate
 190 to write tests for errors that are emitted by your macro or errors detected by
 191 the Rust compiler in the expanded code following misuse of the macro. Such tests
 192 help avoid regressions from later refactors that mistakenly make an error no
 193 longer trigger or be less helpful than it used to be.
 194
 195 [`trybuild`]: https://github.com/dtolnay/trybuild
 196
 197 ## Debugging
 198
 199 When developing a procedural macro it can be helpful to look at what the
 200 generated code looks like. Use `cargo rustc -- -Zunstable-options
 201 --pretty=expanded` or the [`cargo expand`] subcommand.
 202
 203 [`cargo expand`]: https://github.com/dtolnay/cargo-expand
 204
 205 To show the expanded code for some crate that uses your procedural macro, run
 206 `cargo expand` from that crate. To show the expanded code for one of your own
 207 test cases, run `cargo expand --test the_test_case` where the last argument is
 208 the name of the test file without the `.rs` extension.
 209
 210 This write-up by Brandon W Maister discusses debugging in more detail:
 211 [Debugging Rust's new Custom Derive system][debugging].
 212
 213 [debugging]: https://quodlibetor.github.io/posts/debugging-rusts-new-custom-derive-system/
 214
 215 ## Optional features
 216
 217 Syn puts a lot of functionality behind optional features in order to optimize
 218 compile time for the most common use cases. The following features are
 219 available.
 220
 221 - **`derive`** *(enabled by default)* — Data structures for representing the
 222   possible input to a custom derive, including structs and enums and types.
 223 - **`full`** — Data structures for representing the syntax tree of all valid
 224   Rust source code, including items and expressions.
 225 - **`parsing`** *(enabled by default)* — Ability to parse input tokens into a
 226   syntax tree node of a chosen type.
 227 - **`printing`** *(enabled by default)* — Ability to print a syntax tree node as
 228   tokens of Rust source code.
 229 - **`visit`** — Trait for traversing a syntax tree.
 230 - **`visit-mut`** — Trait for traversing and mutating in place a syntax tree.
 231 - **`fold`** — Trait for transforming an owned syntax tree.
 232 - **`clone-impls`** *(enabled by default)* — Clone impls for all syntax tree
 233   types.
 234 - **`extra-traits`** — Debug, Eq, PartialEq, Hash impls for all syntax tree
 235   types.
 236 - **`proc-macro`** *(enabled by default)* — Runtime dependency on the dynamic
 237   library libproc_macro from rustc toolchain.
 238
 239 ## Proc macro shim
 240
 241 Syn uses the [proc-macro2] crate to emulate the compiler's procedural macro API
 242 in a stable way that works all the way back to Rust 1.15.0. This shim makes it
 243 possible to write code without regard for whether the current compiler version
 244 supports the features we use.
 245
 246 In general all of your code should be written against proc-macro2 rather than
 247 proc-macro. The one exception is in the signatures of procedural macro entry
 248 points, which are required by the language to use `proc_macro::TokenStream`.
 249
 250 The proc-macro2 crate will automatically detect and use the compiler's data
 251 structures on sufficiently new compilers.
 252
 253 [proc-macro2]: https://github.com/alexcrichton/proc-macro2
 254
 255 <br>
 256
 257 #### License
 258
 259 <sup>
 260 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
 261 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
 262 </sup>
 263
 264 <br>
 265
 266 <sub>
 267 Unless you explicitly state otherwise, any contribution intentionally submitted
 268 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
 269 be dual licensed as above, without any additional terms or conditions.
 270 </sub>