FILE
parse.rs
File preview with syntax highlighting.
linux-6.19.14/rust/syn/parse.rs
1// SPDX-License-Identifier: Apache-2.0 OR MIT 2 3//! Parsing interface for parsing a token stream into a syntax tree node. 4//! 5//! Parsing in Syn is built on parser functions that take in a [`ParseStream`] 6//! and produce a [`Result<T>`] where `T` is some syntax tree node. Underlying 7//! these parser functions is a lower level mechanism built around the 8//! [`Cursor`] type. `Cursor` is a cheaply copyable cursor over a range of 9//! tokens in a token stream. 10//! 11//! [`Result<T>`]: Result 12//! [`Cursor`]: crate::buffer::Cursor 13//! 14//! # Example 15//! 16//! Here is a snippet of parsing code to get a feel for the style of the 17//! library. We define data structures for a subset of Rust syntax including 18//! enums (not shown) and structs, then provide implementations of the [`Parse`] 19//! trait to parse these syntax tree data structures from a token stream. 20//! 21//! Once `Parse` impls have been defined, they can be called conveniently from a 22//! procedural macro through [`parse_macro_input!`] as shown at the bottom of 23//! the snippet. If the caller provides syntactically invalid input to the 24//! procedural macro, they will receive a helpful compiler error message 25//! pointing out the exact token that triggered the failure to parse. 26//! 27//! [`parse_macro_input!`]: crate::parse_macro_input! 28//! 29//! ``` 30//! # extern crate proc_macro; 31//! # 32//! use proc_macro::TokenStream; 33//! use syn::{braced, parse_macro_input, token, Field, Ident, Result, Token}; 34//! use syn::parse::{Parse, ParseStream}; 35//! use syn::punctuated::Punctuated; 36//! 37//! enum Item { 38//! Struct(ItemStruct), 39//! Enum(ItemEnum), 40//! } 41//! 42//! struct ItemStruct { 43//! struct_token: Token![struct], 44//! ident: Ident, 45//! brace_token: token::Brace, 46//! fields: Punctuated<Field, Token![,]>, 47//! } 48//! # 49//! # enum ItemEnum {} 50//! 51//! impl Parse for Item { 52//! fn parse(input: ParseStream) -> Result<Self> { 53//! let lookahead = input.lookahead1(); 54//! if lookahead.peek(Token![struct]) { 55//! input.parse().map(Item::Struct) 56//! } else if lookahead.peek(Token![enum]) { 57//! input.parse().map(Item::Enum) 58//! } else { 59//! Err(lookahead.error()) 60//! } 61//! } 62//! } 63//! 64//! impl Parse for ItemStruct { 65//! fn parse(input: ParseStream) -> Result<Self> { 66//! let content; 67//! Ok(ItemStruct { 68//! struct_token: input.parse()?, 69//! ident: input.parse()?, 70//! brace_token: braced!(content in input), 71//! fields: content.parse_terminated(Field::parse_named, Token![,])?, 72//! }) 73//! } 74//! } 75//! # 76//! # impl Parse for ItemEnum { 77//! # fn parse(input: ParseStream) -> Result<Self> { 78//! # unimplemented!() 79//! # } 80//! # } 81//! 82//! # const IGNORE: &str = stringify! { 83//! #[proc_macro] 84//! # }; 85//! pub fn my_macro(tokens: TokenStream) -> TokenStream { 86//! let input = parse_macro_input!(tokens as Item); 87//! 88//! /* ... */ 89//! # TokenStream::new() 90//! } 91//! ``` 92//! 93//! # The `syn::parse*` functions 94//! 95//! The [`syn::parse`], [`syn::parse2`], and [`syn::parse_str`] functions serve 96//! as an entry point for parsing syntax tree nodes that can be parsed in an 97//! obvious default way. These functions can return any syntax tree node that 98//! implements the [`Parse`] trait, which includes most types in Syn. 99//! 100//! [`syn::parse`]: crate::parse() 101//! [`syn::parse2`]: crate::parse2() 102//! [`syn::parse_str`]: crate::parse_str() 103//! 104//! ``` 105//! use syn::Type; 106//! 107//! # fn run_parser() -> syn::Result<()> { 108//! let t: Type = syn::parse_str("std::collections::HashMap<String, Value>")?; 109//! # Ok(()) 110//! # } 111//! # 112//! # run_parser().unwrap(); 113//! ``` 114//! 115//! The [`parse_quote!`] macro also uses this approach. 116//! 117//! [`parse_quote!`]: crate::parse_quote! 118//! 119//! # The `Parser` trait 120//! 121//! Some types can be parsed in several ways depending on context. For example 122//! an [`Attribute`] can be either "outer" like `#[...]` or "inner" like 123//! `#![...]` and parsing the wrong one would be a bug. Similarly [`Punctuated`] 124//! may or may not allow trailing punctuation, and parsing it the wrong way 125//! would either reject valid input or accept invalid input. 126//! 127//! [`Attribute`]: crate::Attribute 128//! [`Punctuated`]: crate::punctuated 129//! 130//! The `Parse` trait is not implemented in these cases because there is no good 131//! behavior to consider the default. 132//! 133//! ```compile_fail 134//! # extern crate proc_macro; 135//! # 136//! # use syn::punctuated::Punctuated; 137//! # use syn::{PathSegment, Result, Token}; 138//! # 139//! # fn f(tokens: proc_macro::TokenStream) -> Result<()> { 140//! # 141//! // Can't parse `Punctuated` without knowing whether trailing punctuation 142//! // should be allowed in this context. 143//! let path: Punctuated<PathSegment, Token![::]> = syn::parse(tokens)?; 144//! # 145//! # Ok(()) 146//! # } 147//! ``` 148//! 149//! In these cases the types provide a choice of parser functions rather than a 150//! single `Parse` implementation, and those parser functions can be invoked 151//! through the [`Parser`] trait. 152//! 153//! 154//! ``` 155//! # extern crate proc_macro; 156//! # 157//! use proc_macro::TokenStream; 158//! use syn::parse::Parser; 159//! use syn::punctuated::Punctuated; 160//! use syn::{Attribute, Expr, PathSegment, Result, Token}; 161//! 162//! fn call_some_parser_methods(input: TokenStream) -> Result<()> { 163//! // Parse a nonempty sequence of path segments separated by `::` punctuation 164//! // with no trailing punctuation. 165//! let tokens = input.clone(); 166//! let parser = Punctuated::<PathSegment, Token![::]>::parse_separated_nonempty; 167//! let _path = parser.parse(tokens)?; 168//! 169//! // Parse a possibly empty sequence of expressions terminated by commas with 170//! // an optional trailing punctuation. 171//! let tokens = input.clone(); 172//! let parser = Punctuated::<Expr, Token![,]>::parse_terminated; 173//! let _args = parser.parse(tokens)?; 174//! 175//! // Parse zero or more outer attributes but not inner attributes. 176//! let tokens = input.clone(); 177//! let parser = Attribute::parse_outer; 178//! let _attrs = parser.parse(tokens)?; 179//! 180//! Ok(()) 181//! } 182//! ``` 183 184#[path = "discouraged.rs"] 185pub mod discouraged; 186 187use crate::buffer::{Cursor, TokenBuffer}; 188use crate::error; 189use crate::lookahead; 190use crate::punctuated::Punctuated; 191use crate::token::Token; 192use proc_macro2::{Delimiter, Group, Literal, Punct, Span, TokenStream, TokenTree}; 193#[cfg(feature = "printing")] 194use quote::ToTokens; 195use std::cell::Cell; 196use std::fmt::{self, Debug, Display}; 197#[cfg(feature = "extra-traits")] 198use std::hash::{Hash, Hasher}; 199use std::marker::PhantomData; 200use std::mem; 201use std::ops::Deref; 202use std::panic::{RefUnwindSafe, UnwindSafe}; 203use std::rc::Rc; 204use std::str::FromStr; 205 206pub use crate::error::{Error, Result}; 207pub use crate::lookahead::{End, Lookahead1, Peek}; 208 209/// Parsing interface implemented by all types that can be parsed in a default 210/// way from a token stream. 211/// 212/// Refer to the [module documentation] for details about implementing and using 213/// the `Parse` trait. 214/// 215/// [module documentation]: self 216pub trait Parse: Sized { 217 fn parse(input: ParseStream) -> Result<Self>; 218} 219 220/// Input to a Syn parser function. 221/// 222/// See the methods of this type under the documentation of [`ParseBuffer`]. For 223/// an overview of parsing in Syn, refer to the [module documentation]. 224/// 225/// [module documentation]: self 226pub type ParseStream<'a> = &'a ParseBuffer<'a>; 227 228/// Cursor position within a buffered token stream. 229/// 230/// This type is more commonly used through the type alias [`ParseStream`] which 231/// is an alias for `&ParseBuffer`. 232/// 233/// `ParseStream` is the input type for all parser functions in Syn. They have 234/// the signature `fn(ParseStream) -> Result<T>`. 235/// 236/// ## Calling a parser function 237/// 238/// There is no public way to construct a `ParseBuffer`. Instead, if you are 239/// looking to invoke a parser function that requires `ParseStream` as input, 240/// you will need to go through one of the public parsing entry points. 241/// 242/// - The [`parse_macro_input!`] macro if parsing input of a procedural macro; 243/// - One of [the `syn::parse*` functions][syn-parse]; or 244/// - A method of the [`Parser`] trait. 245/// 246/// [`parse_macro_input!`]: crate::parse_macro_input! 247/// [syn-parse]: self#the-synparse-functions 248pub struct ParseBuffer<'a> { 249 scope: Span, 250 // Instead of Cell<Cursor<'a>> so that ParseBuffer<'a> is covariant in 'a. 251 // The rest of the code in this module needs to be careful that only a 252 // cursor derived from this `cell` is ever assigned to this `cell`. 253 // 254 // Cell<Cursor<'a>> cannot be covariant in 'a because then we could take a 255 // ParseBuffer<'a>, upcast to ParseBuffer<'short> for some lifetime shorter 256 // than 'a, and then assign a Cursor<'short> into the Cell. 257 // 258 // By extension, it would not be safe to expose an API that accepts a 259 // Cursor<'a> and trusts that it lives as long as the cursor currently in 260 // the cell. 261 cell: Cell<Cursor<'static>>, 262 marker: PhantomData<Cursor<'a>>, 263 unexpected: Cell<Option<Rc<Cell<Unexpected>>>>, 264} 265 266impl<'a> Drop for ParseBuffer<'a> { 267 fn drop(&mut self) { 268 if let Some((unexpected_span, delimiter)) = span_of_unexpected_ignoring_nones(self.cursor()) 269 { 270 let (inner, old_span) = inner_unexpected(self); 271 if old_span.is_none() { 272 inner.set(Unexpected::Some(unexpected_span, delimiter)); 273 } 274 } 275 } 276} 277 278impl<'a> Display for ParseBuffer<'a> { 279 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 280 Display::fmt(&self.cursor().token_stream(), f) 281 } 282} 283 284impl<'a> Debug for ParseBuffer<'a> { 285 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 286 Debug::fmt(&self.cursor().token_stream(), f) 287 } 288} 289 290impl<'a> UnwindSafe for ParseBuffer<'a> {} 291impl<'a> RefUnwindSafe for ParseBuffer<'a> {} 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/// # 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"); 336/// ``` 337pub 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 352impl<'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 360impl<'c, 'a> Copy for StepCursor<'c, 'a> {} 361 362impl<'c, 'a> Clone for StepCursor<'c, 'a> { 363 fn clone(&self) -> Self { 364 *self 365 } 366} 367 368impl<'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 378pub(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 387pub(crate) fn new_parse_buffer( 388 scope: Span, 389 cursor: Cursor, 390 unexpected: Rc<Cell<Unexpected>>, 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, 397 unexpected: Cell::new(Some(unexpected)), 398 } 399} 400 401pub(crate) enum Unexpected { 402 None, 403 Some(Span, Delimiter), 404 Chain(Rc<Cell<Unexpected>>), 405} 406 407impl Default for Unexpected { 408 fn default() -> Self { 409 Unexpected::None 410 } 411} 412 413impl Clone for Unexpected { 414 fn clone(&self) -> Self { 415 match self { 416 Unexpected::None => Unexpected::None, 417 Unexpected::Some(span, delimiter) => Unexpected::Some(*span, *delimiter), 418 Unexpected::Chain(next) => Unexpected::Chain(next.clone()), 419 } 420 } 421} 422 423// We call this on Cell<Unexpected> and Cell<Option<T>> where temporarily 424// swapping in a None is cheap. 425fn 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 432fn inner_unexpected(buffer: &ParseBuffer) -> (Rc<Cell<Unexpected>>, Option<(Span, Delimiter)>) { 433 let mut unexpected = get_unexpected(buffer); 434 loop { 435 match cell_clone(&unexpected) { 436 Unexpected::None => return (unexpected, None), 437 Unexpected::Some(span, delimiter) => return (unexpected, Some((span, delimiter))), 438 Unexpected::Chain(next) => unexpected = next, 439 } 440 } 441} 442 443pub(crate) fn get_unexpected(buffer: &ParseBuffer) -> Rc<Cell<Unexpected>> { 444 cell_clone(&buffer.unexpected).unwrap() 445} 446 447fn span_of_unexpected_ignoring_nones(mut cursor: Cursor) -> Option<(Span, Delimiter)> { 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(), cursor.scope_delimiter())) 461 } 462} 463 464impl<'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>(&'a self, function: fn(ParseStream<'a>) -> 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(syn::Ident)` *(does not accept keywords)* 524 /// - `input.peek(syn::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 { 623 fn peek2(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { 624 buffer.cursor().skip().map_or(false, peek) 625 } 626 627 let _ = token; 628 peek2(self, T::Token::peek) 629 } 630 631 /// Looks at the third-next token in the parse stream. 632 pub fn peek3<T: Peek>(&self, token: T) -> bool { 633 fn peek3(buffer: &ParseBuffer, peek: fn(Cursor) -> bool) -> bool { 634 buffer 635 .cursor() 636 .skip() 637 .and_then(Cursor::skip) 638 .map_or(false, peek) 639 } 640 641 let _ = token; 642 peek3(self, T::Token::peek) 643 } 644 645 /// Parses zero or more occurrences of `T` separated by punctuation of type 646 /// `P`, with optional trailing punctuation. 647 /// 648 /// Parsing continues until the end of this parse stream. The entire content 649 /// of this parse stream must consist of `T` and `P`. 650 /// 651 /// # Example 652 /// 653 /// ``` 654 /// # use quote::quote; 655 /// # 656 /// use syn::{parenthesized, token, Ident, Result, Token, Type}; 657 /// use syn::parse::{Parse, ParseStream}; 658 /// use syn::punctuated::Punctuated; 659 /// 660 /// // Parse a simplified tuple struct syntax like: 661 /// // 662 /// // struct S(A, B); 663 /// struct TupleStruct { 664 /// struct_token: Token![struct], 665 /// ident: Ident, 666 /// paren_token: token::Paren, 667 /// fields: Punctuated<Type, Token![,]>, 668 /// semi_token: Token![;], 669 /// } 670 /// 671 /// impl Parse for TupleStruct { 672 /// fn parse(input: ParseStream) -> Result<Self> { 673 /// let content; 674 /// Ok(TupleStruct { 675 /// struct_token: input.parse()?, 676 /// ident: input.parse()?, 677 /// paren_token: parenthesized!(content in input), 678 /// fields: content.parse_terminated(Type::parse, Token![,])?, 679 /// semi_token: input.parse()?, 680 /// }) 681 /// } 682 /// } 683 /// # 684 /// # let input = quote! { 685 /// # struct S(A, B); 686 /// # }; 687 /// # syn::parse2::<TupleStruct>(input).unwrap(); 688 /// ``` 689 /// 690 /// # See also 691 /// 692 /// If your separator is anything more complicated than an invocation of the 693 /// `Token!` macro, this method won't be applicable and you can instead 694 /// directly use `Punctuated`'s parser functions: [`parse_terminated`], 695 /// [`parse_separated_nonempty`] etc. 696 /// 697 /// [`parse_terminated`]: Punctuated::parse_terminated 698 /// [`parse_separated_nonempty`]: Punctuated::parse_separated_nonempty 699 /// 700 /// ``` 701 /// use syn::{custom_keyword, Expr, Result, Token}; 702 /// use syn::parse::{Parse, ParseStream}; 703 /// use syn::punctuated::Punctuated; 704 /// 705 /// mod kw { 706 /// syn::custom_keyword!(fin); 707 /// } 708 /// 709 /// struct Fin(kw::fin, Token![;]); 710 /// 711 /// impl Parse for Fin { 712 /// fn parse(input: ParseStream) -> Result<Self> { 713 /// Ok(Self(input.parse()?, input.parse()?)) 714 /// } 715 /// } 716 /// 717 /// struct Thing { 718 /// steps: Punctuated<Expr, Fin>, 719 /// } 720 /// 721 /// impl Parse for Thing { 722 /// fn parse(input: ParseStream) -> Result<Self> { 723 /// # if true { 724 /// Ok(Thing { 725 /// steps: Punctuated::parse_terminated(input)?, 726 /// }) 727 /// # } else { 728 /// // or equivalently, this means the same thing: 729 /// # Ok(Thing { 730 /// steps: input.call(Punctuated::parse_terminated)?, 731 /// # }) 732 /// # } 733 /// } 734 /// } 735 /// ``` 736 pub fn parse_terminated<T, P>( 737 &'a self, 738 parser: fn(ParseStream<'a>) -> Result<T>, 739 separator: P, 740 ) -> Result<Punctuated<T, P::Token>> 741 where 742 P: Peek, 743 P::Token: Parse, 744 { 745 let _ = separator; 746 Punctuated::parse_terminated_with(self, parser) 747 } 748 749 /// Returns whether there are no more tokens remaining to be parsed from 750 /// this stream. 751 /// 752 /// This method returns true upon reaching the end of the content within a 753 /// set of delimiters, as well as at the end of the tokens provided to the 754 /// outermost parsing entry point. 755 /// 756 /// This is equivalent to 757 /// <code>.<a href="#method.peek">peek</a>(<a href="struct.End.html">syn::parse::End</a>)</code>. 758 /// Use `.peek2(End)` or `.peek3(End)` to look for the end of a parse stream 759 /// further ahead than the current position. 760 /// 761 /// # Example 762 /// 763 /// ``` 764 /// use syn::{braced, token, Ident, Item, Result, Token}; 765 /// use syn::parse::{Parse, ParseStream}; 766 /// 767 /// // Parses a Rust `mod m { ... }` containing zero or more items. 768 /// struct Mod { 769 /// mod_token: Token![mod], 770 /// name: Ident, 771 /// brace_token: token::Brace, 772 /// items: Vec<Item>, 773 /// } 774 /// 775 /// impl Parse for Mod { 776 /// fn parse(input: ParseStream) -> Result<Self> { 777 /// let content; 778 /// Ok(Mod { 779 /// mod_token: input.parse()?, 780 /// name: input.parse()?, 781 /// brace_token: braced!(content in input), 782 /// items: { 783 /// let mut items = Vec::new(); 784 /// while !content.is_empty() { 785 /// items.push(content.parse()?); 786 /// } 787 /// items 788 /// }, 789 /// }) 790 /// } 791 /// } 792 /// ``` 793 pub fn is_empty(&self) -> bool { 794 self.cursor().eof() 795 } 796 797 /// Constructs a helper for peeking at the next token in this stream and 798 /// building an error message if it is not one of a set of expected tokens. 799 /// 800 /// # Example 801 /// 802 /// ``` 803 /// use syn::{ConstParam, Ident, Lifetime, LifetimeParam, Result, Token, TypeParam}; 804 /// use syn::parse::{Parse, ParseStream}; 805 /// 806 /// // A generic parameter, a single one of the comma-separated elements inside 807 /// // angle brackets in: 808 /// // 809 /// // fn f<T: Clone, 'a, 'b: 'a, const N: usize>() { ... } 810 /// // 811 /// // On invalid input, lookahead gives us a reasonable error message. 812 /// // 813 /// // error: expected one of: identifier, lifetime, `const` 814 /// // | 815 /// // 5 | fn f<!Sized>() {} 816 /// // | ^ 817 /// enum GenericParam { 818 /// Type(TypeParam), 819 /// Lifetime(LifetimeParam), 820 /// Const(ConstParam), 821 /// } 822 /// 823 /// impl Parse for GenericParam { 824 /// fn parse(input: ParseStream) -> Result<Self> { 825 /// let lookahead = input.lookahead1(); 826 /// if lookahead.peek(Ident) { 827 /// input.parse().map(GenericParam::Type) 828 /// } else if lookahead.peek(Lifetime) { 829 /// input.parse().map(GenericParam::Lifetime) 830 /// } else if lookahead.peek(Token![const]) { 831 /// input.parse().map(GenericParam::Const) 832 /// } else { 833 /// Err(lookahead.error()) 834 /// } 835 /// } 836 /// } 837 /// ``` 838 pub fn lookahead1(&self) -> Lookahead1<'a> { 839 lookahead::new(self.scope, self.cursor()) 840 } 841 842 /// Forks a parse stream so that parsing tokens out of either the original 843 /// or the fork does not advance the position of the other. 844 /// 845 /// # Performance 846 /// 847 /// Forking a parse stream is a cheap fixed amount of work and does not 848 /// involve copying token buffers. Where you might hit performance problems 849 /// is if your macro ends up parsing a large amount of content more than 850 /// once. 851 /// 852 /// ``` 853 /// # use syn::{Expr, Result}; 854 /// # use syn::parse::ParseStream; 855 /// # 856 /// # fn bad(input: ParseStream) -> Result<Expr> { 857 /// // Do not do this. 858 /// if input.fork().parse::<Expr>().is_ok() { 859 /// return input.parse::<Expr>(); 860 /// } 861 /// # unimplemented!() 862 /// # } 863 /// ``` 864 /// 865 /// As a rule, avoid parsing an unbounded amount of tokens out of a forked 866 /// parse stream. Only use a fork when the amount of work performed against 867 /// the fork is small and bounded. 868 /// 869 /// When complex speculative parsing against the forked stream is 870 /// unavoidable, use [`parse::discouraged::Speculative`] to advance the 871 /// original stream once the fork's parse is determined to have been 872 /// successful. 873 /// 874 /// For a lower level way to perform speculative parsing at the token level, 875 /// consider using [`ParseStream::step`] instead. 876 /// 877 /// [`parse::discouraged::Speculative`]: discouraged::Speculative 878 /// [`ParseStream::step`]: ParseBuffer::step 879 /// 880 /// # Example 881 /// 882 /// The parse implementation shown here parses possibly restricted `pub` 883 /// visibilities. 884 /// 885 /// - `pub` 886 /// - `pub(crate)` 887 /// - `pub(self)` 888 /// - `pub(super)` 889 /// - `pub(in some::path)` 890 /// 891 /// To handle the case of visibilities inside of tuple structs, the parser 892 /// needs to distinguish parentheses that specify visibility restrictions 893 /// from parentheses that form part of a tuple type. 894 /// 895 /// ``` 896 /// # struct A; 897 /// # struct B; 898 /// # struct C; 899 /// # 900 /// struct S(pub(crate) A, pub (B, C)); 901 /// ``` 902 /// 903 /// In this example input the first tuple struct element of `S` has 904 /// `pub(crate)` visibility while the second tuple struct element has `pub` 905 /// visibility; the parentheses around `(B, C)` are part of the type rather 906 /// than part of a visibility restriction. 907 /// 908 /// The parser uses a forked parse stream to check the first token inside of 909 /// parentheses after the `pub` keyword. This is a small bounded amount of 910 /// work performed against the forked parse stream. 911 /// 912 /// ``` 913 /// use syn::{parenthesized, token, Ident, Path, Result, Token}; 914 /// use syn::ext::IdentExt; 915 /// use syn::parse::{Parse, ParseStream}; 916 /// 917 /// struct PubVisibility { 918 /// pub_token: Token![pub], 919 /// restricted: Option<Restricted>, 920 /// } 921 /// 922 /// struct Restricted { 923 /// paren_token: token::Paren, 924 /// in_token: Option<Token![in]>, 925 /// path: Path, 926 /// } 927 /// 928 /// impl Parse for PubVisibility { 929 /// fn parse(input: ParseStream) -> Result<Self> { 930 /// let pub_token: Token![pub] = input.parse()?; 931 /// 932 /// if input.peek(token::Paren) { 933 /// let ahead = input.fork(); 934 /// let mut content; 935 /// parenthesized!(content in ahead); 936 /// 937 /// if content.peek(Token![crate]) 938 /// || content.peek(Token![self]) 939 /// || content.peek(Token![super]) 940 /// { 941 /// return Ok(PubVisibility { 942 /// pub_token, 943 /// restricted: Some(Restricted { 944 /// paren_token: parenthesized!(content in input), 945 /// in_token: None, 946 /// path: Path::from(content.call(Ident::parse_any)?), 947 /// }), 948 /// }); 949 /// } else if content.peek(Token![in]) { 950 /// return Ok(PubVisibility { 951 /// pub_token, 952 /// restricted: Some(Restricted { 953 /// paren_token: parenthesized!(content in input), 954 /// in_token: Some(content.parse()?), 955 /// path: content.call(Path::parse_mod_style)?, 956 /// }), 957 /// }); 958 /// } 959 /// } 960 /// 961 /// Ok(PubVisibility { 962 /// pub_token, 963 /// restricted: None, 964 /// }) 965 /// } 966 /// } 967 /// ``` 968 pub fn fork(&self) -> Self { 969 ParseBuffer { 970 scope: self.scope, 971 cell: self.cell.clone(), 972 marker: PhantomData, 973 // Not the parent's unexpected. Nothing cares whether the clone 974 // parses all the way unless we `advance_to`. 975 unexpected: Cell::new(Some(Rc::new(Cell::new(Unexpected::None)))), 976 } 977 } 978 979 /// Triggers an error at the current position of the parse stream. 980 /// 981 /// # Example 982 /// 983 /// ``` 984 /// use syn::{Expr, Result, Token}; 985 /// use syn::parse::{Parse, ParseStream}; 986 /// 987 /// // Some kind of loop: `while` or `for` or `loop`. 988 /// struct Loop { 989 /// expr: Expr, 990 /// } 991 /// 992 /// impl Parse for Loop { 993 /// fn parse(input: ParseStream) -> Result<Self> { 994 /// if input.peek(Token![while]) 995 /// || input.peek(Token![for]) 996 /// || input.peek(Token![loop]) 997 /// { 998 /// Ok(Loop { 999 /// expr: input.parse()?, 1000 /// }) 1001 /// } else { 1002 /// Err(input.error("expected some kind of loop")) 1003 /// } 1004 /// } 1005 /// } 1006 /// ``` 1007 pub fn error<T: Display>(&self, message: T) -> Error { 1008 error::new_at(self.scope, self.cursor(), message) 1009 } 1010 1011 /// Speculatively parses tokens from this parse stream, advancing the 1012 /// position of this stream only if parsing succeeds. 1013 /// 1014 /// This is a powerful low-level API used for defining the `Parse` impls of 1015 /// the basic built-in token types. It is not something that will be used 1016 /// widely outside of the Syn codebase. 1017 /// 1018 /// # Example 1019 /// 1020 /// ``` 1021 /// use proc_macro2::TokenTree; 1022 /// use syn::Result; 1023 /// use syn::parse::ParseStream; 1024 /// 1025 /// // This function advances the stream past the next occurrence of `@`. If 1026 /// // no `@` is present in the stream, the stream position is unchanged and 1027 /// // an error is returned. 1028 /// fn skip_past_next_at(input: ParseStream) -> Result<()> { 1029 /// input.step(|cursor| { 1030 /// let mut rest = *cursor; 1031 /// while let Some((tt, next)) = rest.token_tree() { 1032 /// match &tt { 1033 /// TokenTree::Punct(punct) if punct.as_char() == '@' => { 1034 /// return Ok(((), next)); 1035 /// } 1036 /// _ => rest = next, 1037 /// } 1038 /// } 1039 /// Err(cursor.error("no `@` was found after this point")) 1040 /// }) 1041 /// } 1042 /// # 1043 /// # fn remainder_after_skipping_past_next_at( 1044 /// # input: ParseStream, 1045 /// # ) -> Result<proc_macro2::TokenStream> { 1046 /// # skip_past_next_at(input)?; 1047 /// # input.parse() 1048 /// # } 1049 /// # 1050 /// # use syn::parse::Parser; 1051 /// # let remainder = remainder_after_skipping_past_next_at 1052 /// # .parse_str("a @ b c") 1053 /// # .unwrap(); 1054 /// # assert_eq!(remainder.to_string(), "b c"); 1055 /// ``` 1056 pub fn step<F, R>(&self, function: F) -> Result<R> 1057 where 1058 F: for<'c> FnOnce(StepCursor<'c, 'a>) -> Result<(R, Cursor<'c>)>, 1059 { 1060 // Since the user's function is required to work for any 'c, we know 1061 // that the Cursor<'c> they return is either derived from the input 1062 // StepCursor<'c, 'a> or from a Cursor<'static>. 1063 // 1064 // It would not be legal to write this function without the invariant 1065 // lifetime 'c in StepCursor<'c, 'a>. If this function were written only 1066 // in terms of 'a, the user could take our ParseBuffer<'a>, upcast it to 1067 // a ParseBuffer<'short> which some shorter lifetime than 'a, invoke 1068 // `step` on their ParseBuffer<'short> with a closure that returns 1069 // Cursor<'short>, and we would wrongly write that Cursor<'short> into 1070 // the Cell intended to hold Cursor<'a>. 1071 // 1072 // In some cases it may be necessary for R to contain a Cursor<'a>. 1073 // Within Syn we solve this using `advance_step_cursor` which uses the 1074 // existence of a StepCursor<'c, 'a> as proof that it is safe to cast 1075 // from Cursor<'c> to Cursor<'a>. If needed outside of Syn, it would be 1076 // safe to expose that API as a method on StepCursor. 1077 let (node, rest) = function(StepCursor { 1078 scope: self.scope, 1079 cursor: self.cell.get(), 1080 marker: PhantomData, 1081 })?; 1082 self.cell.set(rest); 1083 Ok(node) 1084 } 1085 1086 /// Returns the `Span` of the next token in the parse stream, or 1087 /// `Span::call_site()` if this parse stream has completely exhausted its 1088 /// input `TokenStream`. 1089 pub fn span(&self) -> Span { 1090 let cursor = self.cursor(); 1091 if cursor.eof() { 1092 self.scope 1093 } else { 1094 crate::buffer::open_span_of_group(cursor) 1095 } 1096 } 1097 1098 /// Provides low-level access to the token representation underlying this 1099 /// parse stream. 1100 /// 1101 /// Cursors are immutable so no operations you perform against the cursor 1102 /// will affect the state of this parse stream. 1103 /// 1104 /// # Example 1105 /// 1106 /// ``` 1107 /// use proc_macro2::TokenStream; 1108 /// use syn::buffer::Cursor; 1109 /// use syn::parse::{ParseStream, Result}; 1110 /// 1111 /// // Run a parser that returns T, but get its output as TokenStream instead of T. 1112 /// // This works without T needing to implement ToTokens. 1113 /// fn recognize_token_stream<T>( 1114 /// recognizer: fn(ParseStream) -> Result<T>, 1115 /// ) -> impl Fn(ParseStream) -> Result<TokenStream> { 1116 /// move |input| { 1117 /// let begin = input.cursor(); 1118 /// recognizer(input)?; 1119 /// let end = input.cursor(); 1120 /// Ok(tokens_between(begin, end)) 1121 /// } 1122 /// } 1123 /// 1124 /// // Collect tokens between two cursors as a TokenStream. 1125 /// fn tokens_between(begin: Cursor, end: Cursor) -> TokenStream { 1126 /// assert!(begin <= end); 1127 /// 1128 /// let mut cursor = begin; 1129 /// let mut tokens = TokenStream::new(); 1130 /// while cursor < end { 1131 /// let (token, next) = cursor.token_tree().unwrap(); 1132 /// tokens.extend(std::iter::once(token)); 1133 /// cursor = next; 1134 /// } 1135 /// tokens 1136 /// } 1137 /// 1138 /// fn main() { 1139 /// use quote::quote; 1140 /// use syn::parse::{Parse, Parser}; 1141 /// use syn::Token; 1142 /// 1143 /// // Parse syn::Type as a TokenStream, surrounded by angle brackets. 1144 /// fn example(input: ParseStream) -> Result<TokenStream> { 1145 /// let _langle: Token![<] = input.parse()?; 1146 /// let ty = recognize_token_stream(syn::Type::parse)(input)?; 1147 /// let _rangle: Token![>] = input.parse()?; 1148 /// Ok(ty) 1149 /// } 1150 /// 1151 /// let tokens = quote! { <fn() -> u8> }; 1152 /// println!("{}", example.parse2(tokens).unwrap()); 1153 /// } 1154 /// ``` 1155 pub fn cursor(&self) -> Cursor<'a> { 1156 self.cell.get() 1157 } 1158 1159 fn check_unexpected(&self) -> Result<()> { 1160 match inner_unexpected(self).1 { 1161 Some((span, delimiter)) => Err(err_unexpected_token(span, delimiter)), 1162 None => Ok(()), 1163 } 1164 } 1165} 1166 1167#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1168impl<T: Parse> Parse for Box<T> { 1169 fn parse(input: ParseStream) -> Result<Self> { 1170 input.parse().map(Box::new) 1171 } 1172} 1173 1174#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1175impl<T: Parse + Token> Parse for Option<T> { 1176 fn parse(input: ParseStream) -> Result<Self> { 1177 if T::peek(input.cursor()) { 1178 Ok(Some(input.parse()?)) 1179 } else { 1180 Ok(None) 1181 } 1182 } 1183} 1184 1185#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1186impl Parse for TokenStream { 1187 fn parse(input: ParseStream) -> Result<Self> { 1188 input.step(|cursor| Ok((cursor.token_stream(), Cursor::empty()))) 1189 } 1190} 1191 1192#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1193impl Parse for TokenTree { 1194 fn parse(input: ParseStream) -> Result<Self> { 1195 input.step(|cursor| match cursor.token_tree() { 1196 Some((tt, rest)) => Ok((tt, rest)), 1197 None => Err(cursor.error("expected token tree")), 1198 }) 1199 } 1200} 1201 1202#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1203impl Parse for Group { 1204 fn parse(input: ParseStream) -> Result<Self> { 1205 input.step(|cursor| { 1206 if let Some((group, rest)) = cursor.any_group_token() { 1207 if group.delimiter() != Delimiter::None { 1208 return Ok((group, rest)); 1209 } 1210 } 1211 Err(cursor.error("expected group token")) 1212 }) 1213 } 1214} 1215 1216#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1217impl Parse for Punct { 1218 fn parse(input: ParseStream) -> Result<Self> { 1219 input.step(|cursor| match cursor.punct() { 1220 Some((punct, rest)) => Ok((punct, rest)), 1221 None => Err(cursor.error("expected punctuation token")), 1222 }) 1223 } 1224} 1225 1226#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] 1227impl Parse for Literal { 1228 fn parse(input: ParseStream) -> Result<Self> { 1229 input.step(|cursor| match cursor.literal() { 1230 Some((literal, rest)) => Ok((literal, rest)), 1231 None => Err(cursor.error("expected literal token")), 1232 }) 1233 } 1234} 1235 1236/// Parser that can parse Rust tokens into a particular syntax tree node. 1237/// 1238/// Refer to the [module documentation] for details about parsing in Syn. 1239/// 1240/// [module documentation]: self 1241pub trait Parser: Sized { 1242 type Output; 1243 1244 /// Parse a proc-macro2 token stream into the chosen syntax tree node. 1245 /// 1246 /// This function enforces that the input is fully parsed. If there are any 1247 /// unparsed tokens at the end of the stream, an error is returned. 1248 fn parse2(self, tokens: TokenStream) -> Result<Self::Output>; 1249 1250 /// Parse tokens of source code into the chosen syntax tree node. 1251 /// 1252 /// This function enforces that the input is fully parsed. If there are any 1253 /// unparsed tokens at the end of the stream, an error is returned. 1254 #[cfg(feature = "proc-macro")] 1255 #[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))] 1256 fn parse(self, tokens: proc_macro::TokenStream) -> Result<Self::Output> { 1257 self.parse2(proc_macro2::TokenStream::from(tokens)) 1258 } 1259 1260 /// Parse a string of Rust code into the chosen syntax tree node. 1261 /// 1262 /// This function enforces that the input is fully parsed. If there are any 1263 /// unparsed tokens at the end of the string, an error is returned. 1264 /// 1265 /// # Hygiene 1266 /// 1267 /// Every span in the resulting syntax tree will be set to resolve at the 1268 /// macro call site. 1269 fn parse_str(self, s: &str) -> Result<Self::Output> { 1270 self.parse2(proc_macro2::TokenStream::from_str(s)?) 1271 } 1272 1273 // Not public API. 1274 #[doc(hidden)] 1275 fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { 1276 let _ = scope; 1277 self.parse2(tokens) 1278 } 1279} 1280 1281fn tokens_to_parse_buffer(tokens: &TokenBuffer) -> ParseBuffer { 1282 let scope = Span::call_site(); 1283 let cursor = tokens.begin(); 1284 let unexpected = Rc::new(Cell::new(Unexpected::None)); 1285 new_parse_buffer(scope, cursor, unexpected) 1286} 1287 1288impl<F, T> Parser for F 1289where 1290 F: FnOnce(ParseStream) -> Result<T>, 1291{ 1292 type Output = T; 1293 1294 fn parse2(self, tokens: TokenStream) -> Result<T> { 1295 let buf = TokenBuffer::new2(tokens); 1296 let state = tokens_to_parse_buffer(&buf); 1297 let node = self(&state)?; 1298 state.check_unexpected()?; 1299 if let Some((unexpected_span, delimiter)) = 1300 span_of_unexpected_ignoring_nones(state.cursor()) 1301 { 1302 Err(err_unexpected_token(unexpected_span, delimiter)) 1303 } else { 1304 Ok(node) 1305 } 1306 } 1307 1308 fn __parse_scoped(self, scope: Span, tokens: TokenStream) -> Result<Self::Output> { 1309 let buf = TokenBuffer::new2(tokens); 1310 let cursor = buf.begin(); 1311 let unexpected = Rc::new(Cell::new(Unexpected::None)); 1312 let state = new_parse_buffer(scope, cursor, unexpected); 1313 let node = self(&state)?; 1314 state.check_unexpected()?; 1315 if let Some((unexpected_span, delimiter)) = 1316 span_of_unexpected_ignoring_nones(state.cursor()) 1317 { 1318 Err(err_unexpected_token(unexpected_span, delimiter)) 1319 } else { 1320 Ok(node) 1321 } 1322 } 1323} 1324 1325pub(crate) fn parse_scoped<F: Parser>(f: F, scope: Span, tokens: TokenStream) -> Result<F::Output> { 1326 f.__parse_scoped(scope, tokens) 1327} 1328 1329fn err_unexpected_token(span: Span, delimiter: Delimiter) -> Error { 1330 let msg = match delimiter { 1331 Delimiter::Parenthesis => "unexpected token, expected `)`", 1332 Delimiter::Brace => "unexpected token, expected `}`", 1333 Delimiter::Bracket => "unexpected token, expected `]`", 1334 Delimiter::None => "unexpected token", 1335 }; 1336 Error::new(span, msg) 1337} 1338 1339/// An empty syntax tree node that consumes no tokens when parsed. 1340/// 1341/// This is useful for attribute macros that want to ensure they are not 1342/// provided any attribute args. 1343/// 1344/// ``` 1345/// # extern crate proc_macro; 1346/// # 1347/// use proc_macro::TokenStream; 1348/// use syn::parse_macro_input; 1349/// use syn::parse::Nothing; 1350/// 1351/// # const IGNORE: &str = stringify! { 1352/// #[proc_macro_attribute] 1353/// # }; 1354/// pub fn my_attr(args: TokenStream, input: TokenStream) -> TokenStream { 1355/// parse_macro_input!(args as Nothing); 1356/// 1357/// /* ... */ 1358/// # TokenStream::new() 1359/// } 1360/// ``` 1361/// 1362/// ```text 1363/// error: unexpected token 1364/// --> src/main.rs:3:19 1365/// | 1366/// 3 | #[my_attr(asdf)] 1367/// | ^^^^ 1368/// ``` 1369pub struct Nothing; 1370 1371impl Parse for Nothing { 1372 fn parse(_input: ParseStream) -> Result<Self> { 1373 Ok(Nothing) 1374 } 1375} 1376 1377#[cfg(feature = "printing")] 1378#[cfg_attr(docsrs, doc(cfg(feature = "printing")))] 1379impl ToTokens for Nothing { 1380 fn to_tokens(&self, tokens: &mut TokenStream) { 1381 let _ = tokens; 1382 } 1383} 1384 1385#[cfg(feature = "clone-impls")] 1386#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))] 1387impl Clone for Nothing { 1388 fn clone(&self) -> Self { 1389 *self 1390 } 1391} 1392 1393#[cfg(feature = "clone-impls")] 1394#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))] 1395impl Copy for Nothing {} 1396 1397#[cfg(feature = "extra-traits")] 1398#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))] 1399impl Debug for Nothing { 1400 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1401 f.write_str("Nothing") 1402 } 1403} 1404 1405#[cfg(feature = "extra-traits")] 1406#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))] 1407impl Eq for Nothing {} 1408 1409#[cfg(feature = "extra-traits")] 1410#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))] 1411impl PartialEq for Nothing { 1412 fn eq(&self, _other: &Self) -> bool { 1413 true 1414 } 1415} 1416 1417#[cfg(feature = "extra-traits")] 1418#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))] 1419impl Hash for Nothing { 1420 fn hash<H: Hasher>(&self, _state: &mut H) {} 1421}
~/
Read-only file preview.