Debian Codegraph @

.cargo/vendor/syn/src/lookahead.rs

raw
1 use crate::buffer::Cursor;
2 use crate::error::{self, Error};
3 use crate::sealed::lookahead::Sealed;
4 use crate::span::IntoSpans;
5 use crate::token::{CustomToken, Token};
6 use proc_macro2::{Delimiter, Span};
7 use std::cell::RefCell;
8 use std::fmt::{self, Display};
9
10 /// Support for checking the next token in a stream to decide how to parse.
11 ///
12 /// An important advantage over [`ParseStream::peek`] is that here we
13 /// automatically construct an appropriate error message based on the token
14 /// alternatives that get peeked. If you are producing your own error message,
15 /// go ahead and use `ParseStream::peek` instead.
16 ///
17 /// Use [`ParseStream::lookahead1`] to construct this object.
18 ///
19 /// [`ParseStream::peek`]: crate::parse::ParseBuffer::peek
20 /// [`ParseStream::lookahead1`]: crate::parse::ParseBuffer::lookahead1
21 ///
22 /// Consuming tokens from the source stream after constructing a lookahead
23 /// object does not also advance the lookahead object.
24 ///
25 /// # Example
26 ///
27 /// ```
28 /// use syn::{ConstParam, Ident, Lifetime, LifetimeParam, Result, Token, TypeParam};
29 /// use syn::parse::{Parse, ParseStream};
30 ///
31 /// // A generic parameter, a single one of the comma-separated elements inside
32 /// // angle brackets in:
33 /// //
34 /// // fn f<T: Clone, 'a, 'b: 'a, const N: usize>() { ... }
35 /// //
36 /// // On invalid input, lookahead gives us a reasonable error message.
37 /// //
38 /// // error: expected one of: identifier, lifetime, `const`
39 /// // |
40 /// // 5 | fn f<!Sized>() {}
41 /// // | ^
42 /// enum GenericParam {
43 /// Type(TypeParam),
44 /// Lifetime(LifetimeParam),
45 /// Const(ConstParam),
46 /// }
47 ///
48 /// impl Parse for GenericParam {
49 /// fn parse(input: ParseStream) -> Result<Self> {
50 /// let lookahead = input.lookahead1();
51 /// if lookahead.peek(Ident) {
52 /// input.parse().map(GenericParam::Type)
53 /// } else if lookahead.peek(Lifetime) {
54 /// input.parse().map(GenericParam::Lifetime)
55 /// } else if lookahead.peek(Token![const]) {
56 /// input.parse().map(GenericParam::Const)
57 /// } else {
58 /// Err(lookahead.error())
59 /// }
60 /// }
61 /// }
62 /// ```
63 pub struct Lookahead1<'a> {
64 scope: Span,
65 cursor: Cursor<'a>,
66 comparisons: RefCell<Vec<&'static str>>,
67 }
68
69 pub(crate) fn new(scope: Span, cursor: Cursor) -> Lookahead1 {
70 Lookahead1 {
71 scope,
72 cursor,
73 comparisons: RefCell::new(Vec::new()),
74 }
75 }
76
77 fn peek_impl(
78 lookahead: &Lookahead1,
79 peek: fn(Cursor) -> bool,
80 display: fn() -> &'static str,
81 ) -> bool {
82 if peek(lookahead.cursor) {
83 return true;
84 }
85 lookahead.comparisons.borrow_mut().push(display());
86 false
87 }
88
89 impl<'a> Lookahead1<'a> {
90 /// Looks at the next token in the parse stream to determine whether it
91 /// matches the requested type of token.
92 ///
93 /// # Syntax
94 ///
95 /// Note that this method does not use turbofish syntax. Pass the peek type
96 /// inside of parentheses.
97 ///
98 /// - `input.peek(Token![struct])`
99 /// - `input.peek(Token![==])`
100 /// - `input.peek(Ident)`&emsp;*(does not accept keywords)*
101 /// - `input.peek(Ident::peek_any)`
102 /// - `input.peek(Lifetime)`
103 /// - `input.peek(token::Brace)`
104 pub fn peek<T: Peek>(&self, token: T) -> bool {
105 let _ = token;
106 peek_impl(self, T::Token::peek, T::Token::display)
107 }
108
109 /// Triggers an error at the current position of the parse stream.
110 ///
111 /// The error message will identify all of the expected token types that
112 /// have been peeked against this lookahead instance.
113 pub fn error(self) -> Error {
114 let mut comparisons = self.comparisons.into_inner();
115 comparisons.retain_mut(|display| {
116 if *display == "`)`" {
117 *display = match self.cursor.scope_delimiter() {
118 Delimiter::Parenthesis => "`)`",
119 Delimiter::Brace => "`}`",
120 Delimiter::Bracket => "`]`",
121 Delimiter::None => return false,
122 }
123 }
124 true
125 });
126 match comparisons.len() {
127 0 => {
128 if self.cursor.eof() {
129 Error::new(self.scope, "unexpected end of input")
130 } else {
131 Error::new(self.cursor.span(), "unexpected token")
132 }
133 }
134 1 => {
135 let message = format!("expected {}", comparisons[0]);
136 error::new_at(self.scope, self.cursor, message)
137 }
138 2 => {
139 let message = format!("expected {} or {}", comparisons[0], comparisons[1]);
140 error::new_at(self.scope, self.cursor, message)
141 }
142 _ => {
143 let message = format!("expected one of: {}", CommaSeparated(&comparisons));
144 error::new_at(self.scope, self.cursor, message)
145 }
146 }
147 }
148 }
149
150 struct CommaSeparated<'a>(&'a [&'a str]);
151
152 impl<'a> Display for CommaSeparated<'a> {
153 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
154 let mut first = true;
155 for &s in self.0 {
156 if !first {
157 f.write_str(", ")?;
158 }
159 f.write_str(s)?;
160 first = false;
161 }
162 Ok(())
163 }
164 }
165
166 /// Types that can be parsed by looking at just one token.
167 ///
168 /// Use [`ParseStream::peek`] to peek one of these types in a parse stream
169 /// without consuming it from the stream.
170 ///
171 /// This trait is sealed and cannot be implemented for types outside of Syn.
172 ///
173 /// [`ParseStream::peek`]: crate::parse::ParseBuffer::peek
174 pub trait Peek: Sealed {
175 // Not public API.
176 #[doc(hidden)]
177 type Token: Token;
178 }
179
180 /// Pseudo-token used for peeking the end of a parse stream.
181 ///
182 /// This type is only useful as an argument to one of the following functions:
183 ///
184 /// - [`ParseStream::peek`][crate::parse::ParseBuffer::peek]
185 /// - [`ParseStream::peek2`][crate::parse::ParseBuffer::peek2]
186 /// - [`ParseStream::peek3`][crate::parse::ParseBuffer::peek3]
187 /// - [`Lookahead1::peek`]
188 ///
189 /// The peek will return `true` if there are no remaining tokens after that
190 /// point in the parse stream.
191 ///
192 /// # Example
193 ///
194 /// Suppose we are parsing attributes containing core::fmt inspired formatting
195 /// arguments:
196 ///
197 /// - `#[fmt("simple example")]`
198 /// - `#[fmt("interpolation e{}ample", self.x)]`
199 /// - `#[fmt("interpolation e{x}ample")]`
200 ///
201 /// and we want to recognize the cases where no interpolation occurs so that
202 /// more efficient code can be generated.
203 ///
204 /// The following implementation uses `input.peek(Token![,]) &&
205 /// input.peek2(End)` to recognize the case of a trailing comma without
206 /// consuming the comma from the parse stream, because if it isn't a trailing
207 /// comma, that same comma needs to be parsed as part of `args`.
208 ///
209 /// ```
210 /// use proc_macro2::TokenStream;
211 /// use quote::quote;
212 /// use syn::parse::{End, Parse, ParseStream, Result};
213 /// use syn::{parse_quote, Attribute, LitStr, Token};
214 ///
215 /// struct FormatArgs {
216 /// template: LitStr, // "...{}..."
217 /// args: TokenStream, // , self.x
218 /// }
219 ///
220 /// impl Parse for FormatArgs {
221 /// fn parse(input: ParseStream) -> Result<Self> {
222 /// let template: LitStr = input.parse()?;
223 ///
224 /// let args = if input.is_empty()
225 /// || input.peek(Token![,]) && input.peek2(End)
226 /// {
227 /// input.parse::<Option<Token![,]>>()?;
228 /// TokenStream::new()
229 /// } else {
230 /// input.parse()?
231 /// };
232 ///
233 /// Ok(FormatArgs {
234 /// template,
235 /// args,
236 /// })
237 /// }
238 /// }
239 ///
240 /// fn main() -> Result<()> {
241 /// let attrs: Vec<Attribute> = parse_quote! {
242 /// #[fmt("simple example")]
243 /// #[fmt("interpolation e{}ample", self.x)]
244 /// #[fmt("interpolation e{x}ample")]
245 /// };
246 ///
247 /// for attr in &attrs {
248 /// let FormatArgs { template, args } = attr.parse_args()?;
249 /// let requires_fmt_machinery =
250 /// !args.is_empty() || template.value().contains(['{', '}']);
251 /// let out = if requires_fmt_machinery {
252 /// quote! {
253 /// ::core::write!(__formatter, #template #args)
254 /// }
255 /// } else {
256 /// quote! {
257 /// __formatter.write_str(#template)
258 /// }
259 /// };
260 /// println!("{}", out);
261 /// }
262 /// Ok(())
263 /// }
264 /// ```
265 ///
266 /// Implementing this parsing logic without `peek2(End)` is more clumsy because
267 /// we'd need a parse stream actually advanced past the comma before being able
268 /// to find out whether there is anything after it. It would look something
269 /// like:
270 ///
271 /// ```
272 /// # use proc_macro2::TokenStream;
273 /// # use syn::parse::{ParseStream, Result};
274 /// # use syn::Token;
275 /// #
276 /// # fn parse(input: ParseStream) -> Result<()> {
277 /// use syn::parse::discouraged::Speculative as _;
278 ///
279 /// let ahead = input.fork();
280 /// ahead.parse::<Option<Token![,]>>()?;
281 /// let args = if ahead.is_empty() {
282 /// input.advance_to(&ahead);
283 /// TokenStream::new()
284 /// } else {
285 /// input.parse()?
286 /// };
287 /// # Ok(())
288 /// # }
289 /// ```
290 ///
291 /// or:
292 ///
293 /// ```
294 /// # use proc_macro2::TokenStream;
295 /// # use syn::parse::{ParseStream, Result};
296 /// # use syn::Token;
297 /// #
298 /// # fn parse(input: ParseStream) -> Result<()> {
299 /// use quote::ToTokens as _;
300 ///
301 /// let comma: Option<Token![,]> = input.parse()?;
302 /// let mut args = TokenStream::new();
303 /// if !input.is_empty() {
304 /// comma.to_tokens(&mut args);
305 /// input.parse::<TokenStream>()?.to_tokens(&mut args);
306 /// }
307 /// # Ok(())
308 /// # }
309 /// ```
310 pub struct End;
311
312 impl Copy for End {}
313
314 impl Clone for End {
315 fn clone(&self) -> Self {
316 *self
317 }
318 }
319
320 impl Peek for End {
321 type Token = Self;
322 }
323
324 impl CustomToken for End {
325 fn peek(cursor: Cursor) -> bool {
326 cursor.eof()
327 }
328
329 fn display() -> &'static str {
330 "`)`" // Lookahead1 error message will fill in the expected close delimiter
331 }
332 }
333
334 impl<F: Copy + FnOnce(TokenMarker) -> T, T: Token> Peek for F {
335 type Token = T;
336 }
337
338 pub enum TokenMarker {}
339
340 impl<S> IntoSpans<S> for TokenMarker {
341 fn into_spans(self) -> S {
342 match self {}
343 }
344 }
345
346 impl<F: Copy + FnOnce(TokenMarker) -> T, T: Token> Sealed for F {}
347
348 impl Sealed for End {}