]>
Commit | Line | Data |
---|---|---|
fe692bf9 FG |
1 | /// Parse the input TokenStream of a macro, triggering a compile error if the |
2 | /// tokens fail to parse. | |
3 | /// | |
4 | /// Refer to the [`parse` module] documentation for more details about parsing | |
5 | /// in Syn. | |
6 | /// | |
7 | /// [`parse` module]: mod@crate::parse | |
8 | /// | |
9 | /// <br> | |
10 | /// | |
11 | /// # Intended usage | |
12 | /// | |
13 | /// This macro must be called from a function that returns | |
14 | /// `proc_macro::TokenStream`. Usually this will be your proc macro entry point, | |
15 | /// the function that has the #\[proc_macro\] / #\[proc_macro_derive\] / | |
16 | /// #\[proc_macro_attribute\] attribute. | |
17 | /// | |
18 | /// ``` | |
19 | /// # extern crate proc_macro; | |
20 | /// # | |
21 | /// use proc_macro::TokenStream; | |
22 | /// use syn::{parse_macro_input, Result}; | |
23 | /// use syn::parse::{Parse, ParseStream}; | |
24 | /// | |
25 | /// struct MyMacroInput { | |
26 | /// /* ... */ | |
27 | /// } | |
28 | /// | |
29 | /// impl Parse for MyMacroInput { | |
30 | /// fn parse(input: ParseStream) -> Result<Self> { | |
31 | /// /* ... */ | |
32 | /// # Ok(MyMacroInput {}) | |
33 | /// } | |
34 | /// } | |
35 | /// | |
36 | /// # const IGNORE: &str = stringify! { | |
37 | /// #[proc_macro] | |
38 | /// # }; | |
39 | /// pub fn my_macro(tokens: TokenStream) -> TokenStream { | |
40 | /// let input = parse_macro_input!(tokens as MyMacroInput); | |
41 | /// | |
42 | /// /* ... */ | |
43 | /// # TokenStream::new() | |
44 | /// } | |
45 | /// ``` | |
46 | /// | |
47 | /// <br> | |
48 | /// | |
49 | /// # Usage with Parser | |
50 | /// | |
51 | /// This macro can also be used with the [`Parser` trait] for types that have | |
52 | /// multiple ways that they can be parsed. | |
53 | /// | |
54 | /// [`Parser` trait]: crate::parse::Parser | |
55 | /// | |
56 | /// ``` | |
57 | /// # extern crate proc_macro; | |
58 | /// # | |
59 | /// # use proc_macro::TokenStream; | |
60 | /// # use syn::{parse_macro_input, Result}; | |
61 | /// # use syn::parse::ParseStream; | |
62 | /// # | |
63 | /// # struct MyMacroInput {} | |
64 | /// # | |
65 | /// impl MyMacroInput { | |
66 | /// fn parse_alternate(input: ParseStream) -> Result<Self> { | |
67 | /// /* ... */ | |
68 | /// # Ok(MyMacroInput {}) | |
69 | /// } | |
70 | /// } | |
71 | /// | |
72 | /// # const IGNORE: &str = stringify! { | |
73 | /// #[proc_macro] | |
74 | /// # }; | |
75 | /// pub fn my_macro(tokens: TokenStream) -> TokenStream { | |
76 | /// let input = parse_macro_input!(tokens with MyMacroInput::parse_alternate); | |
77 | /// | |
78 | /// /* ... */ | |
79 | /// # TokenStream::new() | |
80 | /// } | |
81 | /// ``` | |
82 | /// | |
83 | /// <br> | |
84 | /// | |
85 | /// # Expansion | |
86 | /// | |
87 | /// `parse_macro_input!($variable as $Type)` expands to something like: | |
88 | /// | |
89 | /// ```no_run | |
90 | /// # extern crate proc_macro; | |
91 | /// # | |
92 | /// # macro_rules! doc_test { | |
93 | /// # ($variable:ident as $Type:ty) => { | |
94 | /// match syn::parse::<$Type>($variable) { | |
95 | /// Ok(syntax_tree) => syntax_tree, | |
96 | /// Err(err) => return proc_macro::TokenStream::from(err.to_compile_error()), | |
97 | /// } | |
98 | /// # }; | |
99 | /// # } | |
100 | /// # | |
101 | /// # fn test(input: proc_macro::TokenStream) -> proc_macro::TokenStream { | |
102 | /// # let _ = doc_test!(input as syn::Ident); | |
103 | /// # proc_macro::TokenStream::new() | |
104 | /// # } | |
105 | /// ``` | |
106 | #[macro_export] | |
107 | #[cfg_attr(doc_cfg, doc(cfg(all(feature = "parsing", feature = "proc-macro"))))] | |
108 | macro_rules! parse_macro_input { | |
109 | ($tokenstream:ident as $ty:ty) => { | |
110 | match $crate::parse::<$ty>($tokenstream) { | |
111 | $crate::__private::Ok(data) => data, | |
112 | $crate::__private::Err(err) => { | |
113 | return $crate::__private::TokenStream::from(err.to_compile_error()); | |
114 | } | |
115 | } | |
116 | }; | |
117 | ($tokenstream:ident with $parser:path) => { | |
118 | match $crate::parse::Parser::parse($parser, $tokenstream) { | |
119 | $crate::__private::Ok(data) => data, | |
120 | $crate::__private::Err(err) => { | |
121 | return $crate::__private::TokenStream::from(err.to_compile_error()); | |
122 | } | |
123 | } | |
124 | }; | |
125 | ($tokenstream:ident) => { | |
126 | $crate::parse_macro_input!($tokenstream as _) | |
127 | }; | |
128 | } |