src/vendor/quote/README.md

   1 Rust Quasi-Quoting
   2 ==================
   3
   4 [![Build Status](https://api.travis-ci.org/dtolnay/quote.svg?branch=master)](https://travis-ci.org/dtolnay/quote)
   5 [![Latest Version](https://img.shields.io/crates/v/quote.svg)](https://crates.io/crates/quote)
   6 [![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/quote/)
   7
   8 Quasi-quoting without a Syntex dependency, intended for use with [Macros
   9 1.1](https://github.com/rust-lang/rfcs/blob/master/text/1681-macros-1.1.md).
  10
  11 ```toml
  12 [dependencies]
  13 quote = "0.3"
  14 ```
  15
  16 ```rust
  17 #[macro_use]
  18 extern crate quote;
  19 ```
  20
  21 ## What is quasi-quoting?
  22
  23 Quasi-quoting is a way of writing code and treating it as data, similar to
  24 writing code inside of a double-quoted string literal except more friendly to
  25 your text editor or IDE. It does not get in the way of syntax highlighting,
  26 brace matching, indentation, or autocompletion, all of which you would lose by
  27 writing code inside of double quotes.
  28
  29 Check out
  30 [my meetup talk](https://air.mozilla.org/rust-meetup-december-2016-12-15/)
  31 on the topic to learn more about the use case. Start the video at 3:00.
  32
  33 This crate is motivated by the Macros 1.1 use case, but is a general-purpose
  34 Rust quasi-quoting library and is not specific to procedural macros.
  35
  36 ## Syntax
  37
  38 The quote crate provides a `quote!` macro within which you can write Rust code
  39 that gets packaged into a `quote::Tokens` and can be treated as data. You should
  40 think of `quote::Tokens` as representing a fragment of Rust source code. Call
  41 `to_string()` or `as_str()` on a Tokens to get back the fragment of source code
  42 as a string.
  43
  44 Within the `quote!` macro, interpolation is done with `#var`. Any type
  45 implementing the `quote::ToTokens` trait can be interpolated. This includes most
  46 Rust primitive types as well as most of the syntax tree types from
  47 [`syn`](https://github.com/dtolnay/syn).
  48
  49 ```rust
  50 let tokens = quote! {
  51     struct SerializeWith #generics #where_clause {
  52         value: &'a #field_ty,
  53         phantom: ::std::marker::PhantomData<#item_ty>,
  54     }
  55
  56     impl #generics serde::Serialize for SerializeWith #generics #where_clause {
  57         fn serialize<S>(&self, s: &mut S) -> Result<(), S::Error>
  58             where S: serde::Serializer
  59         {
  60             #path(self.value, s)
  61         }
  62     }
  63
  64     SerializeWith {
  65         value: #value,
  66         phantom: ::std::marker::PhantomData::<#item_ty>,
  67     }
  68 };
  69 ```
  70
  71 Repetition is done using `#(...)*` or `#(...),*` very similar to `macro_rules!`:
  72
  73 - `#(#var)*` - no separators
  74 - `#(#var),*` - the character before the asterisk is used as a separator
  75 - `#( struct #var; )*` - the repetition can contain other things
  76 - `#( #k => println!("{}", #v), )*` - even multiple interpolations
  77
  78 Tokens can be interpolated into other quotes:
  79
  80 ```rust
  81 let t = quote! { /* ... */ };
  82 return quote! { /* ... */ #t /* ... */ };
  83 ```
  84
  85 The `quote!` macro relies on deep recursion so some large invocations may fail
  86 with "recursion limit reached" when you compile. If it fails, bump up the
  87 recursion limit by adding `#![recursion_limit = "128"]` to your crate. An even
  88 higher limit may be necessary for especially large invocations. You don't need
  89 this unless the compiler tells you that you need it.
  90
  91 ## License
  92
  93 Licensed under either of
  94
  95  * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
  96  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
  97
  98 at your option.
  99
 100 ### Contribution
 101
 102 Unless you explicitly state otherwise, any contribution intentionally submitted
 103 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
 104 be dual licensed as above, without any additional terms or conditions.