Merging upstream version 1.68.2+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 56 insertions, 32 deletions

diff --git a/vendor/pest_derive/src/lib.rs b/vendor/pest_derive/src/lib.rs
index d980c6ae9..a908897f9 100644
--- a/vendor/pest_derive/src/lib.rs
+++ b/vendor/pest_derive/src/lib.rs
@@ -6,7 +6,12 @@
 // license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. All files in the project carrying such notice may not be copied,
 // modified, or distributed except according to those terms.
-
+#![doc(
+    html_root_url = "https://docs.rs/pest_derive",
+    html_logo_url = "https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/pest-parser/pest/master/pest-logo.svg"
+)]
+#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
 //! # pest. The Elegant Parser
 //!
 //! pest is a general purpose parser written in Rust with a focus on accessibility, correctness,
@@ -24,12 +29,16 @@
 //!
 //! * API reference on [docs.rs]
 //! * play with grammars and share them on our [fiddle]
-//! * leave feedback, ask questions, or greet us on [Gitter]
+//! * find previous common questions answered or ask questions on [GitHub Discussions]
+//! * leave feedback, ask questions, or greet us on [Gitter] or [Discord]
 //!
-//! [book]: https://pest-parser.github.io/book
+//! [book]: https://pest.rs/book
 //! [docs.rs]: https://docs.rs/pest
-//! [fiddle]: https://pest-parser.github.io/#editor
-//! [Gitter]: https://gitter.im/dragostis/pest
+//! [fiddle]: https://pest.rs/#editor
+//! [Gitter]: https://gitter.im/pest-parser/pest
+//! [Discord]: https://discord.gg/XEGACtWpT2
+//! [GitHub Discussions]: https://github.com/pest-parser/pest/discussions
+//!
 //!
 //! ## `.pest` files
 //!
@@ -143,12 +152,12 @@
 //!
 //! 1. Terminals
 //!
-//!     | Terminal   | Usage                                                          |
-//!     |------------|----------------------------------------------------------------|
-//!     | `"a"`      | matches the exact string `"a"`                                 |
-//!     | `^"a"`     | matches the exact string `"a"` case insensitively (ASCII only) |
-//!     | `'a'..'z'` | matches one character between `'a'` and `'z'`                  |
-//!     | `a`        | matches rule `a`                                               |
+//! | Terminal   | Usage                                                          |
+//! |------------|----------------------------------------------------------------|
+//! | `"a"`      | matches the exact string `"a"`                                 |
+//! | `^"a"`     | matches the exact string `"a"` case insensitively (ASCII only) |
+//! | `'a'..'z'` | matches one character between `'a'` and `'z'`                  |
+//! | `a`        | matches rule `a`                                               |
 //!
 //! Strings and characters follow
 //! [Rust's escape mechanisms](https://doc.rust-lang.org/reference/tokens.html#byte-escapes), while
@@ -157,23 +166,36 @@
 //!
 //! 2. Non-terminals
 //!
-//!     | Non-terminal          | Usage                                                      |
-//!     |-----------------------|------------------------------------------------------------|
-//!     | `(e)`                 | matches `e`                                                |
-//!     | `e1 ~ e2`             | matches the sequence `e1` `e2`                             |
-//!     | <code>e1 \| e2</code> | matches either `e1` or `e2`                                |
-//!     | `e*`                  | matches `e` zero or more times                             |
-//!     | `e+`                  | matches `e` one or more times                              |
-//!     | `e{n}`                | matches `e` exactly `n` times                              |
-//!     | `e{, n}`              | matches `e` at most `n` times                              |
-//!     | `e{n,} `              | matches `e` at least `n` times                             |
-//!     | `e{m, n}`             | matches `e` between `m` and `n` times inclusively          |
-//!     | `e?`                  | optionally matches `e`                                     |
-//!     | `&e`                  | matches `e` without making progress                        |
-//!     | `!e`                  | matches if `e` doesn't match without making progress       |
-//!     | `PUSH(e)`             | matches `e` and pushes it's captured string down the stack |
-//!
-//!     where `e`, `e1`, and `e2` are expressions.
+//! | Non-terminal          | Usage                                                      |
+//! |-----------------------|------------------------------------------------------------|
+//! | `(e)`                 | matches `e`                                                |
+//! | `e1 ~ e2`             | matches the sequence `e1` `e2`                             |
+//! | <code>e1 \| e2</code> | matches either `e1` or `e2`                                |
+//! | `e*`                  | matches `e` zero or more times                             |
+//! | `e+`                  | matches `e` one or more times                              |
+//! | `e{n}`                | matches `e` exactly `n` times                              |
+//! | `e{, n}`              | matches `e` at most `n` times                              |
+//! | `e{n,}`               | matches `e` at least `n` times                             |
+//! | `e{m, n}`             | matches `e` between `m` and `n` times inclusively          |
+//! | `e?`                  | optionally matches `e`                                     |
+//! | `&e`                  | matches `e` without making progress                        |
+//! | `!e`                  | matches if `e` doesn't match without making progress       |
+//! | `PUSH(e)`             | matches `e` and pushes it's captured string down the stack |
+//!
+//! where `e`, `e1`, and `e2` are expressions.
+//!
+//! Matching is greedy, without backtracking.  Note the difference in behavior for
+//! these two rules in matching identifiers that don't end in an underscore:
+//!
+//! ```ignore
+//! // input: ab_bb_b
+//!
+//! identifier = @{ "a" ~ ("b"|"_")* ~ "b" }
+//! // matches:      a     b_bb_b       nothing -> error!      
+//!
+//! identifier = @{ "a" ~ ("_"* ~ "b")* }
+//! // matches:      a     b, _bb, _b   in three repetitions
+//! ```
 //!
 //! Expressions can modify the stack only if they match the input. For example,
 //! if `e1` in the compound expression `e1 | e2` does not match the input, then
@@ -181,6 +203,10 @@
 //! `e1` did. Repetitions and optionals (`e*`, `e+`, `e{, n}`, `e{n,}`,
 //! `e{m,n}`, `e?`) can modify the stack each time `e` matches. The `!e` and `&e`
 //! expressions are a special case; they never modify the stack.
+//! Many languages have "keyword" tokens (e.g. if, for, while) as well as general
+//! tokens (e.g. identifier) that matches any word. In order to match a keyword,
+//! generally, you may need to restrict that is not immediately followed by another
+//! letter or digit (otherwise it would be matched as an identifier).
 //!
 //! ## Special rules
 //!
@@ -289,12 +315,10 @@
 //! * `ASCII` - matches a character from \x00..\x7f
 //! * `NEWLINE` - matches either "\n" or "\r\n" or "\r"
 
-#![doc(html_root_url = "https://docs.rs/pest_derive")]
-extern crate pest_generator;
-extern crate proc_macro;
-
 use proc_macro::TokenStream;
 
+/// The main method that's called by the proc macro
+/// (a wrapper around `pest_generator::derive_parser`)
 #[proc_macro_derive(Parser, attributes(grammar, grammar_inline))]
 pub fn derive_parser(input: TokenStream) -> TokenStream {
     pest_generator::derive_parser(input.into(), true).into()