src/vendor/syn-0.12.15/README.md

   1 Nom 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.12/syn/)
   7
   8 Syn is a parsing library for parsing a stream of Rust tokens into a syntax tree
   9 of Rust source code.
  10
  11 Currently this library is geared toward the [custom derive] use case but
  12 contains some APIs that may be useful for Rust procedural macros more generally.
  13
  14 [custom derive]: https://github.com/rust-lang/rfcs/blob/master/text/1681-macros-1.1.md
  15
  16 - **Data structures** — Syn provides a complete syntax tree that can represent
  17   any valid Rust source code. The syntax tree is rooted at [`syn::File`] which
  18   represents a full source file, but there are other entry points that may be
  19   useful to procedural macros including [`syn::Item`], [`syn::Expr`] and
  20   [`syn::Type`].
  21
  22 - **Custom derives** — Of particular interest to custom derives is
  23   [`syn::DeriveInput`] which is any of the three legal input items to a derive
  24   macro. An example below shows using this type in a library that can derive
  25   implementations of a trait of your own.
  26
  27 - **Parser combinators** — Parsing in Syn is built on a suite of public parser
  28   combinator macros that you can use for parsing any token-based syntax you
  29   dream up within a `functionlike!(...)` procedural macro. Every syntax tree
  30   node defined by Syn is individually parsable and may be used as a building
  31   block for custom syntaxes, or you may do it all yourself working from the most
  32   primitive tokens.
  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.12/syn/struct.File.html
  45 [`syn::Item`]: https://docs.rs/syn/0.12/syn/enum.Item.html
  46 [`syn::Expr`]: https://docs.rs/syn/0.12/syn/enum.Expr.html
  47 [`syn::Type`]: https://docs.rs/syn/0.12/syn/enum.Type.html
  48 [`syn::DeriveInput`]: https://docs.rs/syn/0.12/syn/struct.DeriveInput.html
  49
  50 If you get stuck with anything involving procedural macros in Rust I am happy to
  51 provide help even if the issue is not related to Syn. Please file a ticket in
  52 this repo.
  53
  54 *Version requirement: Syn supports any compiler version back to Rust's very
  55 first support for procedural macros in Rust 1.15.0. Some features especially
  56 around error reporting are only available in newer compilers or on the nightly
  57 channel.*
  58
  59 ## Example of a custom derive
  60
  61 The canonical custom derive using Syn looks like this. We write an ordinary Rust
  62 function tagged with a `proc_macro_derive` attribute and the name of the trait
  63 we are deriving. Any time that derive appears in the user's code, the Rust
  64 compiler passes their data structure as tokens into our macro. We get to execute
  65 arbitrary Rust code to figure out what to do with those tokens, then hand some
  66 tokens back to the compiler to compile into the user's crate.
  67
  68 [`TokenStream`]: https://doc.rust-lang.org/proc_macro/struct.TokenStream.html
  69
  70 ```toml
  71 [dependencies]
  72 syn = "0.12"
  73 quote = "0.4"
  74
  75 [lib]
  76 proc-macro = true
  77 ```
  78
  79 ```rust
  80 extern crate proc_macro;
  81 extern crate syn;
  82
  83 #[macro_use]
  84 extern crate quote;
  85
  86 use proc_macro::TokenStream;
  87 use syn::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: DeriveInput = syn::parse(input).unwrap();
  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     expanded.into()
 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.0. 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 [`heapsize2`] example directory is an extension of the `heapsize` example
 134 that demonstrates some of the hygiene and error reporting properties of Macros
 135 2.0. This example currently requires a nightly Rust compiler \>=1.24.0-nightly
 136 but we are working to stabilize all of the APIs involved.
 137
 138 [`heapsize2`]: examples/heapsize2
 139
 140 The token-based procedural macro API provides great control over where the
 141 compiler's error messages are displayed in user code. Consider the error the
 142 user sees if one of their field types does not implement `HeapSize`.
 143
 144 ```rust
 145 #[derive(HeapSize)]
 146 struct Broken {
 147     ok: String,
 148     bad: std::thread::Thread,
 149 }
 150 ```
 151
 152 In the Macros 1.1 string-based procedural macro world, the resulting error would
 153 point unhelpfully to the invocation of the derive macro and not to the actual
 154 problematic field.
 155
 156 ```
 157 error[E0599]: no method named `heap_size_of_children` found for type `std::thread::Thread` in the current scope
 158  --> src/main.rs:4:10
 159   |
 160 4 | #[derive(HeapSize)]
 161   |          ^^^^^^^^
 162 ```
 163
 164 By tracking span information all the way through the expansion of a procedural
 165 macro as shown in the `heapsize2` example, token-based macros in Syn are able to
 166 trigger errors that directly pinpoint the source of the problem.
 167
 168 ```
 169 error[E0277]: the trait bound `std::thread::Thread: HeapSize` is not satisfied
 170  --> src/main.rs:7:5
 171   |
 172 7 |     bad: std::thread::Thread,
 173   |     ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `HeapSize` is not implemented for `std::thread::Thread`
 174 ```
 175
 176 ## Parsing a custom syntax using combinators
 177
 178 The [`lazy-static`] example directory shows the implementation of a
 179 `functionlike!(...)` procedural macro in which the input tokens are parsed using
 180 [`nom`]-style parser combinators.
 181
 182 [`lazy-static`]: examples/lazy-static
 183 [`nom`]: https://github.com/Geal/nom
 184
 185 The example reimplements the popular `lazy_static` crate from crates.io as a
 186 procedural macro.
 187
 188 ```
 189 lazy_static! {
 190     static ref USERNAME: Regex = Regex::new("^[a-z0-9_-]{3,16}$").unwrap();
 191 }
 192 ```
 193
 194 The implementation shows how to trigger custom warnings and error messages on
 195 the macro input.
 196
 197 ```
 198 warning: come on, pick a more creative name
 199   --> src/main.rs:10:16
 200    |
 201 10 |     static ref FOO: String = "lazy_static".to_owned();
 202    |                ^^^
 203 ```
 204
 205 ## Debugging
 206
 207 When developing a procedural macro it can be helpful to look at what the
 208 generated code looks like. Use `cargo rustc -- -Zunstable-options
 209 --pretty=expanded` or the [`cargo expand`] subcommand.
 210
 211 [`cargo expand`]: https://github.com/dtolnay/cargo-expand
 212
 213 To show the expanded code for some crate that uses your procedural macro, run
 214 `cargo expand` from that crate. To show the expanded code for one of your own
 215 test cases, run `cargo expand --test the_test_case` where the last argument is
 216 the name of the test file without the `.rs` extension.
 217
 218 This write-up by Brandon W Maister discusses debugging in more detail:
 219 [Debugging Rust's new Custom Derive system][debugging].
 220
 221 [debugging]: https://quodlibetor.github.io/posts/debugging-rusts-new-custom-derive-system/
 222
 223 ## Optional features
 224
 225 Syn puts a lot of functionality behind optional features in order to optimize
 226 compile time for the most common use cases. The following features are
 227 available.
 228
 229 - **`derive`** *(enabled by default)* — Data structures for representing the
 230   possible input to a custom derive, including structs and enums and types.
 231 - **`full`** — Data structures for representing the syntax tree of all valid
 232   Rust source code, including items and expressions.
 233 - **`parsing`** *(enabled by default)* — Ability to parse input tokens into a
 234   syntax tree node of a chosen type.
 235 - **`printing`** *(enabled by default)* — Ability to print a syntax tree node as
 236   tokens of Rust source code.
 237 - **`visit`** — Trait for traversing a syntax tree.
 238 - **`visit-mut`** — Trait for traversing and mutating in place a syntax tree.
 239 - **`fold`** — Trait for transforming an owned syntax tree.
 240 - **`clone-impls`** *(enabled by default)* — Clone impls for all syntax tree
 241   types.
 242 - **`extra-traits`** — Debug, Eq, PartialEq, Hash impls for all syntax tree
 243   types.
 244
 245 ## Nightly features
 246
 247 By default Syn uses the [`proc-macro2`] crate to emulate the nightly compiler's
 248 procedural macro API in a stable way that works all the way back to Rust 1.15.0.
 249 This shim makes it possible to write code without regard for whether the current
 250 compiler version supports the features we use.
 251
 252 [`proc-macro2`]: https://github.com/alexcrichton/proc-macro2
 253
 254 On a nightly compiler, to eliminate the stable shim and use the compiler's
 255 `proc-macro` directly, add `proc-macro2` to your Cargo.toml and set its
 256 `"nightly"` feature which bypasses the stable shim.
 257
 258 ```toml
 259 [dependencies]
 260 syn = "0.12"
 261 proc-macro2 = { version = "0.2", features = ["nightly"] }
 262 ```
 263
 264 ## License
 265
 266 Licensed under either of
 267
 268  * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 269  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 270
 271 at your option.
 272
 273 ### Contribution
 274
 275 Unless you explicitly state otherwise, any contribution intentionally submitted
 276 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
 277 be dual licensed as above, without any additional terms or conditions.