feat: add display UI with splash screen, dashboard, and RSSI sparkline
Implement full SSD1306 OLED display support: - Splash screen on boot (1.5s) with project name, version, board - Dashboard showing radio state, config, counters, RSSI/SNR - RSSI history sparkline (64-sample ring buffer, 2px-wide bars) - DisplayOn/DisplayOff host commands routed via dedicated channel - Pure render functions against generic DrawTarget (no hardware coupling) - Display on/off control bypasses radio task entirely Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
17624 files changed
+4564928
-38
No files matched your search
+38
@@ -0,0 +1,38 @@
|
||||
//! # Chapter 0: Introduction
|
||||
//!
|
||||
//! This tutorial assumes that you are:
|
||||
//! - Already familiar with Rust
|
||||
//! - Using `winnow` for the first time
|
||||
//!
|
||||
//! The focus will be on parsing in-memory strings (`&str`). Once done, you might want to check the
|
||||
//! [Special Topics][_topic] for more specialized topics or examples.
|
||||
//!
|
||||
//! ## About
|
||||
//!
|
||||
//! `winnow` is a parser-combinator library. In other words, it gives you tools to define:
|
||||
//! - "parsers", or functions that take an input and give back an output
|
||||
//! - "combinators", or functions that take parsers and _combine_ them together!
|
||||
//!
|
||||
//! While "combinator" might be an unfamiliar word, you are likely using them in your rust code
|
||||
//! today, like with the [`Iterator`] trait:
|
||||
//! ```rust
|
||||
//! let data = vec![1, 2, 3, 4, 5];
|
||||
//! let even_count = data.iter()
|
||||
//! .copied() // combinator
|
||||
//! .filter(|d| d % 2 == 0) // combinator
|
||||
//! .count(); // combinator
|
||||
//! ```
|
||||
//!
|
||||
//! Parser combinators are great because:
|
||||
//!
|
||||
//! - Individual parser functions are small, focused on one thing, ignoring the rest
|
||||
//! - You can write tests focused on individual parsers (unit tests and property-based tests)
|
||||
//! in addition to testing the top-level parser as a whole.
|
||||
//! - Top-level parsing code looks close to the grammar you would have written
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::_topic;
|
||||
use std::iter::Iterator;
|
||||
|
||||
pub use super::chapter_1 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
//! # Chapter 1: The Winnow Way
|
||||
//!
|
||||
//! First of all, we need to understand the way that winnow thinks about parsing.
|
||||
//! As discussed in the introduction, winnow lets us compose more complex parsers from more simple
|
||||
//! ones (using "combinators").
|
||||
//!
|
||||
//! Let's discuss what a "parser" actually does. A parser takes an input and advances it until it returns
|
||||
//! a result, where:
|
||||
//! - `Ok` indicates the parser successfully found what it was looking for; or
|
||||
//! - `Err` indicates the parser could not find what it was looking for.
|
||||
//!
|
||||
//! Parsers do more than just return a binary "success"/"failure" code.
|
||||
//! - On success, the parser will return the processed data. The input will be advanced to the end of
|
||||
//! what was processed, pointing to what will be parsed next.
|
||||
//! - If the parser failed, then there are multiple errors that could be returned.
|
||||
//! We'll explore this further in [`chapter_7`].
|
||||
//!
|
||||
//! ```text
|
||||
//! ┌─► Ok(what matched the parser)
|
||||
//! ┌────────┐ │
|
||||
//! my input───►│a parser├──►either──┤
|
||||
//! └────────┘ └─► Err(...)
|
||||
//! ```
|
||||
//!
|
||||
//!
|
||||
//! To represent this model of the world, winnow uses the [`Result<O>`] type.
|
||||
//! The `Ok` variant has `output: O`;
|
||||
//! whereas the `Err` variant stores an error.
|
||||
//!
|
||||
//! You can import that from:
|
||||
//!
|
||||
//! ```rust
|
||||
//! use winnow::Result;
|
||||
//! ```
|
||||
//!
|
||||
//! To combine parsers, we need a common way to refer to them which is where the [`Parser<I, O, E>`]
|
||||
//! trait comes in with [`Parser::parse_next`] being the primary way to drive
|
||||
//! parsing forward.
|
||||
//! In [`chapter_6`], we'll cover how to integrate these into your application, particularly with
|
||||
//! [`Parser::parse`].
|
||||
//!
|
||||
//! You'll note that `I` and `O` are parameterized -- while most of the examples in this book
|
||||
//! will be with `&str` (i.e. parsing a string); [they do not have to be strings][stream]; nor do they
|
||||
//! have to be the same type (consider the simple example where `I = &str`, and `O = u64` -- this
|
||||
//! parses a string into an unsigned integer.)
|
||||
//!
|
||||
//! # Let's write our first parser!
|
||||
//!
|
||||
//! The simplest parser we can write is one which successfully does nothing.
|
||||
//!
|
||||
//! To make it easier to implement a [`Parser`], the trait is implemented for
|
||||
//! functions of the form `Fn(&mut I) -> Result<O>`.
|
||||
//!
|
||||
//! This parser function should take in a `&str`:
|
||||
//!
|
||||
//! - Since it is supposed to succeed, we know it will return the `Ok` variant.
|
||||
//! - Since it does nothing to our input, the input will be left where it started.
|
||||
//! - Since it doesn't parse anything, it also should just return an empty string.
|
||||
//!
|
||||
//! ```rust
|
||||
//! use winnow::Result;
|
||||
//! use winnow::Parser;
|
||||
//!
|
||||
//! pub fn do_nothing_parser<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! Ok("")
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let output = do_nothing_parser.parse_next(&mut input).unwrap();
|
||||
//! // Same as:
|
||||
//! // let output = do_nothing_parser(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, "0x1a2b Hello");
|
||||
//! assert_eq!(output, "");
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use super::chapter_6;
|
||||
use super::chapter_7;
|
||||
use crate::Parser;
|
||||
use crate::_topic::stream;
|
||||
|
||||
pub use super::chapter_0 as previous;
|
||||
pub use super::chapter_2 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+301
@@ -0,0 +1,301 @@
|
||||
//! # Chapter 2: Tokens and Tags
|
||||
//!
|
||||
//! The simplest *useful* parser you can write is one which matches tokens.
|
||||
//! In our case, tokens are `char`.
|
||||
//!
|
||||
//! ## Tokens
|
||||
//!
|
||||
//! [`Stream`] provides some core operations to help with parsing. For example, to process a
|
||||
//! single token, you can do:
|
||||
//! ```rust
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::stream::Stream;
|
||||
//! use winnow::error::ParserError;
|
||||
//!
|
||||
//! fn parse_prefix(input: &mut &str) -> Result<char> {
|
||||
//! let c = input.next_token().ok_or_else(|| {
|
||||
//! ParserError::from_input(input)
|
||||
//! })?;
|
||||
//! if c != '0' {
|
||||
//! return Err(ParserError::from_input(input));
|
||||
//! }
|
||||
//! Ok(c)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, "x1a2b Hello");
|
||||
//! assert_eq!(output, '0');
|
||||
//!
|
||||
//! assert!(parse_prefix.parse_next(&mut "d").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! This extraction of a token is encapsulated in the [`any`] parser:
|
||||
//! ```rust
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::error::ParserError;
|
||||
//! use winnow::Parser;
|
||||
//! use winnow::token::any;
|
||||
//!
|
||||
//! fn parse_prefix(input: &mut &str) -> Result<char> {
|
||||
//! let c = any
|
||||
//! .parse_next(input)?;
|
||||
//! if c != '0' {
|
||||
//! return Err(ParserError::from_input(input));
|
||||
//! }
|
||||
//! Ok(c)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, "x1a2b Hello");
|
||||
//! # assert_eq!(output, '0');
|
||||
//! #
|
||||
//! # assert!(parse_prefix.parse_next(&mut "d").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! Using the higher level [`any`] parser opens `parse_prefix` to the helpers on the [`Parser`] trait,
|
||||
//! like [`Parser::verify`] which fails a parse if a condition isn't met, like our check above:
|
||||
//! ```rust
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::Parser;
|
||||
//! use winnow::token::any;
|
||||
//!
|
||||
//! fn parse_prefix(input: &mut &str) -> Result<char> {
|
||||
//! let c = any
|
||||
//! .verify(|c| *c == '0')
|
||||
//! .parse_next(input)?;
|
||||
//! Ok(c)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, "x1a2b Hello");
|
||||
//! # assert_eq!(output, '0');
|
||||
//! #
|
||||
//! # assert!(parse_prefix.parse_next(&mut "d").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! Matching a single token literal is common enough that [`Parser`] is implemented for
|
||||
//! the `char` type, encapsulating both [`any`] and [`Parser::verify`]:
|
||||
//! ```rust
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::Parser;
|
||||
//!
|
||||
//! fn parse_prefix(input: &mut &str) -> Result<char> {
|
||||
//! let c = '0'.parse_next(input)?;
|
||||
//! Ok(c)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, "x1a2b Hello");
|
||||
//! # assert_eq!(output, '0');
|
||||
//! #
|
||||
//! # assert!(parse_prefix.parse_next(&mut "d").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Tags
|
||||
//!
|
||||
//! [`Stream`] also supports processing slices of tokens:
|
||||
//! ```rust
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::stream::Stream;
|
||||
//! use winnow::error::ParserError;
|
||||
//!
|
||||
//! fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! let expected = "0x";
|
||||
//! if input.len() < expected.len() {
|
||||
//! return Err(ParserError::from_input(input));
|
||||
//! }
|
||||
//! let actual = input.next_slice(expected.len());
|
||||
//! if actual != expected {
|
||||
//! return Err(ParserError::from_input(input));
|
||||
//! }
|
||||
//! Ok(actual)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! assert_eq!(input, "1a2b Hello");
|
||||
//! assert_eq!(output, "0x");
|
||||
//!
|
||||
//! assert!(parse_prefix.parse_next(&mut "0o123").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! Matching the input position against a string literal is encapsulated in the [`literal`] parser:
|
||||
//! ```rust
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::Parser;
|
||||
//! use winnow::token::literal;
|
||||
//!
|
||||
//! fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! let expected = "0x";
|
||||
//! let actual = literal(expected).parse_next(input)?;
|
||||
//! Ok(actual)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! # assert_eq!(input, "1a2b Hello");
|
||||
//! # assert_eq!(output, "0x");
|
||||
//! #
|
||||
//! # assert!(parse_prefix.parse_next(&mut "0o123").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! Like for a single token, matching a string literal is common enough that [`Parser`] is implemented for the `&str` type:
|
||||
//! ```rust
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::Parser;
|
||||
//!
|
||||
//! fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! let actual = "0x".parse_next(input)?;
|
||||
//! Ok(actual)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! # assert_eq!(input, "1a2b Hello");
|
||||
//! # assert_eq!(output, "0x");
|
||||
//! #
|
||||
//! # assert!(parse_prefix.parse_next(&mut "0o123").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! See [`token`] for additional individual and token-slice parsers.
|
||||
//!
|
||||
//! ## Character Classes
|
||||
//!
|
||||
//! Selecting a single `char` or a [`literal`] is fairly limited. Sometimes, you will want to select one of several
|
||||
//! `chars` of a specific class, like digits. For this, we use the [`one_of`] parser:
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::token::one_of;
|
||||
//!
|
||||
//! fn parse_digits(input: &mut &str) -> Result<char> {
|
||||
//! one_of(('0'..='9', 'a'..='f', 'A'..='F')).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "1a2b Hello";
|
||||
//!
|
||||
//! let output = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! assert_eq!(input, "a2b Hello");
|
||||
//! assert_eq!(output, '1');
|
||||
//!
|
||||
//! assert!(parse_digits.parse_next(&mut "Z").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! > **Aside:** [`one_of`] might look straightforward, a function returning a value that implements `Parser`.
|
||||
//! > Let's look at it more closely as its used above (resolving all generic parameters):
|
||||
//! > ```rust
|
||||
//! > # use winnow::prelude::*;
|
||||
//! > # use winnow::error::ContextError;
|
||||
//! > pub fn one_of<'i>(
|
||||
//! > list: &'static [char]
|
||||
//! > ) -> impl Parser<&'i str, char, ContextError> {
|
||||
//! > // ...
|
||||
//! > # winnow::token::one_of(list)
|
||||
//! > }
|
||||
//! > ```
|
||||
//! > If you have not programmed in a language where functions are values, the type signature of the
|
||||
//! > [`one_of`] function might be a surprise.
|
||||
//! > The function [`one_of`] *returns a function*. The function it returns is a
|
||||
//! > [`Parser`], taking a `&str` and returning an [`Result`]. This is a common pattern in winnow for
|
||||
//! > configurable or stateful parsers.
|
||||
//!
|
||||
//! Some of character classes are common enough that a named parser is provided, like with:
|
||||
//! - [`line_ending`][crate::ascii::line_ending]: Recognizes an end of line (both `\n` and `\r\n`)
|
||||
//! - [`newline`][crate::ascii::newline]: Matches a newline character `\n`
|
||||
//! - [`tab`][crate::ascii::tab]: Matches a tab character `\t`
|
||||
//!
|
||||
//! You can then capture sequences of these characters with parsers like [`take_while`].
|
||||
//! ```rust
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::token::take_while;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! take_while(1.., ('0'..='9', 'a'..='f', 'A'..='F')).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "1a2b Hello";
|
||||
//!
|
||||
//! let output = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(output, "1a2b");
|
||||
//!
|
||||
//! assert!(parse_digits.parse_next(&mut "Z").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! We could simplify this further by using one of the built-in character classes, [`hex_digit1`]:
|
||||
//! ```rust
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::Result;
|
||||
//! use winnow::ascii::hex_digit1;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! hex_digit1.parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "1a2b Hello";
|
||||
//!
|
||||
//! let output = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(output, "1a2b");
|
||||
//!
|
||||
//! assert!(parse_digits.parse_next(&mut "Z").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! See [`ascii`] for more text-based parsers.
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::ascii;
|
||||
use crate::ascii::hex_digit1;
|
||||
use crate::stream::ContainsToken;
|
||||
use crate::stream::Stream;
|
||||
use crate::token;
|
||||
use crate::token::any;
|
||||
use crate::token::literal;
|
||||
use crate::token::one_of;
|
||||
use crate::token::take_while;
|
||||
use crate::Parser;
|
||||
use crate::Result;
|
||||
use std::ops::RangeInclusive;
|
||||
|
||||
pub use super::chapter_1 as previous;
|
||||
pub use super::chapter_3 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+394
@@ -0,0 +1,394 @@
|
||||
//! # Chapter 3: Sequencing and Alternatives
|
||||
//!
|
||||
//! In the last chapter, we saw how to create parsers using prebuilt parsers.
|
||||
//!
|
||||
//! In this chapter, we explore two other widely used features:
|
||||
//! sequencing and alternatives.
|
||||
//!
|
||||
//! ## Sequencing
|
||||
//!
|
||||
//! Now that we can create more interesting parsers, we can sequence them together, like:
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! #
|
||||
//! fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! "0x".parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! take_while(1.., (
|
||||
//! ('0'..='9'),
|
||||
//! ('A'..='F'),
|
||||
//! ('a'..='f'),
|
||||
//! )).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let prefix = parse_prefix.parse_next(&mut input).unwrap();
|
||||
//! let digits = parse_digits.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(prefix, "0x");
|
||||
//! assert_eq!(digits, "1a2b");
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! To sequence these together, you can just put them in a tuple:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! #
|
||||
//! # fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # "0x".parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! //...
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let (prefix, digits) = (
|
||||
//! parse_prefix,
|
||||
//! parse_digits
|
||||
//! ).parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(prefix, "0x");
|
||||
//! assert_eq!(digits, "1a2b");
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! Frequently, you won't care about the literal and you can instead use one of the provided combinators,
|
||||
//! like [`preceded`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::combinator::preceded;
|
||||
//!
|
||||
//! # fn parse_prefix<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # "0x".parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! //...
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let digits = preceded(
|
||||
//! parse_prefix,
|
||||
//! parse_digits
|
||||
//! ).parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(digits, "1a2b");
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! See [`combinator`] for more sequencing parsers.
|
||||
//!
|
||||
//! ## Alternatives
|
||||
//!
|
||||
//! Sometimes, we might want to choose between two parsers; and we're happy with
|
||||
//! either being used.
|
||||
//!
|
||||
//! To retry a parse result, we can save off a [`Stream::checkpoint`] and later restore the parser
|
||||
//! back to that position with [`Stream::reset`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::stream::Stream;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! let start = input.checkpoint();
|
||||
//! if let Ok(output) = ("0b", parse_bin_digits).parse_next(input) {
|
||||
//! return Ok(output);
|
||||
//! }
|
||||
//!
|
||||
//! input.reset(&start);
|
||||
//! if let Ok(output) = ("0o", parse_oct_digits).parse_next(input) {
|
||||
//! return Ok(output);
|
||||
//! }
|
||||
//!
|
||||
//! input.reset(&start);
|
||||
//! if let Ok(output) = ("0d", parse_dec_digits).parse_next(input) {
|
||||
//! return Ok(output);
|
||||
//! }
|
||||
//!
|
||||
//! input.reset(&start);
|
||||
//! ("0x", parse_hex_digits).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let (prefix, digits) = parse_digits.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(prefix, "0x");
|
||||
//! assert_eq!(digits, "1a2b");
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! <div class="warning">
|
||||
//!
|
||||
//! **Warning:** the above example is for illustrative purposes and relying on `Result::Ok` or
|
||||
//! `Result::Err` can lead to incorrect behavior. This will be clarified in later when covering
|
||||
//! [error handling][`chapter_7`#error-cuts]
|
||||
//!
|
||||
//! </div>
|
||||
//!
|
||||
//! [`opt`] is a parser that encapsulates this pattern of "retry on failure":
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::combinator::opt;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! if let Some(output) = opt(("0b", parse_bin_digits)).parse_next(input)? {
|
||||
//! Ok(output)
|
||||
//! } else if let Some(output) = opt(("0o", parse_oct_digits)).parse_next(input)? {
|
||||
//! Ok(output)
|
||||
//! } else if let Some(output) = opt(("0d", parse_dec_digits)).parse_next(input)? {
|
||||
//! Ok(output)
|
||||
//! } else {
|
||||
//! ("0x", parse_hex_digits).parse_next(input)
|
||||
//! }
|
||||
//! }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let (prefix, digits) = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, " Hello");
|
||||
//! # assert_eq!(prefix, "0x");
|
||||
//! # assert_eq!(digits, "1a2b");
|
||||
//! #
|
||||
//! # assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! [`alt`] encapsulates this if/else-if ladder pattern, with the last case being the "else":
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::combinator::alt;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! alt((
|
||||
//! ("0b", parse_bin_digits),
|
||||
//! ("0o", parse_oct_digits),
|
||||
//! ("0d", parse_dec_digits),
|
||||
//! ("0x", parse_hex_digits),
|
||||
//! )).parse_next(input)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let (prefix, digits) = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, " Hello");
|
||||
//! # assert_eq!(prefix, "0x");
|
||||
//! # assert_eq!(digits, "1a2b");
|
||||
//! #
|
||||
//! # assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! <div class="warning">
|
||||
//!
|
||||
//! **Note:** [`empty`] and [`fail`] are parsers that might be useful in the "else" case.
|
||||
//!
|
||||
//! </div>
|
||||
//!
|
||||
//! Sometimes a giant if/else-if ladder can be slow and you'd rather have a `match` statement for
|
||||
//! branches of your parser that have unique prefixes. In this case, you can use the
|
||||
//! [`dispatch`] macro:
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::combinator::dispatch;
|
||||
//! use winnow::token::take;
|
||||
//! use winnow::combinator::fail;
|
||||
//!
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! dispatch!(take(2usize);
|
||||
//! "0b" => parse_bin_digits,
|
||||
//! "0o" => parse_oct_digits,
|
||||
//! "0d" => parse_dec_digits,
|
||||
//! "0x" => parse_hex_digits,
|
||||
//! _ => fail,
|
||||
//! ).parse_next(input)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let digits = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, " Hello");
|
||||
//! # assert_eq!(digits, "1a2b");
|
||||
//! #
|
||||
//! # assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! <div class="warning">
|
||||
//!
|
||||
//! **Note:** [`peek`] may be useful when [`dispatch`]ing from hints from each case's parser.
|
||||
//!
|
||||
//! </div>
|
||||
//!
|
||||
//! See [`combinator`] for more alternative parsers.
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use super::chapter_7;
|
||||
use crate::combinator;
|
||||
use crate::combinator::alt;
|
||||
use crate::combinator::dispatch;
|
||||
use crate::combinator::empty;
|
||||
use crate::combinator::fail;
|
||||
use crate::combinator::opt;
|
||||
use crate::combinator::peek;
|
||||
use crate::combinator::preceded;
|
||||
use crate::stream::Stream;
|
||||
|
||||
pub use super::chapter_2 as previous;
|
||||
pub use super::chapter_4 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
//! # Chapter 4: Parsers With Custom Return Types
|
||||
//!
|
||||
//! So far, we have seen mostly functions that take an `&str`, and return a
|
||||
//! [`Result<&str>`]. Splitting strings into smaller strings and characters is certainly
|
||||
//! useful, but it's not the only thing winnow is capable of!
|
||||
//!
|
||||
//! A useful operation when parsing is to convert between types; for example
|
||||
//! parsing from `&str` to another primitive, like [`usize`].
|
||||
//!
|
||||
//! All we need to do for our parser to return a different type is to change
|
||||
//! the type parameter of [`Result`] to the desired return type.
|
||||
//! For example, to return a `usize`, return a `Result<usize>`.
|
||||
//!
|
||||
//! One winnow-native way of doing a type conversion is to use the
|
||||
//! [`Parser::parse_to`] combinator
|
||||
//! to convert from a successful parse to a particular type using [`FromStr`].
|
||||
//!
|
||||
//! The following code converts from a string containing a number to `usize`:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::ascii::digit1;
|
||||
//! #
|
||||
//! fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! digit1
|
||||
//! .parse_to()
|
||||
//! .parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "1024 Hello";
|
||||
//!
|
||||
//! let output = parse_digits.parse_next(&mut input).unwrap();
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(output, 1024);
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "Z").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! `Parser::parse_to` is just a convenient form of [`Parser::try_map`] which we can use to handle
|
||||
//! all radices of numbers:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! use winnow::combinator::dispatch;
|
||||
//! use winnow::token::take;
|
||||
//! use winnow::combinator::fail;
|
||||
//!
|
||||
//! fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! dispatch!(take(2usize);
|
||||
//! "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! _ => fail,
|
||||
//! ).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b Hello";
|
||||
//!
|
||||
//! let digits = parse_digits.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(digits, 0x1a2b);
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! See also [`Parser`] for more output-modifying parsers.
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use crate::Parser;
|
||||
use crate::Result;
|
||||
use std::str::FromStr;
|
||||
|
||||
pub use super::chapter_3 as previous;
|
||||
pub use super::chapter_5 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+300
@@ -0,0 +1,300 @@
|
||||
//! # Chapter 5: Repetition
|
||||
//!
|
||||
//! In [`chapter_3`], we covered how to sequence different parsers into a tuple but sometimes you need to run a
|
||||
//! single parser multiple times, collecting the result into a container, like `Vec`.
|
||||
//!
|
||||
//! Let's collect the result of `parse_digits`:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::dispatch;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! use winnow::combinator::opt;
|
||||
//! use winnow::combinator::repeat;
|
||||
//! use winnow::combinator::terminated;
|
||||
//!
|
||||
//! fn parse_list(input: &mut &str) -> Result<Vec<usize>> {
|
||||
//! let mut list = Vec::new();
|
||||
//! while let Some(output) = opt(terminated(parse_digits, opt(','))).parse_next(input)? {
|
||||
//! list.push(output);
|
||||
//! }
|
||||
//! Ok(list)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//! # fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! # dispatch!(take(2usize);
|
||||
//! # "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! # "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! # "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! # "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! # _ => fail,
|
||||
//! # ).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b,0x3c4d,0x5e6f Hello";
|
||||
//!
|
||||
//! let digits = parse_list.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(digits, vec![0x1a2b, 0x3c4d, 0x5e6f]);
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! We can implement this declaratively with [`repeat`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::dispatch;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! use winnow::combinator::opt;
|
||||
//! use winnow::combinator::repeat;
|
||||
//! use winnow::combinator::terminated;
|
||||
//!
|
||||
//! fn parse_list(input: &mut &str) -> Result<Vec<usize>> {
|
||||
//! repeat(0..,
|
||||
//! terminated(parse_digits, opt(','))
|
||||
//! ).parse_next(input)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! # dispatch!(take(2usize);
|
||||
//! # "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! # "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! # "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! # "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! # _ => fail,
|
||||
//! # ).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b,0x3c4d,0x5e6f Hello";
|
||||
//! #
|
||||
//! # let digits = parse_list.parse_next(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, " Hello");
|
||||
//! # assert_eq!(digits, vec![0x1a2b, 0x3c4d, 0x5e6f]);
|
||||
//! #
|
||||
//! # assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! You'll notice that the above allows trailing `,`. However, if that's not desired, it
|
||||
//! can easily be fixed by using [`separated`] instead of [`repeat`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::dispatch;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! use winnow::combinator::separated;
|
||||
//!
|
||||
//! fn parse_list(input: &mut &str) -> Result<Vec<usize>> {
|
||||
//! separated(0.., parse_digits, ",").parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//! # fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! # dispatch!(take(2usize);
|
||||
//! # "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! # "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! # "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! # "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! # _ => fail,
|
||||
//! # ).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b,0x3c4d,0x5e6f Hello";
|
||||
//!
|
||||
//! let digits = parse_list.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(digits, vec![0x1a2b, 0x3c4d, 0x5e6f]);
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! If you look closely at [`separated`] and [`repeat`], they aren't limited to collecting
|
||||
//! the result into a `Vec`, but rather anything that implements the [`Accumulate`] trait.
|
||||
//! [`Accumulate`] is for instance also implemented for [`HashSet`], [`String`] and `()`.
|
||||
//!
|
||||
//! This lets us build more complex parsers than we did in
|
||||
//! [`chapter_2`] by accumulating the results into a `()` and [`take`][Parser::take]-ing
|
||||
//! the consumed input.
|
||||
//!
|
||||
//! `take` works by
|
||||
//! 1. Creating a [`checkpoint`][Stream::checkpoint]
|
||||
//! 2. Running the inner parser, in our case the `parse_list` parser, which will advance the input
|
||||
//! 3. Returning the slice from the first checkpoint to the current position.
|
||||
//!
|
||||
//! Since the result of `parse_list` gets thrown away, we
|
||||
//! accumulates into a `()` to not waste work creating an unused `Vec`.
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::dispatch;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::combinator::separated;
|
||||
//! #
|
||||
//! fn take_list<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! parse_list.take().parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! fn parse_list(input: &mut &str) -> Result<()> {
|
||||
//! separated(0.., parse_digits, ",").parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! # fn parse_digits(input: &mut &str) -> Result<usize> {
|
||||
//! # dispatch!(take(2usize);
|
||||
//! # "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! # "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! # "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! # "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! # _ => fail,
|
||||
//! # ).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let mut input = "0x1a2b,0x3c4d,0x5e6f Hello";
|
||||
//!
|
||||
//! let digits = take_list.parse_next(&mut input).unwrap();
|
||||
//!
|
||||
//! assert_eq!(input, " Hello");
|
||||
//! assert_eq!(digits, "0x1a2b,0x3c4d,0x5e6f");
|
||||
//!
|
||||
//! assert!(parse_digits(&mut "ghiWorld").is_err());
|
||||
//! }
|
||||
//! ```
|
||||
//! See [`combinator`] for more repetition parsers.
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use super::chapter_2;
|
||||
use super::chapter_3;
|
||||
use crate::combinator;
|
||||
use crate::combinator::repeat;
|
||||
use crate::combinator::separated;
|
||||
use crate::stream::Accumulate;
|
||||
use crate::stream::Stream;
|
||||
use crate::Parser;
|
||||
use std::collections::HashSet;
|
||||
|
||||
pub use super::chapter_4 as previous;
|
||||
pub use super::chapter_6 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+120
@@ -0,0 +1,120 @@
|
||||
//! # Chapter 6: Integrating the Parser
|
||||
//!
|
||||
//! So far, we've highlighted how to incrementally parse, but how do we bring this all together
|
||||
//! into our application?
|
||||
//!
|
||||
//! Parsers we've been working with look like:
|
||||
//! ```rust
|
||||
//! # use winnow::error::ContextError;
|
||||
//! # use winnow::Parser;
|
||||
//! use winnow::Result;
|
||||
//!
|
||||
//! pub fn parser<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! // ...
|
||||
//! # Ok("")
|
||||
//! }
|
||||
//! ```
|
||||
//! 1. We have to decide what to do about the "remainder" of the `input`.
|
||||
//! 2. The [`Result`] may not be compatible with the rest of the Rust ecosystem.
|
||||
//! Normally, Rust applications want errors that are `std::error::Error + Send + Sync + 'static`
|
||||
//! meaning:
|
||||
//! - They implement the [`std::error::Error`] trait
|
||||
//! - They can be sent across threads
|
||||
//! - They are safe to be referenced across threads
|
||||
//! - They do not borrow
|
||||
//!
|
||||
//! winnow provides [`Parser::parse`] to help with this:
|
||||
//! - Ensures we hit [`eof`]
|
||||
//! - Wraps the error in [`ParseError`]
|
||||
//! - For simple cases, [`ParseError`] provides a [`std::fmt::Display`] impl to render the error.
|
||||
//! - For more involved cases, [`ParseError`] provides the original [`input`][ParseError::input] and the
|
||||
//! [`offset`][ParseError::offset] of where it failed so you can capture this information in
|
||||
//! your error, [rendering it as you wish][chapter_7#error-adaptation-and-rendering].
|
||||
//! - Converts from [`ModalResult`] to [`Result`] (if used, more on this in [`chapter_7`])
|
||||
//!
|
||||
//! However, [`ParseError`] will still need some level of adaptation to integrate with your
|
||||
//! application's error type (like with `?`).
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::dispatch;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! use winnow::Parser;
|
||||
//!
|
||||
//! #[derive(Debug, PartialEq, Eq)]
|
||||
//! pub struct Hex(usize);
|
||||
//!
|
||||
//! impl std::str::FromStr for Hex {
|
||||
//! type Err = anyhow::Error;
|
||||
//!
|
||||
//! fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! parse_digits
|
||||
//! .map(Hex)
|
||||
//! .parse(input)
|
||||
//! .map_err(|e| anyhow::format_err!("{e}"))
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<usize> {
|
||||
//! # dispatch!(take(2usize);
|
||||
//! # "0b" => parse_bin_digits.try_map(|s| usize::from_str_radix(s, 2)),
|
||||
//! # "0o" => parse_oct_digits.try_map(|s| usize::from_str_radix(s, 8)),
|
||||
//! # "0d" => parse_dec_digits.try_map(|s| usize::from_str_radix(s, 10)),
|
||||
//! # "0x" => parse_hex_digits.try_map(|s| usize::from_str_radix(s, 16)),
|
||||
//! # _ => fail,
|
||||
//! # ).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let input = "0x1a2b";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap(), Hex(0x1a2b));
|
||||
//!
|
||||
//! let input = "0x1a2b Hello";
|
||||
//! assert!(input.parse::<Hex>().is_err());
|
||||
//! let input = "ghiHello";
|
||||
//! assert!(input.parse::<Hex>().is_err());
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use super::chapter_1;
|
||||
use super::chapter_7;
|
||||
use crate::combinator::eof;
|
||||
use crate::error::ErrMode;
|
||||
use crate::error::ParseError;
|
||||
use crate::ModalResult;
|
||||
use crate::Parser;
|
||||
|
||||
pub use super::chapter_5 as previous;
|
||||
pub use super::chapter_7 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+736
@@ -0,0 +1,736 @@
|
||||
//! # Chapter 7: Error Reporting
|
||||
//!
|
||||
//! ## Context
|
||||
//!
|
||||
//! With [`Parser::parse`] we get errors that point to the failure but don't explain the reason for
|
||||
//! the failure:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! // ...
|
||||
//!
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! # alt((
|
||||
//! # ("0b", parse_bin_digits),
|
||||
//! # ("0o", parse_oct_digits),
|
||||
//! # ("0d", parse_dec_digits),
|
||||
//! # ("0x", parse_hex_digits),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "0xZZ";
|
||||
//! let error = "\
|
||||
//! 0xZZ
|
||||
//! ^
|
||||
//! ";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! Back in [`chapter_1`], we glossed over the `Err` variant of [`Result`]. `Result<O>` is
|
||||
//! actually short for `Result<O, E=ContextError>` where [`ContextError`] is a relatively cheap
|
||||
//! way of building up reasonable errors for humans.
|
||||
//!
|
||||
//! You can use [`Parser::context`] to annotate the error with custom types
|
||||
//! while unwinding to further clarify the error:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! use winnow::error::StrContext;
|
||||
//! use winnow::error::StrContextValue;
|
||||
//!
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! alt((
|
||||
//! ("0b", parse_bin_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! ("0o", parse_oct_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! ("0d", parse_dec_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! ("0x", parse_hex_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! )).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//!
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "0xZZ";
|
||||
//! let error = "\
|
||||
//! 0xZZ
|
||||
//! ^
|
||||
//! invalid digit
|
||||
//! expected hexadecimal";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! If you remember back to [`chapter_3`], [`alt`] will only report the last error.
|
||||
//! So if the parsers fail for any reason, like a bad radix, it will be reported as an invalid
|
||||
//! hexadecimal value:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::error::StrContext;
|
||||
//! # use winnow::error::StrContextValue;
|
||||
//! #
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! # alt((
|
||||
//! # ("0b", parse_bin_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! # ("0o", parse_oct_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! # ("0d", parse_dec_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! # ("0x", parse_hex_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "100";
|
||||
//! let error = "\
|
||||
//! 100
|
||||
//! ^
|
||||
//! invalid digit
|
||||
//! expected hexadecimal";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//! We can improve this with [`fail`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! use winnow::error::StrContext;
|
||||
//! use winnow::error::StrContextValue;
|
||||
//!
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! alt((
|
||||
//! ("0b", parse_bin_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! ("0o", parse_oct_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! ("0d", parse_dec_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! ("0x", parse_hex_digits)
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! fail
|
||||
//! .context(StrContext::Label("radix prefix"))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0b")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0o")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0d")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0x"))),
|
||||
//! )).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//!
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "100";
|
||||
//! let error = "\
|
||||
//! 100
|
||||
//! ^
|
||||
//! invalid radix prefix
|
||||
//! expected `0b`, `0o`, `0d`, `0x`";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Error Cuts
|
||||
//!
|
||||
//! We still have the issue that we are falling-through when the radix is valid but the digits
|
||||
//! don't match it:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::Result;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::error::StrContext;
|
||||
//! # use winnow::error::StrContextValue;
|
||||
//! #
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> Result<(&'s str, &'s str)> {
|
||||
//! # alt((
|
||||
//! # ("0b", parse_bin_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! # ("0o", parse_oct_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! # ("0d", parse_dec_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! # ("0x", parse_hex_digits)
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! # fail
|
||||
//! # .context(StrContext::Label("radix prefix"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0b")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0o")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0d")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0x"))),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> Result<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "0b5";
|
||||
//! let error = "\
|
||||
//! 0b5
|
||||
//! ^
|
||||
//! invalid radix prefix
|
||||
//! expected `0b`, `0o`, `0d`, `0x`";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! Winnow provides an error wrapper, [`ErrMode<ContextError>`], so different failure modes can affect parsing.
|
||||
//! [`ErrMode`] is an enum with [`Backtrack`] and [`Cut`] variants (ignore [`Incomplete`] as its only
|
||||
//! relevant for [streaming][_topic::stream]). By default, errors are [`Backtrack`], meaning that
|
||||
//! other parsing branches will be attempted on failure, like the next case of an [`alt`]. [`Cut`]
|
||||
//! shortcircuits all other branches, immediately reporting the error.
|
||||
//!
|
||||
//! To make [`ErrMode`] more convenient, Winnow provides [`ModalResult`]:
|
||||
//! ```rust
|
||||
//! # use winnow::error::ContextError;
|
||||
//! # use winnow::error::ErrMode;
|
||||
//! pub type ModalResult<O, E = ContextError> = Result<O, ErrMode<E>>;
|
||||
//! ```
|
||||
//!
|
||||
//! So we can get the correct `context` by changing to [`ModalResult`] and adding [`cut_err`]:
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::error::StrContext;
|
||||
//! # use winnow::error::StrContextValue;
|
||||
//! use winnow::combinator::cut_err;
|
||||
//!
|
||||
//! #
|
||||
//! # #[derive(Debug, PartialEq, Eq)]
|
||||
//! # pub struct Hex(usize);
|
||||
//! #
|
||||
//! # impl std::str::FromStr for Hex {
|
||||
//! # type Err = String;
|
||||
//! #
|
||||
//! # fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! # .parse(input)
|
||||
//! # .map_err(|e| e.to_string())
|
||||
//! # }
|
||||
//! # }
|
||||
//! #
|
||||
//! fn parse_digits<'s>(input: &mut &'s str) -> ModalResult<(&'s str, &'s str)> {
|
||||
//! alt((
|
||||
//! ("0b", cut_err(parse_bin_digits))
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! ("0o", cut_err(parse_oct_digits))
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! ("0d", cut_err(parse_dec_digits))
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! ("0x", cut_err(parse_hex_digits))
|
||||
//! .context(StrContext::Label("digit"))
|
||||
//! .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! fail
|
||||
//! .context(StrContext::Label("radix prefix"))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0b")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0o")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0d")))
|
||||
//! .context(StrContext::Expected(StrContextValue::StringLiteral("0x"))),
|
||||
//! )).parse_next(input)
|
||||
//! }
|
||||
//!
|
||||
//! // ...
|
||||
//!
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "0b5";
|
||||
//! let error = "\
|
||||
//! 0b5
|
||||
//! ^
|
||||
//! invalid digit
|
||||
//! expected binary";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Error Adaptation and Rendering
|
||||
//!
|
||||
//! While Winnow can provide basic rendering of errors, your application can have various demands
|
||||
//! beyond the basics provided like
|
||||
//! - Correctly reporting columns with unicode
|
||||
//! - Conforming to a specific layout
|
||||
//!
|
||||
//! For example, to get rustc-like errors with [`annotate-snippets`](https://crates.io/crates/annotate-snippets):
|
||||
//! ```rust
|
||||
//! # use winnow::prelude::*;
|
||||
//! # use winnow::token::take_while;
|
||||
//! # use winnow::combinator::alt;
|
||||
//! # use winnow::token::take;
|
||||
//! # use winnow::combinator::fail;
|
||||
//! # use winnow::Parser;
|
||||
//! # use winnow::error::ParseError;
|
||||
//! # use winnow::error::ContextError;
|
||||
//! # use winnow::error::StrContext;
|
||||
//! # use winnow::error::StrContextValue;
|
||||
//! # use winnow::combinator::cut_err;
|
||||
//! #
|
||||
//! #
|
||||
//! #[derive(Debug, PartialEq, Eq)]
|
||||
//! pub struct Hex(usize);
|
||||
//!
|
||||
//! impl std::str::FromStr for Hex {
|
||||
//! type Err = HexError;
|
||||
//!
|
||||
//! fn from_str(input: &str) -> Result<Self, Self::Err> {
|
||||
//! // ...
|
||||
//! # parse_digits
|
||||
//! # .try_map(|(t, v)| match t {
|
||||
//! # "0b" => usize::from_str_radix(v, 2),
|
||||
//! # "0o" => usize::from_str_radix(v, 8),
|
||||
//! # "0d" => usize::from_str_radix(v, 10),
|
||||
//! # "0x" => usize::from_str_radix(v, 16),
|
||||
//! # _ => unreachable!("`parse_digits` doesn't return `{t}`"),
|
||||
//! # })
|
||||
//! # .map(Hex)
|
||||
//! .parse(input)
|
||||
//! .map_err(|e| HexError::from_parse(e))
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! #[derive(Debug)]
|
||||
//! pub struct HexError {
|
||||
//! message: String,
|
||||
//! // Byte spans are tracked, rather than line and column.
|
||||
//! // This makes it easier to operate on programmatically
|
||||
//! // and doesn't limit us to one definition for column count
|
||||
//! // which can depend on the output medium and application.
|
||||
//! span: std::ops::Range<usize>,
|
||||
//! input: String,
|
||||
//! }
|
||||
//!
|
||||
//! impl HexError {
|
||||
//! // Avoiding `From` so `winnow` types don't become part of our public API
|
||||
//! fn from_parse(error: ParseError<&str, ContextError>) -> Self {
|
||||
//! // The default renderer for `ContextError` is still used but that can be
|
||||
//! // customized as well to better fit your needs.
|
||||
//! let message = error.inner().to_string();
|
||||
//! let input = (*error.input()).to_owned();
|
||||
//! // Assume the error span is only for the first `char`.
|
||||
//! let span = error.char_span();
|
||||
//! Self {
|
||||
//! message,
|
||||
//! span,
|
||||
//! input,
|
||||
//! }
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! impl std::fmt::Display for HexError {
|
||||
//! fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
//! let message = annotate_snippets::Level::Error.title(&self.message)
|
||||
//! .snippet(annotate_snippets::Snippet::source(&self.input)
|
||||
//! .fold(true)
|
||||
//! .annotation(annotate_snippets::Level::Error.span(self.span.clone()))
|
||||
//! );
|
||||
//! let renderer = annotate_snippets::Renderer::plain();
|
||||
//! let rendered = renderer.render(message);
|
||||
//! rendered.fmt(f)
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! impl std::error::Error for HexError {}
|
||||
//!
|
||||
//! # fn parse_digits<'s>(input: &mut &'s str) -> ModalResult<(&'s str, &'s str)> {
|
||||
//! # alt((
|
||||
//! # ("0b", cut_err(parse_bin_digits))
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("binary"))),
|
||||
//! # ("0o", cut_err(parse_oct_digits))
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("octal"))),
|
||||
//! # ("0d", cut_err(parse_dec_digits))
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("decimal"))),
|
||||
//! # ("0x", cut_err(parse_hex_digits))
|
||||
//! # .context(StrContext::Label("digit"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::Description("hexadecimal"))),
|
||||
//! # fail
|
||||
//! # .context(StrContext::Label("radix prefix"))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0b")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0o")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0d")))
|
||||
//! # .context(StrContext::Expected(StrContextValue::StringLiteral("0x"))),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_bin_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='1'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_oct_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='7'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_dec_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! #
|
||||
//! # fn parse_hex_digits<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! # take_while(1.., (
|
||||
//! # ('0'..='9'),
|
||||
//! # ('A'..='F'),
|
||||
//! # ('a'..='f'),
|
||||
//! # )).parse_next(input)
|
||||
//! # }
|
||||
//! fn main() {
|
||||
//! let input = "0b5";
|
||||
//! let error = "\
|
||||
//! error: invalid digit
|
||||
//! expected binary
|
||||
//! |
|
||||
//! 1 | 0b5
|
||||
//! | ^
|
||||
//! |";
|
||||
//! assert_eq!(input.parse::<Hex>().unwrap_err().to_string(), error);
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! To add spans to your parsed data for inclusion in semantic errors, see [`Parser::with_span`].
|
||||
//!
|
||||
//! For richer syntactic errors with spans,
|
||||
//! consider separating lexing and parsing and annotating your tokens with [`Parser::with_span`].
|
||||
|
||||
#![allow(unused_imports)]
|
||||
use super::chapter_1;
|
||||
use super::chapter_3;
|
||||
use crate::combinator::alt;
|
||||
use crate::combinator::cut_err;
|
||||
use crate::combinator::fail;
|
||||
use crate::error::ContextError;
|
||||
use crate::error::ErrMode;
|
||||
use crate::error::ErrMode::*;
|
||||
use crate::ModalResult;
|
||||
use crate::Parser;
|
||||
use crate::Result;
|
||||
use crate::_topic;
|
||||
|
||||
pub use super::chapter_6 as previous;
|
||||
pub use super::chapter_8 as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
//! # Chapter 8: Debugging
|
||||
//!
|
||||
//! When things inevitably go wrong, you can introspect the parsing state by running your test case
|
||||
//! with `--features winnow/debug`.
|
||||
//!
|
||||
//! For example, the trace output of an [escaped string parser][crate::_topic::language#escaped-strings]:
|
||||
//! 
|
||||
//!
|
||||
//! You can extend your own parsers to show up by wrapping their body with
|
||||
//! [`trace`][crate::combinator::trace]. Going back to [`do_nothing_parser`][super::chapter_1].
|
||||
//! ```rust
|
||||
//! # use winnow::ModalResult;
|
||||
//! # use winnow::Parser;
|
||||
//! use winnow::combinator::trace;
|
||||
//!
|
||||
//! pub fn do_nothing_parser<'s>(input: &mut &'s str) -> ModalResult<&'s str> {
|
||||
//! trace(
|
||||
//! "do_nothing_parser",
|
||||
//! |i: &mut _| Ok("")
|
||||
//! ).parse_next(input)
|
||||
//! }
|
||||
//! #
|
||||
//! # fn main() {
|
||||
//! # let mut input = "0x1a2b Hello";
|
||||
//! #
|
||||
//! # let output = do_nothing_parser.parse_next(&mut input).unwrap();
|
||||
//! # // Same as:
|
||||
//! # // let output = do_nothing_parser(&mut input).unwrap();
|
||||
//! #
|
||||
//! # assert_eq!(input, "0x1a2b Hello");
|
||||
//! # assert_eq!(output, "");
|
||||
//! # }
|
||||
//! ```
|
||||
|
||||
pub use super::chapter_7 as previous;
|
||||
pub use crate::_topic as next;
|
||||
pub use crate::_tutorial as table_of_contents;
|
||||
Vendored
+14
@@ -0,0 +1,14 @@
|
||||
//! # Tutorial
|
||||
//!
|
||||
//! Table of Contents
|
||||
#![allow(clippy::std_instead_of_core)]
|
||||
|
||||
pub mod chapter_0;
|
||||
pub mod chapter_1;
|
||||
pub mod chapter_2;
|
||||
pub mod chapter_3;
|
||||
pub mod chapter_4;
|
||||
pub mod chapter_5;
|
||||
pub mod chapter_6;
|
||||
pub mod chapter_7;
|
||||
pub mod chapter_8;
|
||||
Reference in new issue
Block a user