David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 1 | /// Quasi-quotation macro that accepts input like the [`quote!`] macro but uses |
| 2 | /// type inference to figure out a return type for those tokens. |
| 3 | /// |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 4 | /// [`quote!`]: https://docs.rs/quote/1.0/quote/index.html |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 5 | /// |
David Tolnay | d85a881 | 2018-08-31 11:09:57 -0700 | [diff] [blame] | 6 | /// The return type can be any syntax tree node that implements the [`Parse`] |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 7 | /// trait. |
| 8 | /// |
Chih-Hung Hsieh | a0ab740 | 2020-10-26 13:16:52 -0700 | [diff] [blame] | 9 | /// [`Parse`]: crate::parse::Parse |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 10 | /// |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 11 | /// ``` |
David Tolnay | fd5b117 | 2018-12-31 17:54:36 -0500 | [diff] [blame] | 12 | /// use quote::quote; |
| 13 | /// use syn::{parse_quote, Stmt}; |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 14 | /// |
| 15 | /// fn main() { |
| 16 | /// let name = quote!(v); |
| 17 | /// let ty = quote!(u8); |
| 18 | /// |
| 19 | /// let stmt: Stmt = parse_quote! { |
| 20 | /// let #name: #ty = Default::default(); |
| 21 | /// }; |
| 22 | /// |
| 23 | /// println!("{:#?}", stmt); |
| 24 | /// } |
| 25 | /// ``` |
| 26 | /// |
Haibo Huang | 4fbebf9 | 2020-05-26 17:08:50 -0700 | [diff] [blame] | 27 | /// *This macro is available only if Syn is built with the `"parsing"` feature, |
David Tolnay | 491680a | 2018-01-23 00:34:40 -0800 | [diff] [blame] | 28 | /// although interpolation of syntax tree nodes into the quoted tokens is only |
| 29 | /// supported if Syn is built with the `"printing"` feature as well.* |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 30 | /// |
| 31 | /// # Example |
| 32 | /// |
| 33 | /// The following helper function adds a bound `T: HeapSize` to every type |
| 34 | /// parameter `T` in the input generics. |
| 35 | /// |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 36 | /// ``` |
David Tolnay | fd5b117 | 2018-12-31 17:54:36 -0500 | [diff] [blame] | 37 | /// use syn::{parse_quote, Generics, GenericParam}; |
David Tolnay | 9b00f65 | 2018-09-01 10:31:02 -0700 | [diff] [blame] | 38 | /// |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 39 | /// // Add a bound `T: HeapSize` to every type parameter T. |
| 40 | /// fn add_trait_bounds(mut generics: Generics) -> Generics { |
| 41 | /// for param in &mut generics.params { |
David Tolnay | 6533607 | 2019-04-22 23:10:52 -0700 | [diff] [blame] | 42 | /// if let GenericParam::Type(type_param) = param { |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 43 | /// type_param.bounds.push(parse_quote!(HeapSize)); |
| 44 | /// } |
| 45 | /// } |
| 46 | /// generics |
| 47 | /// } |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 48 | /// ``` |
| 49 | /// |
| 50 | /// # Special cases |
| 51 | /// |
| 52 | /// This macro can parse the following additional types as a special case even |
David Tolnay | d85a881 | 2018-08-31 11:09:57 -0700 | [diff] [blame] | 53 | /// though they do not implement the `Parse` trait. |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 54 | /// |
| 55 | /// - [`Attribute`] — parses one attribute, allowing either outer like `#[...]` |
| 56 | /// or inner like `#![...]` |
| 57 | /// - [`Punctuated<T, P>`] — parses zero or more `T` separated by punctuation |
| 58 | /// `P` with optional trailing punctuation |
Chih-Hung Hsieh | 218e269 | 2020-03-20 13:02:10 -0700 | [diff] [blame] | 59 | /// - [`Vec<Stmt>`] — parses the same as `Block::parse_within` |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 60 | /// |
Chih-Hung Hsieh | a0ab740 | 2020-10-26 13:16:52 -0700 | [diff] [blame] | 61 | /// [`Punctuated<T, P>`]: crate::punctuated::Punctuated |
Chih-Hung Hsieh | 218e269 | 2020-03-20 13:02:10 -0700 | [diff] [blame] | 62 | /// [`Vec<Stmt>`]: Block::parse_within |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 63 | /// |
| 64 | /// # Panics |
| 65 | /// |
| 66 | /// Panics if the tokens fail to parse as the expected syntax tree type. The |
| 67 | /// caller is responsible for ensuring that the input tokens are syntactically |
| 68 | /// valid. |
David Tolnay | b8dec88 | 2019-07-20 09:46:14 -0700 | [diff] [blame] | 69 | // |
| 70 | // TODO: allow Punctuated to be inferred as intra doc link, currently blocked on |
| 71 | // https://github.com/rust-lang/rust/issues/62834 |
Haibo Huang | ec2e2eb | 2021-01-05 21:38:44 -0800 | [diff] [blame] | 72 | #[cfg_attr(doc_cfg, doc(cfg(all(feature = "parsing", feature = "printing"))))] |
Haibo Huang | 4fbebf9 | 2020-05-26 17:08:50 -0700 | [diff] [blame] | 73 | #[macro_export] |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 74 | macro_rules! parse_quote { |
| 75 | ($($tt:tt)*) => { |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 76 | $crate::parse_quote::parse( |
Haibo Huang | ec2e2eb | 2021-01-05 21:38:44 -0800 | [diff] [blame] | 77 | $crate::__private::From::from( |
| 78 | $crate::__private::quote::quote!($($tt)*) |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 79 | ) |
| 80 | ) |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 81 | }; |
| 82 | } |
| 83 | |
| 84 | //////////////////////////////////////////////////////////////////////////////// |
David Tolnay | 06faaca | 2018-09-01 20:25:04 -0700 | [diff] [blame] | 85 | // Can parse any type that implements Parse. |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 86 | |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 87 | use crate::parse::{Parse, ParseStream, Parser, Result}; |
David Tolnay | e82a2b1 | 2018-08-30 16:31:10 -0700 | [diff] [blame] | 88 | use proc_macro2::TokenStream; |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 89 | |
| 90 | // Not public API. |
| 91 | #[doc(hidden)] |
David Tolnay | 7d6a7b8 | 2018-01-23 00:42:22 -0800 | [diff] [blame] | 92 | pub fn parse<T: ParseQuote>(token_stream: TokenStream) -> T { |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 93 | let parser = T::parse; |
| 94 | match parser.parse2(token_stream) { |
| 95 | Ok(t) => t, |
David Tolnay | 40c0611 | 2018-08-30 16:14:50 -0700 | [diff] [blame] | 96 | Err(err) => panic!("{}", err), |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 97 | } |
| 98 | } |
| 99 | |
| 100 | // Not public API. |
| 101 | #[doc(hidden)] |
| 102 | pub trait ParseQuote: Sized { |
David Tolnay | 40c0611 | 2018-08-30 16:14:50 -0700 | [diff] [blame] | 103 | fn parse(input: ParseStream) -> Result<Self>; |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 104 | } |
| 105 | |
David Tolnay | 40c0611 | 2018-08-30 16:14:50 -0700 | [diff] [blame] | 106 | impl<T: Parse> ParseQuote for T { |
| 107 | fn parse(input: ParseStream) -> Result<Self> { |
| 108 | <T as Parse>::parse(input) |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 109 | } |
| 110 | } |
| 111 | |
| 112 | //////////////////////////////////////////////////////////////////////////////// |
| 113 | // Any other types that we want `parse_quote!` to be able to parse. |
| 114 | |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 115 | use crate::punctuated::Punctuated; |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 116 | #[cfg(any(feature = "full", feature = "derive"))] |
Chih-Hung Hsieh | 467ea21 | 2019-10-31 17:36:47 -0700 | [diff] [blame] | 117 | use crate::{attr, Attribute}; |
Chih-Hung Hsieh | 218e269 | 2020-03-20 13:02:10 -0700 | [diff] [blame] | 118 | #[cfg(feature = "full")] |
| 119 | use crate::{Block, Stmt}; |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 120 | |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 121 | #[cfg(any(feature = "full", feature = "derive"))] |
| 122 | impl ParseQuote for Attribute { |
David Tolnay | 40c0611 | 2018-08-30 16:14:50 -0700 | [diff] [blame] | 123 | fn parse(input: ParseStream) -> Result<Self> { |
| 124 | if input.peek(Token![#]) && input.peek2(Token![!]) { |
| 125 | attr::parsing::single_parse_inner(input) |
| 126 | } else { |
| 127 | attr::parsing::single_parse_outer(input) |
| 128 | } |
David Tolnay | e83ef5a | 2018-01-11 15:18:36 -0800 | [diff] [blame] | 129 | } |
| 130 | } |
David Tolnay | 024b576 | 2018-08-31 11:11:53 -0700 | [diff] [blame] | 131 | |
| 132 | impl<T: Parse, P: Parse> ParseQuote for Punctuated<T, P> { |
| 133 | fn parse(input: ParseStream) -> Result<Self> { |
| 134 | Self::parse_terminated(input) |
| 135 | } |
| 136 | } |
Chih-Hung Hsieh | 218e269 | 2020-03-20 13:02:10 -0700 | [diff] [blame] | 137 | |
| 138 | #[cfg(feature = "full")] |
| 139 | impl ParseQuote for Vec<Stmt> { |
| 140 | fn parse(input: ParseStream) -> Result<Self> { |
| 141 | Block::parse_within(input) |
| 142 | } |
| 143 | } |