]>
Commit | Line | Data |
---|---|---|
e74abb32 XL |
1 | //! Parsing interface for parsing a token stream into a syntax tree node. |
2 | //! | |
3 | //! Parsing in Syn is built on parser functions that take in a [`ParseStream`] | |
4 | //! and produce a [`Result<T>`] where `T` is some syntax tree node. Underlying | |
5 | //! these parser functions is a lower level mechanism built around the | |
6 | //! [`Cursor`] type. `Cursor` is a cheaply copyable cursor over a range of | |
7 | //! tokens in a token stream. | |
8 | //! | |
5869c6ff XL |
9 | //! [`Result<T>`]: Result |
10 | //! [`Cursor`]: crate::buffer::Cursor | |
e74abb32 XL |
11 | //! |
12 | //! # Example | |
13 | //! | |
14 | //! Here is a snippet of parsing code to get a feel for the style of the | |
15 | //! library. We define data structures for a subset of Rust syntax including | |
16 | //! enums (not shown) and structs, then provide implementations of the [`Parse`] | |
17 | //! trait to parse these syntax tree data structures from a token stream. | |
18 | //! | |
19 | //! Once `Parse` impls have been defined, they can be called conveniently from a | |
20 | //! procedural macro through [`parse_macro_input!`] as shown at the bottom of | |
21 | //! the snippet. If the caller provides syntactically invalid input to the | |
22 | //! procedural macro, they will receive a helpful compiler error message | |
23 | //! pointing out the exact token that triggered the failure to parse. | |
24 | //! | |
5869c6ff | 25 | //! [`parse_macro_input!`]: crate::parse_macro_input! |
e74abb32 XL |
26 | //! |
27 | //! ``` | |
f035d41b XL |
28 | //! # extern crate proc_macro; |
29 | //! # | |
e74abb32 XL |
30 | //! use proc_macro::TokenStream; |
31 | //! use syn::{braced, parse_macro_input, token, Field, Ident, Result, Token}; | |
32 | //! use syn::parse::{Parse, ParseStream}; | |
33 | //! use syn::punctuated::Punctuated; | |
34 | //! | |
35 | //! enum Item { | |
36 | //! Struct(ItemStruct), | |
37 | //! Enum(ItemEnum), | |
38 | //! } | |
39 | //! | |
40 | //! struct ItemStruct { | |
41 | //! struct_token: Token![struct], | |
42 | //! ident: Ident, | |
43 | //! brace_token: token::Brace, | |
44 | //! fields: Punctuated<Field, Token![,]>, | |
45 | //! } | |
46 | //! # | |
47 | //! # enum ItemEnum {} | |
48 | //! | |
49 | //! impl Parse for Item { | |
50 | //! fn parse(input: ParseStream) -> Result<Self> { | |
51 | //! let lookahead = input.lookahead1(); | |
52 | //! if lookahead.peek(Token![struct]) { | |
53 | //! input.parse().map(Item::Struct) | |
54 | //! } else if lookahead.peek(Token![enum]) { | |
55 | //! input.parse().map(Item::Enum) | |
56 | //! } else { | |
57 | //! Err(lookahead.error()) | |
58 | //! } | |
59 | //! } | |
60 | //! } | |
61 | //! | |
62 | //! impl Parse for ItemStruct { | |
63 | //! fn parse(input: ParseStream) -> Result<Self> { | |
64 | //! let content; | |
65 | //! Ok(ItemStruct { | |
66 | //! struct_token: input.parse()?, | |
67 | //! ident: input.parse()?, | |
68 | //! brace_token: braced!(content in input), | |
69 | //! fields: content.parse_terminated(Field::parse_named)?, | |
70 | //! }) | |
71 | //! } | |
72 | //! } | |
73 | //! # | |
74 | //! # impl Parse for ItemEnum { | |
75 | //! # fn parse(input: ParseStream) -> Result<Self> { | |
76 | //! # unimplemented!() | |
77 | //! # } | |
78 | //! # } | |
79 | //! | |
80 | //! # const IGNORE: &str = stringify! { | |
81 | //! #[proc_macro] | |
82 | //! # }; | |
83 | //! pub fn my_macro(tokens: TokenStream) -> TokenStream { | |
84 | //! let input = parse_macro_input!(tokens as Item); | |
85 | //! | |
86 | //! /* ... */ | |
87 | //! # "".parse().unwrap() | |
88 | //! } | |
89 | //! ``` | |
90 | //! | |
91 | //! # The `syn::parse*` functions | |
92 | //! | |
93 | //! The [`syn::parse`], [`syn::parse2`], and [`syn::parse_str`] functions serve | |
94 | //! as an entry point for parsing syntax tree nodes that can be parsed in an | |
95 | //! obvious default way. These functions can return any syntax tree node that | |
96 | //! implements the [`Parse`] trait, which includes most types in Syn. | |
97 | //! | |
5869c6ff XL |
98 | //! [`syn::parse`]: crate::parse() |
99 | //! [`syn::parse2`]: crate::parse2() | |
100 | //! [`syn::parse_str`]: crate::parse_str() | |
e74abb32 XL |
101 | //! |
102 | //! ``` | |
103 | //! use syn::Type; | |
104 | //! | |
105 | //! # fn run_parser() -> syn::Result<()> { | |
106 | //! let t: Type = syn::parse_str("std::collections::HashMap<String, Value>")?; | |
107 | //! # Ok(()) | |
108 | //! # } | |
109 | //! # | |
60c5eb7d | 110 | //! # run_parser().unwrap(); |
e74abb32 XL |
111 | //! ``` |
112 | //! | |
113 | //! The [`parse_quote!`] macro also uses this approach. | |
114 | //! | |
5869c6ff | 115 | //! [`parse_quote!`]: crate::parse_quote! |
e74abb32 XL |
116 | //! |
117 | //! # The `Parser` trait | |
118 | //! | |
119 | //! Some types can be parsed in several ways depending on context. For example | |
120 | //! an [`Attribute`] can be either "outer" like `#[...]` or "inner" like | |
121 | //! `#![...]` and parsing the wrong one would be a bug. Similarly [`Punctuated`] | |
122 | //! may or may not allow trailing punctuation, and parsing it the wrong way | |
123 | //! would either reject valid input or accept invalid input. | |
124 | //! | |
5869c6ff XL |
125 | //! [`Attribute`]: crate::Attribute |
126 | //! [`Punctuated`]: crate::punctuated | |
e74abb32 XL |
127 | //! |
128 | //! The `Parse` trait is not implemented in these cases because there is no good | |
129 | //! behavior to consider the default. | |
130 | //! | |
131 | //! ```compile_fail | |
132 | //! # extern crate proc_macro; | |
133 | //! # | |
134 | //! # use syn::punctuated::Punctuated; | |
135 | //! # use syn::{PathSegment, Result, Token}; | |
136 | //! # | |
137 | //! # fn f(tokens: proc_macro::TokenStream) -> Result<()> { | |
138 | //! # | |
139 | //! // Can't parse `Punctuated` without knowing whether trailing punctuation | |
140 | //! // should be allowed in this context. | |
141 | //! let path: Punctuated<PathSegment, Token![::]> = syn::parse(tokens)?; | |
142 | //! # | |
143 | //! # Ok(()) | |
144 | //! # } | |
145 | //! ``` | |
146 | //! | |
147 | //! In these cases the types provide a choice of parser functions rather than a | |
148 | //! single `Parse` implementation, and those parser functions can be invoked | |
149 | //! through the [`Parser`] trait. | |
150 | //! | |
e74abb32 XL |
151 | //! |
152 | //! ``` | |
f035d41b XL |
153 | //! # extern crate proc_macro; |
154 | //! # | |
e74abb32 XL |
155 | //! use proc_macro::TokenStream; |
156 | //! use syn::parse::Parser; | |
157 | //! use syn::punctuated::Punctuated; | |
158 | //! use syn::{Attribute, Expr, PathSegment, Result, Token}; | |
159 | //! | |
160 | //! fn call_some_parser_methods(input: TokenStream) -> Result<()> { | |
161 | //! // Parse a nonempty sequence of path segments separated by `::` punctuation | |
162 | //! // with no trailing punctuation. | |
163 | //! let tokens = input.clone(); | |
164 | //! let parser = Punctuated::<PathSegment, Token![::]>::parse_separated_nonempty; | |
165 | //! let _path = parser.parse(tokens)?; | |
166 | //! | |
167 | //! // Parse a possibly empty sequence of expressions terminated by commas with | |
168 | //! // an optional trailing punctuation. | |
169 | //! let tokens = input.clone(); | |
170 | //! let parser = Punctuated::<Expr, Token![,]>::parse_terminated; | |
171 | //! let _args = parser.parse(tokens)?; | |
172 | //! | |
173 | //! // Parse zero or more outer attributes but not inner attributes. | |
174 | //! let tokens = input.clone(); | |
175 | //! let parser = Attribute::parse_outer; | |
176 | //! let _attrs = parser.parse(tokens)?; | |
177 | //! | |
178 | //! Ok(()) | |
179 | //! } | |
180 | //! ``` | |
181 | //! | |
182 | //! --- | |
183 | //! | |
f035d41b | 184 | //! *This module is available only if Syn is built with the `"parsing"` feature.* |
e74abb32 XL |
185 | |
186 | #[path = "discouraged.rs"] | |
187 | pub mod discouraged; | |
188 | ||
29967ef6 XL |
189 | use crate::buffer::{Cursor, TokenBuffer}; |
190 | use crate::error; | |
191 | use crate::lookahead; | |
e74abb32 XL |
192 | #[cfg(all( |
193 | not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), | |
194 | feature = "proc-macro" | |
195 | ))] | |
196 | use crate::proc_macro; | |
e74abb32 XL |
197 | use crate::punctuated::Punctuated; |
198 | use crate::token::Token; | |
29967ef6 XL |
199 | use proc_macro2::{self, Delimiter, Group, Literal, Punct, Span, TokenStream, TokenTree}; |
200 | use std::cell::Cell; | |
201 | use std::fmt::{self, Debug, Display}; | |
5e7ed085 FG |
202 | #[cfg(feature = "extra-traits")] |
203 | use std::hash::{Hash, Hasher}; | |
29967ef6 XL |
204 | use std::marker::PhantomData; |
205 | use std::mem; | |
206 | use std::ops::Deref; | |
207 | use std::rc::Rc; | |
208 | use std::str::FromStr; | |
e74abb32 XL |
209 | |
210 | pub use crate::error::{Error, Result}; | |
211 | pub use crate::lookahead::{Lookahead1, Peek}; | |
212 | ||
213 | /// Parsing interface implemented by all types that can be parsed in a default | |
214 | /// way from a token stream. | |
f035d41b XL |
215 | /// |
216 | /// Refer to the [module documentation] for details about implementing and using | |
217 | /// the `Parse` trait. | |
218 | /// | |
219 | /// [module documentation]: self | |
e74abb32 XL |
220 | pub trait Parse: Sized { |
221 | fn parse(input: ParseStream) -> Result<Self>; | |
222 | } | |
223 | ||
224 | /// Input to a Syn parser function. | |
225 | /// | |
226 | /// See the methods of this type under the documentation of [`ParseBuffer`]. For | |
227 | /// an overview of parsing in Syn, refer to the [module documentation]. | |
228 | /// | |
229 | /// [module documentation]: self | |
230 | pub type ParseStream<'a> = &'a ParseBuffer<'a>; | |
231 | ||
232 | /// Cursor position within a buffered token stream. | |
233 | /// | |
234 | /// This type is more commonly used through the type alias [`ParseStream`] which | |
235 | /// is an alias for `&ParseBuffer`. | |
236 | /// | |
237 | /// `ParseStream` is the input type for all parser functions in Syn. They have | |
238 | /// the signature `fn(ParseStream) -> Result<T>`. | |
239 | /// | |
240 | /// ## Calling a parser function | |
241 | /// | |
242 | /// There is no public way to construct a `ParseBuffer`. Instead, if you are | |
243 | /// looking to invoke a parser function that requires `ParseStream` as input, | |
244 | /// you will need to go through one of the public parsing entry points. | |
245 | /// | |
246 | /// - The [`parse_macro_input!`] macro if parsing input of a procedural macro; | |
247 | /// - One of [the `syn::parse*` functions][syn-parse]; or | |
248 | /// - A method of the [`Parser`] trait. | |
249 | /// | |
923072b8 | 250 | /// [`parse_macro_input!`]: crate::parse_macro_input! |
5869c6ff | 251 | /// [syn-parse]: self#the-synparse-functions |
e74abb32 XL |
252 | pub struct ParseBuffer<'a> { |
253 | scope: Span, | |
254 | // Instead of Cell<Cursor<'a>> so that ParseBuffer<'a> is covariant in 'a. | |
255 | // The rest of the code in this module needs to be careful that only a | |
256 | // cursor derived from this `cell` is ever assigned to this `cell`. | |
257 | // | |
258 | // Cell<Cursor<'a>> cannot be covariant in 'a because then we could take a | |
259 | // ParseBuffer<'a>, upcast to ParseBuffer<'short> for some lifetime shorter | |
260 | // than 'a, and then assign a Cursor<'short> into the Cell. | |
261 | // | |
262 | // By extension, it would not be safe to expose an API that accepts a | |
263 | // Cursor<'a> and trusts that it lives as long as the cursor currently in | |
264 | // the cell. | |
265 | cell: Cell<Cursor<'static>>, | |
266 | marker: PhantomData<Cursor<'a>>, | |
60c5eb7d | 267 | unexpected: Cell<Option<Rc<Cell<Unexpected>>>>, |
e74abb32 XL |
268 | } |
269 | ||
270 | impl<'a> Drop for ParseBuffer<'a> { | |
271 | fn drop(&mut self) { | |
f035d41b | 272 | if let Some(unexpected_span) = span_of_unexpected_ignoring_nones(self.cursor()) { |
60c5eb7d XL |
273 | let (inner, old_span) = inner_unexpected(self); |
274 | if old_span.is_none() { | |
f035d41b | 275 | inner.set(Unexpected::Some(unexpected_span)); |
60c5eb7d | 276 | } |
e74abb32 XL |
277 | } |
278 | } | |
279 | } | |
280 | ||
281 | impl<'a> Display for ParseBuffer<'a> { | |
282 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
283 | Display::fmt(&self.cursor().token_stream(), f) | |
284 | } | |
285 | } | |
286 | ||
287 | impl<'a> Debug for ParseBuffer<'a> { | |
288 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
289 | Debug::fmt(&self.cursor().token_stream(), f) | |
290 | } | |
291 | } | |
292 | ||
293 | /// Cursor state associated with speculative parsing. | |
294 | /// | |
295 | /// This type is the input of the closure provided to [`ParseStream::step`]. | |
296 | /// | |
297 | /// [`ParseStream::step`]: ParseBuffer::step | |
298 | /// | |
299 | /// # Example | |
300 | /// | |
301 | /// ``` | |
302 | /// use proc_macro2::TokenTree; | |
303 | /// use syn::Result; | |
304 | /// use syn::parse::ParseStream; | |
305 | /// | |
306 | /// // This function advances the stream past the next occurrence of `@`. If | |
307 | /// // no `@` is present in the stream, the stream position is unchanged and | |
308 | /// // an error is returned. | |
309 | /// fn skip_past_next_at(input: ParseStream) -> Result<()> { | |
310 | /// input.step(|cursor| { | |
311 | /// let mut rest = *cursor; | |
312 | /// while let Some((tt, next)) = rest.token_tree() { | |
313 | /// match &tt { | |
314 | /// TokenTree::Punct(punct) if punct.as_char() == '@' => { | |
315 | /// return Ok(((), next)); | |
316 | /// } | |
317 | /// _ => rest = next, | |
318 | /// } | |
319 | /// } | |
320 | /// Err(cursor.error("no `@` was found after this point")) | |
321 | /// }) | |
322 | /// } | |
323 | /// # | |
324 | /// # fn remainder_after_skipping_past_next_at( | |
325 | /// # input: ParseStream, | |
326 | /// # ) -> Result<proc_macro2::TokenStream> { | |
327 | /// # skip_past_next_at(input)?; | |
328 | /// # input.parse() | |
329 | /// # } | |
330 | /// # | |
60c5eb7d XL |
331 | /// # use syn::parse::Parser; |
332 | /// # let remainder = remainder_after_skipping_past_next_at | |
333 | /// # .parse_str("a @ b c") | |
334 | /// # .unwrap(); | |
335 | /// # assert_eq!(remainder.to_string(), "b c"); | |
e74abb32 | 336 | /// ``` |
e74abb32 XL |
337 | pub struct StepCursor<'c, 'a> { |
338 | scope: Span, | |
339 | // This field is covariant in 'c. | |
340 | cursor: Cursor<'c>, | |
341 | // This field is contravariant in 'c. Together these make StepCursor | |
342 | // invariant in 'c. Also covariant in 'a. The user cannot cast 'c to a | |
343 | // different lifetime but can upcast into a StepCursor with a shorter | |
344 | // lifetime 'a. | |
345 | // | |
346 | // As long as we only ever construct a StepCursor for which 'c outlives 'a, | |
347 | // this means if ever a StepCursor<'c, 'a> exists we are guaranteed that 'c | |
348 | // outlives 'a. | |
349 | marker: PhantomData<fn(Cursor<'c>) -> Cursor<'a>>, | |
350 | } | |
351 | ||
352 | impl<'c, 'a> Deref for StepCursor<'c, 'a> { | |
353 | type Target = Cursor<'c>; | |
354 | ||
355 | fn deref(&self) -> &Self::Target { | |
356 | &self.cursor | |
357 | } | |
358 | } | |
359 | ||
1b1a35ee XL |
360 | impl<'c, 'a> Copy for StepCursor<'c, 'a> {} |
361 | ||
362 | impl<'c, 'a> Clone for StepCursor<'c, 'a> { | |
363 | fn clone(&self) -> Self { | |
364 | *self | |
365 | } | |
366 | } | |
367 | ||
e74abb32 XL |
368 | impl<'c, 'a> StepCursor<'c, 'a> { |
369 | /// Triggers an error at the current position of the parse stream. | |
370 | /// | |
371 | /// The `ParseStream::step` invocation will return this same error without | |
372 | /// advancing the stream state. | |
373 | pub fn error<T: Display>(self, message: T) -> Error { | |
374 | error::new_at(self.scope, self.cursor, message) | |
375 | } | |
376 | } | |
377 | ||
378 | pub(crate) fn advance_step_cursor<'c, 'a>(proof: StepCursor<'c, 'a>, to: Cursor<'c>) -> Cursor<'a> { | |
379 | // Refer to the comments within the StepCursor definition. We use the | |
380 | // fact that a StepCursor<'c, 'a> exists as proof that 'c outlives 'a. | |
381 | // Cursor is covariant in its lifetime parameter so we can cast a | |
382 | // Cursor<'c> to one with the shorter lifetime Cursor<'a>. | |
383 | let _ = proof; | |
384 | unsafe { mem::transmute::<Cursor<'c>, Cursor<'a>>(to) } | |
385 | } | |
386 | ||
e74abb32 XL |
387 | pub(crate) fn new_parse_buffer( |
388 | scope: Span, | |
389 | cursor: Cursor, | |
60c5eb7d | 390 | unexpected: Rc<Cell<Unexpected>>, |
e74abb32 XL |
391 | ) -> ParseBuffer { |
392 | ParseBuffer { | |
393 | scope, | |
394 | // See comment on `cell` in the struct definition. | |
395 | cell: Cell::new(unsafe { mem::transmute::<Cursor, Cursor<'static>>(cursor) }), | |
396 | marker: PhantomData, | |
60c5eb7d XL |
397 | unexpected: Cell::new(Some(unexpected)), |
398 | } | |
399 | } | |
400 | ||
60c5eb7d XL |
401 | pub(crate) enum Unexpected { |
402 | None, | |
403 | Some(Span), | |
404 | Chain(Rc<Cell<Unexpected>>), | |
405 | } | |
406 | ||
407 | impl Default for Unexpected { | |
408 | fn default() -> Self { | |
409 | Unexpected::None | |
e74abb32 XL |
410 | } |
411 | } | |
412 | ||
1b1a35ee XL |
413 | impl Clone for Unexpected { |
414 | fn clone(&self) -> Self { | |
415 | match self { | |
416 | Unexpected::None => Unexpected::None, | |
417 | Unexpected::Some(span) => Unexpected::Some(*span), | |
418 | Unexpected::Chain(next) => Unexpected::Chain(next.clone()), | |
419 | } | |
420 | } | |
421 | } | |
422 | ||
60c5eb7d XL |
423 | // We call this on Cell<Unexpected> and Cell<Option<T>> where temporarily |
424 | // swapping in a None is cheap. | |
425 | fn cell_clone<T: Default + Clone>(cell: &Cell<T>) -> T { | |
426 | let prev = cell.take(); | |
427 | let ret = prev.clone(); | |
428 | cell.set(prev); | |
429 | ret | |
430 | } | |
431 | ||
432 | fn inner_unexpected(buffer: &ParseBuffer) -> (Rc<Cell<Unexpected>>, Option<Span>) { | |
433 | let mut unexpected = get_unexpected(buffer); | |
434 | loop { | |
435 | match cell_clone(&unexpected) { | |
436 | Unexpected::None => return (unexpected, None), | |
437 | Unexpected::Some(span) => return (unexpected, Some(span)), | |
438 | Unexpected::Chain(next) => unexpected = next, | |
439 | } | |
440 | } | |
441 | } | |
442 | ||
443 | pub(crate) fn get_unexpected(buffer: &ParseBuffer) -> Rc<Cell<Unexpected>> { | |
444 | cell_clone(&buffer.unexpected).unwrap() | |
e74abb32 XL |
445 | } |
446 | ||
f035d41b XL |
447 | fn span_of_unexpected_ignoring_nones(mut cursor: Cursor) -> Option<Span> { |
448 | if cursor.eof() { | |
449 | return None; | |
450 | } | |
451 | while let Some((inner, _span, rest)) = cursor.group(Delimiter::None) { | |
452 | if let Some(unexpected) = span_of_unexpected_ignoring_nones(inner) { | |
453 | return Some(unexpected); | |
454 | } | |
455 | cursor = rest; | |
456 | } | |
457 | if cursor.eof() { | |
458 | None | |
459 | } else { | |
460 | Some(cursor.span()) | |
461 | } | |
462 | } | |
463 | ||
e74abb32 XL |
464 | impl<'a> ParseBuffer<'a> { |
465 | /// Parses a syntax tree node of type `T`, advancing the position of our | |
466 | /// parse stream past it. | |
467 | pub fn parse<T: Parse>(&self) -> Result<T> { | |
468 | T::parse(self) | |
469 | } | |
470 | ||
471 | /// Calls the given parser function to parse a syntax tree node of type `T` | |
472 | /// from this stream. | |
473 | /// | |
474 | /// # Example | |
475 | /// | |
476 | /// The parser below invokes [`Attribute::parse_outer`] to parse a vector of | |
477 | /// zero or more outer attributes. | |
478 | /// | |
479 | /// [`Attribute::parse_outer`]: crate::Attribute::parse_outer | |
480 | /// | |
481 | /// ``` | |
482 | /// use syn::{Attribute, Ident, Result, Token}; | |
483 | /// use syn::parse::{Parse, ParseStream}; | |
484 | /// | |
485 | /// // Parses a unit struct with attributes. | |
486 | /// // | |
487 | /// // #[path = "s.tmpl"] | |
488 | /// // struct S; | |
489 | /// struct UnitStruct { | |
490 | /// attrs: Vec<Attribute>, | |
491 | /// struct_token: Token![struct], | |
492 | /// name: Ident, | |
493 | /// semi_token: Token![;], | |
494 | /// } | |
495 | /// | |
496 | /// impl Parse for UnitStruct { | |
497 | /// fn parse(input: ParseStream) -> Result<Self> { | |
498 | /// Ok(UnitStruct { | |
499 | /// attrs: input.call(Attribute::parse_outer)?, | |
500 | /// struct_token: input.parse()?, | |
501 | /// name: input.parse()?, | |
502 | /// semi_token: input.parse()?, | |
503 | /// }) | |
504 | /// } | |
505 | /// } | |
506 | /// ``` | |
507 | pub fn call<T>(&self, function: fn(ParseStream) -> Result<T>) -> Result<T> { | |
508 | function(self) | |
509 | } | |
510 | ||
511 | /// Looks at the next token in the parse stream to determine whether it | |
512 | /// matches the requested type of token. | |
513 | /// | |
514 | /// Does not advance the position of the parse stream. | |
515 | /// | |
516 | /// # Syntax | |
517 | /// | |
518 | /// Note that this method does not use turbofish syntax. Pass the peek type | |
519 | /// inside of parentheses. | |
520 | /// | |
521 | /// - `input.peek(Token![struct])` | |
522 | /// - `input.peek(Token![==])` | |
523 | /// - `input.peek(Ident)` *(does not accept keywords)* | |
524 | /// - `input.peek(Ident::peek_any)` | |
525 | /// - `input.peek(Lifetime)` | |
526 | /// - `input.peek(token::Brace)` | |
527 | /// | |
528 | /// # Example | |
529 | /// | |
530 | /// In this example we finish parsing the list of supertraits when the next | |
531 | /// token in the input is either `where` or an opening curly brace. | |
532 | /// | |
533 | /// ``` | |
534 | /// use syn::{braced, token, Generics, Ident, Result, Token, TypeParamBound}; | |
535 | /// use syn::parse::{Parse, ParseStream}; | |
536 | /// use syn::punctuated::Punctuated; | |
537 | /// | |
538 | /// // Parses a trait definition containing no associated items. | |
539 | /// // | |
540 | /// // trait Marker<'de, T>: A + B<'de> where Box<T>: Clone {} | |
541 | /// struct MarkerTrait { | |
542 | /// trait_token: Token![trait], | |
543 | /// ident: Ident, | |
544 | /// generics: Generics, | |
545 | /// colon_token: Option<Token![:]>, | |
546 | /// supertraits: Punctuated<TypeParamBound, Token![+]>, | |
547 | /// brace_token: token::Brace, | |
548 | /// } | |
549 | /// | |
550 | /// impl Parse for MarkerTrait { | |
551 | /// fn parse(input: ParseStream) -> Result<Self> { | |
552 | /// let trait_token: Token![trait] = input.parse()?; | |
553 | /// let ident: Ident = input.parse()?; | |
554 | /// let mut generics: Generics = input.parse()?; | |
555 | /// let colon_token: Option<Token![:]> = input.parse()?; | |
556 | /// | |
557 | /// let mut supertraits = Punctuated::new(); | |
558 | /// if colon_token.is_some() { | |
559 | /// loop { | |
560 | /// supertraits.push_value(input.parse()?); | |
561 | /// if input.peek(Token![where]) || input.peek(token::Brace) { | |
562 | /// break; | |
563 | /// } | |
564 | /// supertraits.push_punct(input.parse()?); | |
565 | /// } | |
566 | /// } | |
567 | /// | |
568 | /// generics.where_clause = input.parse()?; | |
569 | /// let content; | |
570 | /// let empty_brace_token = braced!(content in input); | |
571 | /// | |
572 | /// Ok(MarkerTrait { | |
573 | /// trait_token, | |
574 | /// ident, | |
575 | /// generics, | |
576 | /// colon_token, | |
577 | /// supertraits, | |
578 | /// brace_token: empty_brace_token, | |
579 | /// }) | |
580 | /// } | |
581 | /// } | |
582 | /// ``` | |
583 | pub fn peek<T: Peek>(&self, token: T) -> bool { | |
584 | let _ = token; | |
585 | T::Token::peek(self.cursor()) | |
586 | } | |
587 | ||
588 | /// Looks at the second-next token in the parse stream. | |
589 | /// | |
590 | /// This is commonly useful as a way to implement contextual keywords. | |
591 | /// | |
592 | /// # Example | |
593 | /// | |
594 | /// This example needs to use `peek2` because the symbol `union` is not a | |
595 | /// keyword in Rust. We can't use just `peek` and decide to parse a union if | |
596 | /// the very next token is `union`, because someone is free to write a `mod | |
597 | /// union` and a macro invocation that looks like `union::some_macro! { ... | |
598 | /// }`. In other words `union` is a contextual keyword. | |
599 | /// | |
600 | /// ``` | |
601 | /// use syn::{Ident, ItemUnion, Macro, Result, Token}; | |
602 | /// use syn::parse::{Parse, ParseStream}; | |
603 | /// | |
604 | /// // Parses either a union or a macro invocation. | |
605 | /// enum UnionOrMacro { | |
606 | /// // union MaybeUninit<T> { uninit: (), value: T } | |
607 | /// Union(ItemUnion), | |
608 | /// // lazy_static! { ... } | |
609 | /// Macro(Macro), | |
610 | /// } | |
611 | /// | |
612 | /// impl Parse for UnionOrMacro { | |
613 | /// fn parse(input: ParseStream) -> Result<Self> { | |
614 | /// if input.peek(Token![union]) && input.peek2(Ident) { | |
615 | /// input.parse().map(UnionOrMacro::Union) | |
616 | /// } else { | |
617 | /// input.parse().map(UnionOrMacro::Macro) | |
618 | /// } | |
619 | /// } | |
620 | /// } | |
621 | /// ``` | |
622 | pub fn peek2<T: Peek>(&self, token: T) -> bool { | |
5869c6ff XL |
623 | fn peek2(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { |
624 | if let Some(group) = buffer.cursor().group(Delimiter::None) { | |
625 | if group.0.skip().map_or(false, peek) { | |
626 | return true; | |
627 | } | |
628 | } | |
629 | buffer.cursor().skip().map_or(false, peek) | |
630 | } | |
631 | ||
f035d41b | 632 | let _ = token; |
5869c6ff | 633 | peek2(self, T::Token::peek) |
e74abb32 XL |
634 | } |
635 | ||
636 | /// Looks at the third-next token in the parse stream. | |
637 | pub fn peek3<T: Peek>(&self, token: T) -> bool { | |
5869c6ff XL |
638 | fn peek3(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { |
639 | if let Some(group) = buffer.cursor().group(Delimiter::None) { | |
640 | if group.0.skip().and_then(Cursor::skip).map_or(false, peek) { | |
641 | return true; | |
642 | } | |
643 | } | |
644 | buffer | |
645 | .cursor() | |
646 | .skip() | |
647 | .and_then(Cursor::skip) | |
648 | .map_or(false, peek) | |
649 | } | |
650 | ||
f035d41b | 651 | let _ = token; |
5869c6ff | 652 | peek3(self, T::Token::peek) |
e74abb32 XL |
653 | } |
654 | ||
655 | /// Parses zero or more occurrences of `T` separated by punctuation of type | |
656 | /// `P`, with optional trailing punctuation. | |
657 | /// | |
658 | /// Parsing continues until the end of this parse stream. The entire content | |
659 | /// of this parse stream must consist of `T` and `P`. | |
660 | /// | |
661 | /// # Example | |
662 | /// | |
663 | /// ``` | |
664 | /// # use quote::quote; | |
665 | /// # | |
666 | /// use syn::{parenthesized, token, Ident, Result, Token, Type}; | |
667 | /// use syn::parse::{Parse, ParseStream}; | |
668 | /// use syn::punctuated::Punctuated; | |
669 | /// | |
670 | /// // Parse a simplified tuple struct syntax like: | |
671 | /// // | |
672 | /// // struct S(A, B); | |
673 | /// struct TupleStruct { | |
674 | /// struct_token: Token![struct], | |
675 | /// ident: Ident, | |
676 | /// paren_token: token::Paren, | |
677 | /// fields: Punctuated<Type, Token![,]>, | |
678 | /// semi_token: Token![;], | |
679 | /// } | |
680 | /// | |
681 | /// impl Parse for TupleStruct { | |
682 | /// fn parse(input: ParseStream) -> Result<Self> { | |
683 | /// let content; | |
684 | /// Ok(TupleStruct { | |
685 | /// struct_token: input.parse()?, | |
686 | /// ident: input.parse()?, | |
687 | /// paren_token: parenthesized!(content in input), | |
688 | /// fields: content.parse_terminated(Type::parse)?, | |
689 | /// semi_token: input.parse()?, | |
690 | /// }) | |
691 | /// } | |
692 | /// } | |
693 | /// # | |
60c5eb7d XL |
694 | /// # let input = quote! { |
695 | /// # struct S(A, B); | |
696 | /// # }; | |
697 | /// # syn::parse2::<TupleStruct>(input).unwrap(); | |
e74abb32 XL |
698 | /// ``` |
699 | pub fn parse_terminated<T, P: Parse>( | |
700 | &self, | |
701 | parser: fn(ParseStream) -> Result<T>, | |
702 | ) -> Result<Punctuated<T, P>> { | |
703 | Punctuated::parse_terminated_with(self, parser) | |
704 | } | |
705 | ||
706 | /// Returns whether there are tokens remaining in this stream. | |
707 | /// | |
708 | /// This method returns true at the end of the content of a set of | |
709 | /// delimiters, as well as at the very end of the complete macro input. | |
710 | /// | |
711 | /// # Example | |
712 | /// | |
713 | /// ``` | |
714 | /// use syn::{braced, token, Ident, Item, Result, Token}; | |
715 | /// use syn::parse::{Parse, ParseStream}; | |
716 | /// | |
717 | /// // Parses a Rust `mod m { ... }` containing zero or more items. | |
718 | /// struct Mod { | |
719 | /// mod_token: Token![mod], | |
720 | /// name: Ident, | |
721 | /// brace_token: token::Brace, | |
722 | /// items: Vec<Item>, | |
723 | /// } | |
724 | /// | |
725 | /// impl Parse for Mod { | |
726 | /// fn parse(input: ParseStream) -> Result<Self> { | |
727 | /// let content; | |
728 | /// Ok(Mod { | |
729 | /// mod_token: input.parse()?, | |
730 | /// name: input.parse()?, | |
731 | /// brace_token: braced!(content in input), | |
732 | /// items: { | |
733 | /// let mut items = Vec::new(); | |
734 | /// while !content.is_empty() { | |
735 | /// items.push(content.parse()?); | |
736 | /// } | |
737 | /// items | |
738 | /// }, | |
739 | /// }) | |
740 | /// } | |
741 | /// } | |
742 | /// ``` | |
743 | pub fn is_empty(&self) -> bool { | |
744 | self.cursor().eof() | |
745 | } | |
746 | ||
747 | /// Constructs a helper for peeking at the next token in this stream and | |
748 | /// building an error message if it is not one of a set of expected tokens. | |
749 | /// | |
750 | /// # Example | |
751 | /// | |
752 | /// ``` | |
753 | /// use syn::{ConstParam, Ident, Lifetime, LifetimeDef, Result, Token, TypeParam}; | |
754 | /// use syn::parse::{Parse, ParseStream}; | |
755 | /// | |
756 | /// // A generic parameter, a single one of the comma-separated elements inside | |
757 | /// // angle brackets in: | |
758 | /// // | |
759 | /// // fn f<T: Clone, 'a, 'b: 'a, const N: usize>() { ... } | |
760 | /// // | |
761 | /// // On invalid input, lookahead gives us a reasonable error message. | |
762 | /// // | |
763 | /// // error: expected one of: identifier, lifetime, `const` | |
764 | /// // | | |
765 | /// // 5 | fn f<!Sized>() {} | |
766 | /// // | ^ | |
767 | /// enum GenericParam { | |
768 | /// Type(TypeParam), | |
769 | /// Lifetime(LifetimeDef), | |
770 | /// Const(ConstParam), | |
771 | /// } | |
772 | /// | |
773 | /// impl Parse for GenericParam { | |
774 | /// fn parse(input: ParseStream) -> Result<Self> { | |
775 | /// let lookahead = input.lookahead1(); | |
776 | /// if lookahead.peek(Ident) { | |
777 | /// input.parse().map(GenericParam::Type) | |
778 | /// } else if lookahead.peek(Lifetime) { | |
779 | /// input.parse().map(GenericParam::Lifetime) | |
780 | /// } else if lookahead.peek(Token![const]) { | |
781 | /// input.parse().map(GenericParam::Const) | |
782 | /// } else { | |
783 | /// Err(lookahead.error()) | |
784 | /// } | |
785 | /// } | |
786 | /// } | |
787 | /// ``` | |
788 | pub fn lookahead1(&self) -> Lookahead1<'a> { | |
789 | lookahead::new(self.scope, self.cursor()) | |
790 | } | |
791 | ||
792 | /// Forks a parse stream so that parsing tokens out of either the original | |
793 | /// or the fork does not advance the position of the other. | |
794 | /// | |
795 | /// # Performance | |
796 | /// | |
797 | /// Forking a parse stream is a cheap fixed amount of work and does not | |
798 | /// involve copying token buffers. Where you might hit performance problems | |
799 | /// is if your macro ends up parsing a large amount of content more than | |
800 | /// once. | |
801 | /// | |
802 | /// ``` | |
803 | /// # use syn::{Expr, Result}; | |
804 | /// # use syn::parse::ParseStream; | |
805 | /// # | |
806 | /// # fn bad(input: ParseStream) -> Result<Expr> { | |
807 | /// // Do not do this. | |
808 | /// if input.fork().parse::<Expr>().is_ok() { | |
809 | /// return input.parse::<Expr>(); | |
810 | /// } | |
811 | /// # unimplemented!() | |
812 | /// # } | |
813 | /// ``` | |
814 | /// | |
815 | /// As a rule, avoid parsing an unbounded amount of tokens out of a forked | |
816 | /// parse stream. Only use a fork when the amount of work performed against | |
817 | /// the fork is small and bounded. | |
818 | /// | |
819 | /// When complex speculative parsing against the forked stream is | |
820 | /// unavoidable, use [`parse::discouraged::Speculative`] to advance the | |
821 | /// original stream once the fork's parse is determined to have been | |
822 | /// successful. | |
823 | /// | |
824 | /// For a lower level way to perform speculative parsing at the token level, | |
825 | /// consider using [`ParseStream::step`] instead. | |
826 | /// | |
827 | /// [`parse::discouraged::Speculative`]: discouraged::Speculative | |
828 | /// [`ParseStream::step`]: ParseBuffer::step | |
829 | /// | |
830 | /// # Example | |
831 | /// | |
832 | /// The parse implementation shown here parses possibly restricted `pub` | |
833 | /// visibilities. | |
834 | /// | |
835 | /// - `pub` | |
836 | /// - `pub(crate)` | |
837 | /// - `pub(self)` | |
838 | /// - `pub(super)` | |
839 | /// - `pub(in some::path)` | |
840 | /// | |
841 | /// To handle the case of visibilities inside of tuple structs, the parser | |
842 | /// needs to distinguish parentheses that specify visibility restrictions | |
843 | /// from parentheses that form part of a tuple type. | |
844 | /// | |
845 | /// ``` | |
846 | /// # struct A; | |
847 | /// # struct B; | |
848 | /// # struct C; | |
849 | /// # | |
850 | /// struct S(pub(crate) A, pub (B, C)); | |
851 | /// ``` | |
852 | /// | |
853 | /// In this example input the first tuple struct element of `S` has | |
854 | /// `pub(crate)` visibility while the second tuple struct element has `pub` | |
855 | /// visibility; the parentheses around `(B, C)` are part of the type rather | |
856 | /// than part of a visibility restriction. | |
857 | /// | |
858 | /// The parser uses a forked parse stream to check the first token inside of | |
859 | /// parentheses after the `pub` keyword. This is a small bounded amount of | |
860 | /// work performed against the forked parse stream. | |
861 | /// | |
862 | /// ``` | |
863 | /// use syn::{parenthesized, token, Ident, Path, Result, Token}; | |
864 | /// use syn::ext::IdentExt; | |
865 | /// use syn::parse::{Parse, ParseStream}; | |
866 | /// | |
867 | /// struct PubVisibility { | |
868 | /// pub_token: Token![pub], | |
869 | /// restricted: Option<Restricted>, | |
870 | /// } | |
871 | /// | |
872 | /// struct Restricted { | |
873 | /// paren_token: token::Paren, | |
874 | /// in_token: Option<Token![in]>, | |
875 | /// path: Path, | |
876 | /// } | |
877 | /// | |
878 | /// impl Parse for PubVisibility { | |
879 | /// fn parse(input: ParseStream) -> Result<Self> { | |
880 | /// let pub_token: Token![pub] = input.parse()?; | |
881 | /// | |
882 | /// if input.peek(token::Paren) { | |
883 | /// let ahead = input.fork(); | |
884 | /// let mut content; | |
885 | /// parenthesized!(content in ahead); | |
886 | /// | |
887 | /// if content.peek(Token![crate]) | |
888 | /// || content.peek(Token![self]) | |
889 | /// || content.peek(Token![super]) | |
890 | /// { | |
891 | /// return Ok(PubVisibility { | |
892 | /// pub_token, | |
893 | /// restricted: Some(Restricted { | |
894 | /// paren_token: parenthesized!(content in input), | |
895 | /// in_token: None, | |
896 | /// path: Path::from(content.call(Ident::parse_any)?), | |
897 | /// }), | |
898 | /// }); | |
899 | /// } else if content.peek(Token![in]) { | |
900 | /// return Ok(PubVisibility { | |
901 | /// pub_token, | |
902 | /// restricted: Some(Restricted { | |
903 | /// paren_token: parenthesized!(content in input), | |
904 | /// in_token: Some(content.parse()?), | |
905 | /// path: content.call(Path::parse_mod_style)?, | |
906 | /// }), | |
907 | /// }); | |
908 | /// } | |
909 | /// } | |
910 | /// | |
911 | /// Ok(PubVisibility { | |
912 | /// pub_token, | |
913 | /// restricted: None, | |
914 | /// }) | |
915 | /// } | |
916 | /// } | |
917 | /// ``` | |
918 | pub fn fork(&self) -> Self { | |
919 | ParseBuffer { | |
920 | scope: self.scope, | |
921 | cell: self.cell.clone(), | |
922 | marker: PhantomData, | |
923 | // Not the parent's unexpected. Nothing cares whether the clone | |
60c5eb7d XL |
924 | // parses all the way unless we `advance_to`. |
925 | unexpected: Cell::new(Some(Rc::new(Cell::new(Unexpected::None)))), | |
e74abb32 XL |
926 | } |
927 | } | |
928 | ||
929 | /// Triggers an error at the current position of the parse stream. | |
930 | /// | |
931 | /// # Example | |
932 | /// | |
933 | /// ``` | |
934 | /// use syn::{Expr, Result, Token}; | |
935 | /// use syn::parse::{Parse, ParseStream}; | |
936 | /// | |
937 | /// // Some kind of loop: `while` or `for` or `loop`. | |
938 | /// struct Loop { | |
939 | /// expr: Expr, | |
940 | /// } | |
941 | /// | |
942 | /// impl Parse for Loop { | |
943 | /// fn parse(input: ParseStream) -> Result<Self> { | |
944 | /// if input.peek(Token![while]) | |
945 | /// || input.peek(Token![for]) | |
946 | /// || input.peek(Token![loop]) | |
947 | /// { | |
948 | /// Ok(Loop { | |
949 | /// expr: input.parse()?, | |
950 | /// }) | |
951 | /// } else { | |
952 | /// Err(input.error("expected some kind of loop")) | |
953 | /// } | |
954 | /// } | |
955 | /// } | |
956 | /// ``` | |
957 | pub fn error<T: Display>(&self, message: T) -> Error { | |
958 | error::new_at(self.scope, self.cursor(), message) | |
959 | } | |
960 | ||
961 | /// Speculatively parses tokens from this parse stream, advancing the | |
962 | /// position of this stream only if parsing succeeds. | |
963 | /// | |
964 | /// This is a powerful low-level API used for defining the `Parse` impls of | |
965 | /// the basic built-in token types. It is not something that will be used | |
966 | /// widely outside of the Syn codebase. | |
967 | /// | |
968 | /// # Example | |
969 | /// | |
970 | /// ``` | |
971 | /// use proc_macro2::TokenTree; | |
972 | /// use syn::Result; | |
973 | /// use syn::parse::ParseStream; | |
974 | /// | |
975 | /// // This function advances the stream past the next occurrence of `@`. If | |
976 | /// // no `@` is present in the stream, the stream position is unchanged and | |
977 | /// // an error is returned. | |
978 | /// fn skip_past_next_at(input: ParseStream) -> Result<()> { | |
979 | /// input.step(|cursor| { | |
980 | /// let mut rest = *cursor; | |
981 | /// while let Some((tt, next)) = rest.token_tree() { | |
982 | /// match &tt { | |
983 | /// TokenTree::Punct(punct) if punct.as_char() == '@' => { | |
984 | /// return Ok(((), next)); | |
985 | /// } | |
986 | /// _ => rest = next, | |
987 | /// } | |
988 | /// } | |
989 | /// Err(cursor.error("no `@` was found after this point")) | |
990 | /// }) | |
991 | /// } | |
992 | /// # | |
993 | /// # fn remainder_after_skipping_past_next_at( | |
994 | /// # input: ParseStream, | |
995 | /// # ) -> Result<proc_macro2::TokenStream> { | |
996 | /// # skip_past_next_at(input)?; | |
997 | /// # input.parse() | |
998 | /// # } | |
999 | /// # | |
60c5eb7d XL |
1000 | /// # use syn::parse::Parser; |
1001 | /// # let remainder = remainder_after_skipping_past_next_at | |
1002 | /// # .parse_str("a @ b c") | |
1003 | /// # .unwrap(); | |
1004 | /// # assert_eq!(remainder.to_string(), "b c"); | |
e74abb32 XL |
1005 | /// ``` |
1006 | pub fn step<F, R>(&self, function: F) -> Result<R> | |
1007 | where | |
1008 | F: for<'c> FnOnce(StepCursor<'c, 'a>) -> Result<(R, Cursor<'c>)>, | |
1009 | { | |
1010 | // Since the user's function is required to work for any 'c, we know | |
1011 | // that the Cursor<'c> they return is either derived from the input | |
1012 | // StepCursor<'c, 'a> or from a Cursor<'static>. | |
1013 | // | |
1014 | // It would not be legal to write this function without the invariant | |
1015 | // lifetime 'c in StepCursor<'c, 'a>. If this function were written only | |
1016 | // in terms of 'a, the user could take our ParseBuffer<'a>, upcast it to | |
1017 | // a ParseBuffer<'short> which some shorter lifetime than 'a, invoke | |
1018 | // `step` on their ParseBuffer<'short> with a closure that returns | |
1019 | // Cursor<'short>, and we would wrongly write that Cursor<'short> into | |
1020 | // the Cell intended to hold Cursor<'a>. | |
1021 | // | |
1022 | // In some cases it may be necessary for R to contain a Cursor<'a>. | |
1023 | // Within Syn we solve this using `advance_step_cursor` which uses the | |
1024 | // existence of a StepCursor<'c, 'a> as proof that it is safe to cast | |
1025 | // from Cursor<'c> to Cursor<'a>. If needed outside of Syn, it would be | |
1026 | // safe to expose that API as a method on StepCursor. | |
1027 | let (node, rest) = function(StepCursor { | |
1028 | scope: self.scope, | |
1029 | cursor: self.cell.get(), | |
1030 | marker: PhantomData, | |
1031 | })?; | |
1032 | self.cell.set(rest); | |
1033 | Ok(node) | |
1034 | } | |
1035 | ||
f035d41b XL |
1036 | /// Returns the `Span` of the next token in the parse stream, or |
1037 | /// `Span::call_site()` if this parse stream has completely exhausted its | |
1038 | /// input `TokenStream`. | |
1039 | pub fn span(&self) -> Span { | |
1040 | let cursor = self.cursor(); | |
1041 | if cursor.eof() { | |
1042 | self.scope | |
1043 | } else { | |
1044 | crate::buffer::open_span_of_group(cursor) | |
1045 | } | |
1046 | } | |
1047 | ||
e74abb32 XL |
1048 | /// Provides low-level access to the token representation underlying this |
1049 | /// parse stream. | |
1050 | /// | |
1051 | /// Cursors are immutable so no operations you perform against the cursor | |
1052 | /// will affect the state of this parse stream. | |
1053 | pub fn cursor(&self) -> Cursor<'a> { | |
1054 | self.cell.get() | |
1055 | } | |
1056 | ||
1057 | fn check_unexpected(&self) -> Result<()> { | |
60c5eb7d | 1058 | match inner_unexpected(self).1 { |
e74abb32 XL |
1059 | Some(span) => Err(Error::new(span, "unexpected token")), |
1060 | None => Ok(()), | |
1061 | } | |
1062 | } | |
1063 | } | |
1064 | ||
5869c6ff | 1065 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1066 | impl<T: Parse> Parse for Box<T> { |
1067 | fn parse(input: ParseStream) -> Result<Self> { | |
1068 | input.parse().map(Box::new) | |
1069 | } | |
1070 | } | |
1071 | ||
5869c6ff | 1072 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1073 | impl<T: Parse + Token> Parse for Option<T> { |
1074 | fn parse(input: ParseStream) -> Result<Self> { | |
1075 | if T::peek(input.cursor()) { | |
1076 | Ok(Some(input.parse()?)) | |
1077 | } else { | |
1078 | Ok(None) | |
1079 | } | |
1080 | } | |
1081 | } | |
1082 | ||
5869c6ff | 1083 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1084 | impl Parse for TokenStream { |
1085 | fn parse(input: ParseStream) -> Result<Self> { | |
1086 | input.step(|cursor| Ok((cursor.token_stream(), Cursor::empty()))) | |
1087 | } | |
1088 | } | |
1089 | ||
5869c6ff | 1090 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1091 | impl Parse for TokenTree { |
1092 | fn parse(input: ParseStream) -> Result<Self> { | |
1093 | input.step(|cursor| match cursor.token_tree() { | |
1094 | Some((tt, rest)) => Ok((tt, rest)), | |
1095 | None => Err(cursor.error("expected token tree")), | |
1096 | }) | |
1097 | } | |
1098 | } | |
1099 | ||
5869c6ff | 1100 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1101 | impl Parse for Group { |
1102 | fn parse(input: ParseStream) -> Result<Self> { | |
1103 | input.step(|cursor| { | |
1104 | for delim in &[Delimiter::Parenthesis, Delimiter::Brace, Delimiter::Bracket] { | |
1105 | if let Some((inside, span, rest)) = cursor.group(*delim) { | |
1106 | let mut group = Group::new(*delim, inside.token_stream()); | |
1107 | group.set_span(span); | |
1108 | return Ok((group, rest)); | |
1109 | } | |
1110 | } | |
1111 | Err(cursor.error("expected group token")) | |
1112 | }) | |
1113 | } | |
1114 | } | |
1115 | ||
5869c6ff | 1116 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1117 | impl Parse for Punct { |
1118 | fn parse(input: ParseStream) -> Result<Self> { | |
1119 | input.step(|cursor| match cursor.punct() { | |
1120 | Some((punct, rest)) => Ok((punct, rest)), | |
1121 | None => Err(cursor.error("expected punctuation token")), | |
1122 | }) | |
1123 | } | |
1124 | } | |
1125 | ||
5869c6ff | 1126 | #[cfg_attr(doc_cfg, doc(cfg(feature = "parsing")))] |
e74abb32 XL |
1127 | impl Parse for Literal { |
1128 | fn parse(input: ParseStream) -> Result<Self> { | |
1129 | input.step(|cursor| match cursor.literal() { | |
1130 | Some((literal, rest)) => Ok((literal, rest)), | |
1131 | None => Err(cursor.error("expected literal token")), | |
1132 | }) | |
1133 | } | |
1134 | } | |
1135 | ||
1136 | /// Parser that can parse Rust tokens into a particular syntax tree node. | |
1137 | /// | |
1138 | /// Refer to the [module documentation] for details about parsing in Syn. | |
1139 | /// | |
1140 | /// [module documentation]: self | |
1141 | /// | |
f035d41b | 1142 | /// *This trait is available only if Syn is built with the `"parsing"` feature.* |
e74abb32 XL |
1143 | pub trait Parser: Sized { |
1144 | type Output; | |
1145 | ||
1146 | /// Parse a proc-macro2 token stream into the chosen syntax tree node. | |
1147 | /// | |
1148 | /// This function will check that the input is fully parsed. If there are | |
1149 | /// any unparsed tokens at the end of the stream, an error is returned. | |
1150 | fn parse2(self, tokens: TokenStream) -> Result<Self::Output>; | |
1151 | ||
1152 | /// Parse tokens of source code into the chosen syntax tree node. | |
1153 | /// | |
1154 | /// This function will check that the input is fully parsed. If there are | |
1155 | /// any unparsed tokens at the end of the stream, an error is returned. | |
1156 | /// | |
f035d41b | 1157 | /// *This method is available only if Syn is built with both the `"parsing"` and |
e74abb32 XL |
1158 | /// `"proc-macro"` features.* |
1159 | #[cfg(all( | |
1160 | not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), | |
1161 | feature = "proc-macro" | |
1162 | ))] | |
1163 | fn parse(self, tokens: proc_macro::TokenStream) -> Result<Self::Output> { | |
1164 | self.parse2(proc_macro2::TokenStream::from(tokens)) | |
1165 | } | |
1166 | ||
1167 | /// Parse a string of Rust code into the chosen syntax tree node. | |
1168 | /// | |
1169 | /// This function will check that the input is fully parsed. If there are | |
1170 | /// any unparsed tokens at the end of the string, an error is returned. | |
1171 | /// | |
1172 | /// # Hygiene | |
1173 | /// | |
1174 | /// Every span in the resulting syntax tree will be set to resolve at the | |
1175 | /// macro call site. | |
1176 | fn parse_str(self, s: &str) -> Result<Self::Output> { | |
1177 | self.parse2(proc_macro2::TokenStream::from_str(s)?) | |
1178 | } | |
1179 | ||
1180 | // Not public API. | |
1181 | #[doc(hidden)] | |
f035d41b | 1182 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1183 | fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { |
1184 | let _ = scope; | |
1185 | self.parse2(tokens) | |
1186 | } | |
1187 | ||
1188 | // Not public API. | |
1189 | #[doc(hidden)] | |
f035d41b | 1190 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1191 | fn __parse_stream(self, input: ParseStream) -> Result<Self::Output> { |
1192 | input.parse().and_then(|tokens| self.parse2(tokens)) | |
1193 | } | |
1194 | } | |
1195 | ||
1196 | fn tokens_to_parse_buffer(tokens: &TokenBuffer) -> ParseBuffer { | |
1197 | let scope = Span::call_site(); | |
1198 | let cursor = tokens.begin(); | |
60c5eb7d | 1199 | let unexpected = Rc::new(Cell::new(Unexpected::None)); |
e74abb32 XL |
1200 | new_parse_buffer(scope, cursor, unexpected) |
1201 | } | |
1202 | ||
1203 | impl<F, T> Parser for F | |
1204 | where | |
1205 | F: FnOnce(ParseStream) -> Result<T>, | |
1206 | { | |
1207 | type Output = T; | |
1208 | ||
1209 | fn parse2(self, tokens: TokenStream) -> Result<T> { | |
1210 | let buf = TokenBuffer::new2(tokens); | |
1211 | let state = tokens_to_parse_buffer(&buf); | |
1212 | let node = self(&state)?; | |
1213 | state.check_unexpected()?; | |
f035d41b XL |
1214 | if let Some(unexpected_span) = span_of_unexpected_ignoring_nones(state.cursor()) { |
1215 | Err(Error::new(unexpected_span, "unexpected token")) | |
e74abb32 | 1216 | } else { |
f035d41b | 1217 | Ok(node) |
e74abb32 XL |
1218 | } |
1219 | } | |
1220 | ||
f035d41b | 1221 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1222 | fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { |
1223 | let buf = TokenBuffer::new2(tokens); | |
1224 | let cursor = buf.begin(); | |
60c5eb7d | 1225 | let unexpected = Rc::new(Cell::new(Unexpected::None)); |
e74abb32 XL |
1226 | let state = new_parse_buffer(scope, cursor, unexpected); |
1227 | let node = self(&state)?; | |
1228 | state.check_unexpected()?; | |
f035d41b XL |
1229 | if let Some(unexpected_span) = span_of_unexpected_ignoring_nones(state.cursor()) { |
1230 | Err(Error::new(unexpected_span, "unexpected token")) | |
e74abb32 | 1231 | } else { |
f035d41b | 1232 | Ok(node) |
e74abb32 XL |
1233 | } |
1234 | } | |
1235 | ||
f035d41b | 1236 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1237 | fn __parse_stream(self, input: ParseStream) -> Result<Self::Output> { |
1238 | self(input) | |
1239 | } | |
1240 | } | |
1241 | ||
f035d41b | 1242 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1243 | pub(crate) fn parse_scoped<F: Parser>(f: F, scope: Span, tokens: TokenStream) -> Result<F::Output> { |
1244 | f.__parse_scoped(scope, tokens) | |
1245 | } | |
1246 | ||
f035d41b | 1247 | #[cfg(any(feature = "full", feature = "derive"))] |
e74abb32 XL |
1248 | pub(crate) fn parse_stream<F: Parser>(f: F, input: ParseStream) -> Result<F::Output> { |
1249 | f.__parse_stream(input) | |
1250 | } | |
1251 | ||
1252 | /// An empty syntax tree node that consumes no tokens when parsed. | |
1253 | /// | |
1254 | /// This is useful for attribute macros that want to ensure they are not | |
1255 | /// provided any attribute args. | |
1256 | /// | |
1257 | /// ``` | |
f035d41b XL |
1258 | /// # extern crate proc_macro; |
1259 | /// # | |
e74abb32 XL |
1260 | /// use proc_macro::TokenStream; |
1261 | /// use syn::parse_macro_input; | |
1262 | /// use syn::parse::Nothing; | |
1263 | /// | |
1264 | /// # const IGNORE: &str = stringify! { | |
1265 | /// #[proc_macro_attribute] | |
1266 | /// # }; | |
1267 | /// pub fn my_attr(args: TokenStream, input: TokenStream) -> TokenStream { | |
1268 | /// parse_macro_input!(args as Nothing); | |
1269 | /// | |
1270 | /// /* ... */ | |
1271 | /// # "".parse().unwrap() | |
1272 | /// } | |
1273 | /// ``` | |
1274 | /// | |
1275 | /// ```text | |
1276 | /// error: unexpected token | |
1277 | /// --> src/main.rs:3:19 | |
1278 | /// | | |
1279 | /// 3 | #[my_attr(asdf)] | |
1280 | /// | ^^^^ | |
1281 | /// ``` | |
1282 | pub struct Nothing; | |
1283 | ||
1284 | impl Parse for Nothing { | |
1285 | fn parse(_input: ParseStream) -> Result<Self> { | |
1286 | Ok(Nothing) | |
1287 | } | |
1288 | } | |
5e7ed085 FG |
1289 | |
1290 | #[cfg(feature = "extra-traits")] | |
1291 | #[cfg_attr(doc_cfg, doc(cfg(feature = "extra-traits")))] | |
1292 | impl Debug for Nothing { | |
1293 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
1294 | f.write_str("Nothing") | |
1295 | } | |
1296 | } | |
1297 | ||
1298 | #[cfg(feature = "extra-traits")] | |
1299 | #[cfg_attr(doc_cfg, doc(cfg(feature = "extra-traits")))] | |
1300 | impl Eq for Nothing {} | |
1301 | ||
1302 | #[cfg(feature = "extra-traits")] | |
1303 | #[cfg_attr(doc_cfg, doc(cfg(feature = "extra-traits")))] | |
1304 | impl PartialEq for Nothing { | |
1305 | fn eq(&self, _other: &Self) -> bool { | |
1306 | true | |
1307 | } | |
1308 | } | |
1309 | ||
1310 | #[cfg(feature = "extra-traits")] | |
1311 | #[cfg_attr(doc_cfg, doc(cfg(feature = "extra-traits")))] | |
1312 | impl Hash for Nothing { | |
1313 | fn hash<H: Hasher>(&self, _state: &mut H) {} | |
1314 | } |