1 files changed, 165 insertions, 0 deletions
diff --git a/vendor/winnow-0.4.7/examples/string/parser.rs b/vendor/winnow-0.4.7/examples/string/parser.rs
new file mode 100644
index 000000000..dcd87f272
--- /dev/null
+++ b/vendor/winnow-0.4.7/examples/string/parser.rs
@@ -0,0 +1,165 @@
+//! This example shows an example of how to parse an escaped string. The
+//! rules for the string are similar to JSON and rust. A string is:
+//!
+//! - Enclosed by double quotes
+//! - Can contain any raw unescaped code point besides \ and "
+//! - Matches the following escape sequences: \b, \f, \n, \r, \t, \", \\, \/
+//! - Matches code points like Rust: \u{XXXX}, where XXXX can be up to 6
+//!   hex characters
+//! - an escape followed by whitespace consumes all whitespace between the
+//!   escape and the next non-whitespace character
+
+use winnow::ascii::multispace1;
+use winnow::combinator::alt;
+use winnow::combinator::fold_repeat;
+use winnow::combinator::{delimited, preceded};
+use winnow::error::{FromExternalError, ParseError};
+use winnow::prelude::*;
+use winnow::token::{take_till1, take_while};
+
+/// Parse a string. Use a loop of `parse_fragment` and push all of the fragments
+/// into an output string.
+pub fn parse_string<'a, E>(input: &'a str) -> IResult<&'a str, String, E>
+where
+    E: ParseError<&'a str> + FromExternalError<&'a str, std::num::ParseIntError>,
+{
+    // fold_repeat is the equivalent of iterator::fold. It runs a parser in a loop,
+    // and for each output value, calls a folding function on each output value.
+    let build_string = fold_repeat(
+        0..,
+        // Our parser function – parses a single string fragment
+        parse_fragment,
+        // Our init value, an empty string
+        String::new,
+        // Our folding function. For each fragment, append the fragment to the
+        // string.
+        |mut string, fragment| {
+            match fragment {
+                StringFragment::Literal(s) => string.push_str(s),
+                StringFragment::EscapedChar(c) => string.push(c),
+                StringFragment::EscapedWS => {}
+            }
+            string
+        },
+    );
+
+    // Finally, parse the string. Note that, if `build_string` could accept a raw
+    // " character, the closing delimiter " would never match. When using
+    // `delimited` with a looping parser (like fold_repeat), be sure that the
+    // loop won't accidentally match your closing delimiter!
+    delimited('"', build_string, '"').parse_next(input)
+}
+
+/// A string fragment contains a fragment of a string being parsed: either
+/// a non-empty Literal (a series of non-escaped characters), a single
+/// parsed escaped character, or a block of escaped whitespace.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum StringFragment<'a> {
+    Literal(&'a str),
+    EscapedChar(char),
+    EscapedWS,
+}
+
+/// Combine `parse_literal`, `parse_escaped_whitespace`, and `parse_escaped_char`
+/// into a `StringFragment`.
+fn parse_fragment<'a, E>(input: &'a str) -> IResult<&'a str, StringFragment<'a>, E>
+where
+    E: ParseError<&'a str> + FromExternalError<&'a str, std::num::ParseIntError>,
+{
+    alt((
+        // The `map` combinator runs a parser, then applies a function to the output
+        // of that parser.
+        parse_literal.map(StringFragment::Literal),
+        parse_escaped_char.map(StringFragment::EscapedChar),
+        parse_escaped_whitespace.value(StringFragment::EscapedWS),
+    ))
+    .parse_next(input)
+}
+
+/// Parse a non-empty block of text that doesn't include \ or "
+fn parse_literal<'a, E: ParseError<&'a str>>(input: &'a str) -> IResult<&'a str, &'a str, E> {
+    // `take_till1` parses a string of 0 or more characters that aren't one of the
+    // given characters.
+    let not_quote_slash = take_till1("\"\\");
+
+    // `verify` runs a parser, then runs a verification function on the output of
+    // the parser. The verification function accepts the output only if it
+    // returns true. In this case, we want to ensure that the output of take_till1
+    // is non-empty.
+    not_quote_slash
+        .verify(|s: &str| !s.is_empty())
+        .parse_next(input)
+}
+
+// parser combinators are constructed from the bottom up:
+// first we write parsers for the smallest elements (escaped characters),
+// then combine them into larger parsers.
+
+/// Parse an escaped character: \n, \t, \r, \u{00AC}, etc.
+fn parse_escaped_char<'a, E>(input: &'a str) -> IResult<&'a str, char, E>
+where
+    E: ParseError<&'a str> + FromExternalError<&'a str, std::num::ParseIntError>,
+{
+    preceded(
+        '\\',
+        // `alt` tries each parser in sequence, returning the result of
+        // the first successful match
+        alt((
+            parse_unicode,
+            // The `value` parser returns a fixed value (the first argument) if its
+            // parser (the second argument) succeeds. In these cases, it looks for
+            // the marker characters (n, r, t, etc) and returns the matching
+            // character (\n, \r, \t, etc).
+            'n'.value('\n'),
+            'r'.value('\r'),
+            't'.value('\t'),
+            'b'.value('\u{08}'),
+            'f'.value('\u{0C}'),
+            '\\'.value('\\'),
+            '/'.value('/'),
+            '"'.value('"'),
+        )),
+    )
+    .parse_next(input)
+}
+
+/// Parse a unicode sequence, of the form u{XXXX}, where XXXX is 1 to 6
+/// hexadecimal numerals. We will combine this later with `parse_escaped_char`
+/// to parse sequences like \u{00AC}.
+fn parse_unicode<'a, E>(input: &'a str) -> IResult<&'a str, char, E>
+where
+    E: ParseError<&'a str> + FromExternalError<&'a str, std::num::ParseIntError>,
+{
+    // `take_while` parses between `m` and `n` bytes (inclusive) that match
+    // a predicate. `parse_hex` here parses between 1 and 6 hexadecimal numerals.
+    let parse_hex = take_while(1..=6, |c: char| c.is_ascii_hexdigit());
+
+    // `preceded` takes a prefix parser, and if it succeeds, returns the result
+    // of the body parser. In this case, it parses u{XXXX}.
+    let parse_delimited_hex = preceded(
+        'u',
+        // `delimited` is like `preceded`, but it parses both a prefix and a suffix.
+        // It returns the result of the middle parser. In this case, it parses
+        // {XXXX}, where XXXX is 1 to 6 hex numerals, and returns XXXX
+        delimited('{', parse_hex, '}'),
+    );
+
+    // `try_map` takes the result of a parser and applies a function that returns
+    // a Result. In this case we take the hex bytes from parse_hex and attempt to
+    // convert them to a u32.
+    let parse_u32 = parse_delimited_hex.try_map(move |hex| u32::from_str_radix(hex, 16));
+
+    // verify_map is like try_map, but it takes an Option instead of a Result. If
+    // the function returns None, verify_map returns an error. In this case, because
+    // not all u32 values are valid unicode code points, we have to fallibly
+    // convert to char with from_u32.
+    parse_u32.verify_map(std::char::from_u32).parse_next(input)
+}
+
+/// Parse a backslash, followed by any amount of whitespace. This is used later
+/// to discard any escaped whitespace.
+fn parse_escaped_whitespace<'a, E: ParseError<&'a str>>(
+    input: &'a str,
+) -> IResult<&'a str, &'a str, E> {
+    preceded('\\', multispace1).parse_next(input)
+}