      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171

    //! Extensions to the parsing API with niche applicability.

    use super::*;

    /// Extensions to the `ParseStream` API to support speculative parsing.
    pub trait Speculative {
        /// Advance this parse stream to the position of a forked parse stream.
        ///
        /// This is the opposite operation to [`ParseStream::fork`]. You can fork a
        /// parse stream, perform some speculative parsing, then join the original
        /// stream to the fork to "commit" the parsing from the fork to the main
        /// stream.
        ///
        /// If you can avoid doing this, you should, as it limits the ability to
        /// generate useful errors. That said, it is often the only way to parse
        /// syntax of the form `A* B*` for arbitrary syntax `A` and `B`. The problem
        /// is that when the fork fails to parse an `A`, it's impossible to tell
        /// whether that was because of a syntax error and the user meant to provide
        /// an `A`, or that the `A`s are finished and its time to start parsing
        /// `B`s. Use with care.
        ///
        /// Also note that if `A` is a subset of `B`, `A* B*` can be parsed by
        /// parsing `B*` and removing the leading members of `A` from the
        /// repetition, bypassing the need to involve the downsides associated with
        /// speculative parsing.
        ///
        /// [`ParseStream::fork`]: ../struct.ParseBuffer.html#method.fork
        ///
        /// # Example
        ///
        /// There has been chatter about the possibility of making the colons in the
        /// turbofish syntax like `path::to::<T>` no longer required by accepting
        /// `path::to<T>` in expression position. Specifically, according to [RFC
        /// 2544], [`PathSegment`] parsing should always try to consume a following
        /// `<` token as the start of generic arguments, and reset to the `<` if
        /// that fails (e.g. the token is acting as a less-than operator).
        ///
        /// This is the exact kind of parsing behavior which requires the "fork,
        /// try, commit" behavior that [`ParseStream::fork`] discourages. With
        /// `advance_to`, we can avoid having to parse the speculatively parsed
        /// content a second time.
        ///
        /// This change in behavior can be implemented in syn by replacing just the
        /// `Parse` implementation for `PathSegment`:
        ///
        /// ```edition2018
        /// # use syn::ext::IdentExt;
        /// use syn::parse::discouraged::Speculative;
        /// # use syn::parse::{Parse, ParseStream};
        /// # use syn::{Ident, PathArguments, Result, Token};
        ///
        /// pub struct PathSegment {
        ///     pub ident: Ident,
        ///     pub arguments: PathArguments,
        /// }
        /// #
        /// # impl<T> From<T> for PathSegment
        /// # where
        /// #     T: Into<Ident>,
        /// # {
        /// #     fn from(ident: T) -> Self {
        /// #         PathSegment {
        /// #             ident: ident.into(),
        /// #             arguments: PathArguments::None,
        /// #         }
        /// #     }
        /// # }
        ///
        /// impl Parse for PathSegment {
        ///     fn parse(input: ParseStream) -> Result<Self> {
        ///         if input.peek(Token![super])
        ///             || input.peek(Token![self])
        ///             || input.peek(Token![Self])
        ///             || input.peek(Token![crate])
        ///             || input.peek(Token![extern])
        ///         {
        ///             let ident = input.call(Ident::parse_any)?;
        ///             return Ok(PathSegment::from(ident));
        ///         }
        ///
        ///         let ident = input.parse()?;
        ///         if input.peek(Token![::]) && input.peek3(Token![<]) {
        ///             return Ok(PathSegment {
        ///                 ident: ident,
        ///                 arguments: PathArguments::AngleBracketed(input.parse()?),
        ///             });
        ///         }
        ///         if input.peek(Token![<]) && !input.peek(Token![<=]) {
        ///             let fork = input.fork();
        ///             if let Ok(arguments) = fork.parse() {
        ///                 input.advance_to(&fork);
        ///                 return Ok(PathSegment {
        ///                     ident: ident,
        ///                     arguments: PathArguments::AngleBracketed(arguments),
        ///                 });
        ///             }
        ///         }
        ///         Ok(PathSegment::from(ident))
        ///     }
        /// }
        ///
        /// # syn::parse_str::<PathSegment>("a<b,c>").unwrap();
        /// ```
        ///
        /// # Drawbacks
        ///
        /// The main drawback of this style of speculative parsing is in error
        /// presentation. Even if the lookahead is the "correct" parse, the error
        /// that is shown is that of the "fallback" parse. To use the same example
        /// as the turbofish above, take the following unfinished "turbofish":
        ///
        /// ```text
        /// let _ = f<&'a fn(), for<'a> serde::>();
        /// ```
        ///
        /// If this is parsed as generic arguments, we can provide the error message
        ///
        /// ```text
        /// error: expected identifier
        ///  --> src.rs:L:C
        ///   |
        /// L | let _ = f<&'a fn(), for<'a> serde::>();
        ///   |                                    ^
        /// ```
        ///
        /// but if parsed using the above speculative parsing, it falls back to
        /// assuming that the `<` is a less-than when it fails to parse the generic
        /// arguments, and tries to interpret the `&'a` as the start of a labelled
        /// loop, resulting in the much less helpful error
        ///
        /// ```text
        /// error: expected `:`
        ///  --> src.rs:L:C
        ///   |
        /// L | let _ = f<&'a fn(), for<'a> serde::>();
        ///   |               ^^
        /// ```
        ///
        /// This can be mitigated with various heuristics (two examples: show both
        /// forks' parse errors, or show the one that consumed more tokens), but
        /// when you can control the grammar, sticking to something that can be
        /// parsed LL(3) and without the LL(*) speculative parsing this makes
        /// possible, displaying reasonable errors becomes much more simple.
        ///
        /// [RFC 2544]: https://github.com/rust-lang/rfcs/pull/2544
        /// [`PathSegment`]: ../../struct.PathSegment.html
        ///
        /// # Performance
        ///
        /// This method performs a cheap fixed amount of work that does not depend
        /// on how far apart the two streams are positioned.
        ///
        /// # Panics
        ///
        /// The forked stream in the argument of `advance_to` must have been
        /// obtained by forking `self`. Attempting to advance to any other stream
        /// will cause a panic.
        fn advance_to(&self, fork: &Self);
    }

    impl<'a> Speculative for ParseBuffer<'a> {
        fn advance_to(&self, fork: &Self) {
            if !private::same_scope(self.cursor(), fork.cursor()) {
                panic!("Fork was not derived from the advancing parse stream");
            }

            // See comment on `cell` in the struct definition.
            self.cell
                .set(unsafe { mem::transmute::<Cursor, Cursor<'static>>(fork.cursor()) })
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)