Merge pull request #436 from epage/docs

docs: Try to make people more successful with `cut_err`

src/_topic/error.rs

@@ -1,13 +1,27 @@
 //! # Custom Errors
 //!
-//! The most basic error type is [`ParserError`][crate::error::ParserError]
+//! Between [`ContextError`], [`Parser::context`], and [`cut_err`],
+//! most error needs will likely be met
+//! (see [tutorial][chapter_6]).
+//! When that isn't the case, you can implement your own error type.
+//!
+//! The most basic error trait is [`ParserError`].
 //!
 //! Optional traits include:
-//! - [`AddContext`][crate::error::AddContext]
-//! - [`FromExternalError`][crate::error::FromExternalError]
+//! - [`AddContext`]
+//! - [`FromExternalError`]
 //!
 //! # Example
 //!
 //!```rust
 #![doc = include_str!("../../examples/custom_error.rs")]
 //!```
+
+#![allow(unused_imports)]
+use crate::combinator::cut_err;
+use crate::error::ContextError;
+use crate::Parser;
+use crate::_tutorial::chapter_6;
+use crate::error::AddContext;
+use crate::error::FromExternalError;
+use crate::error::ParserError;

src/_topic/mod.rs

@@ -17,6 +17,7 @@
 //!   - [Parsing Partial Input][partial]
 //!   - [Custom stream or token][stream]
 //!   - [Custom errors][error]
+//!   - [Debugging][crate::_tutorial::chapter_8]
 //!
 //! See also parsers written with `winnow`:
 //!

src/_tutorial/chapter_7.rs

@@ -115,4 +115,5 @@ use crate::PResult;
 use crate::Parser;
 
 pub use super::chapter_6 as previous;
+pub use super::chapter_8 as next;
 pub use crate::_tutorial as table_of_contents;

src/_tutorial/chapter_8.rs

@@ -0,0 +1,34 @@
+//! # Chapter 8: Debugging
+//!
+//! When things inevitably go wrong, you can introspect the parsing state by running your test case
+//! with `--features debug`:
+//! ![Trace output from string example](https://raw.githubusercontent.com/winnow-rs/winnow/main/assets/trace.svg "Example output")
+//!
+//! 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::PResult;
+//! # use winnow::Parser;
+//! use winnow::combinator::trace;
+//!
+//! pub fn do_nothing_parser<'s>(input: &mut &'s str) -> PResult<&'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::_tutorial as table_of_contents;

src/_tutorial/mod.rs

@@ -11,3 +11,4 @@ pub mod chapter_4;
 pub mod chapter_5;
 pub mod chapter_6;
 pub mod chapter_7;
+pub mod chapter_8;

src/ascii/mod.rs

@@ -10,14 +10,14 @@ use crate::lib::std::ops::{Add, Shl};
 use crate::combinator::alt;
 use crate::combinator::cut_err;
 use crate::combinator::opt;
+use crate::combinator::trace;
 use crate::error::ParserError;
 use crate::error::{ErrMode, ErrorKind, Needed};
 use crate::stream::{AsBStr, AsChar, ParseSlice, Stream, StreamIsPartial};
 use crate::stream::{Compare, CompareResult};
 use crate::token::one_of;
 use crate::token::take_till;
 use crate::token::take_while;
-use crate::trace::trace;
 use crate::PResult;
 use crate::Parser;
 

src/binary/bits/mod.rs

@@ -4,10 +4,10 @@
 #[cfg(test)]
 mod tests;
 
+use crate::combinator::trace;
 use crate::error::{ErrMode, ErrorConvert, ErrorKind, Needed, ParserError};
 use crate::lib::std::ops::{AddAssign, Div, Shl, Shr};
 use crate::stream::{AsBytes, Stream, StreamIsPartial, ToUsize};
-use crate::trace::trace;
 use crate::{unpeek, IResult, PResult, Parser};
 
 /// Number of bits in a byte

src/binary/mod.rs

@@ -8,6 +8,7 @@ pub mod bits;
 mod tests;
 
 use crate::combinator::repeat;
+use crate::combinator::trace;
 use crate::error::ErrMode;
 use crate::error::ErrorKind;
 use crate::error::Needed;
@@ -17,7 +18,6 @@ use crate::stream::Accumulate;
 use crate::stream::{AsBytes, Stream, StreamIsPartial};
 use crate::stream::{ToUsize, UpdateSlice};
 use crate::token::take;
-use crate::trace::trace;
 use crate::PResult;
 use crate::Parser;
 

src/combinator/branch.rs

@@ -1,6 +1,6 @@
+use crate::combinator::trace;
 use crate::error::{ErrMode, ErrorKind, ParserError};
 use crate::stream::Stream;
-use crate::trace::trace;
 use crate::*;
 
 #[doc(inline)]
@@ -16,7 +16,10 @@ pub trait Alt<I, O, E> {
 
 /// Pick the first successful parser
 ///
-/// For tight control over the error, add a final case using [`fail`][crate::combinator::fail].
+/// To stop on an error, rather than trying further cases, see
+/// [`cut_err`][crate::combinator::cut_err] ([example][crate::_tutorial::chapter_6]).
+///
+/// For tight control over the error when no match is found, add a final case using [`fail`][crate::combinator::fail].
 /// Alternatively, with a [custom error type][crate::_topic::error], it is possible to track all
 /// errors or return the error of the parser that went the farthest in the input data.
 ///
@@ -65,6 +68,11 @@ pub trait Permutation<I, O, E> {
 /// It takes as argument a tuple of parsers, and returns a
 /// tuple of the parser results.
 ///
+/// To stop on an error, rather than trying further permutations, see
+/// [`cut_err`][crate::combinator::cut_err] ([example][crate::_tutorial::chapter_6]).
+///
+/// # Example
+///
 /// ```rust
 /// # use winnow::{error::ErrMode,error::{InputError, ErrorKind}, error::Needed};
 /// # use winnow::prelude::*;

src/combinator/core.rs

@@ -1,6 +1,6 @@
+use crate::combinator::trace;
 use crate::error::{ErrMode, ErrorKind, Needed, ParserError};
 use crate::stream::Stream;
-use crate::trace::trace;
 use crate::*;
 
 /// Return the remaining input.
@@ -225,6 +225,8 @@ where
 /// This commits the parse result, preventing alternative branch paths like with
 /// [`winnow::combinator::alt`][crate::combinator::alt].
 ///
+/// See the [tutorial][crate::_tutorial::chapter_6] for more details.
+///
 /// # Example
 ///
 /// Without `cut_err`:

src/trace/mod.rs → src/combinator/debug/mod.rs

@@ -1,11 +1,3 @@
-//! Parser execution tracing
-//!
-//! By default, nothing happens and tracing gets compiled away as a no-op. To enable tracing, use
-//! `--features debug`.
-//!
-//! # Example
-//!
-//!![Trace output from string example](https://raw.githubusercontent.com/winnow-rs/winnow/main/assets/trace.svg "Example output")
 #![cfg_attr(feature = "debug", allow(clippy::std_instead_of_core))]
 
 #[cfg(feature = "debug")]
@@ -22,7 +14,7 @@ compile_error!("`debug` requires `std`");
 ///
 /// Note that [`Parser::context`] also provides high level trace information.
 ///
-/// See [`trace` module][self] for more details.
+/// See [tutorial][crate::_tutorial::chapter_8] for more details.
 ///
 /// # Example
 ///
@@ -31,7 +23,7 @@ compile_error!("`debug` requires `std`");
 /// # use winnow::token::take_while;
 /// # use winnow::stream::AsChar;
 /// # use winnow::prelude::*;
-/// use winnow::trace::trace;
+/// use winnow::combinator::trace;
 ///
 /// fn short_alpha<'s>(s: &mut &'s [u8]) -> PResult<&'s [u8], InputError<&'s [u8]>> {
 ///   trace("short_alpha",

src/combinator/mod.rs

@@ -76,7 +76,7 @@
 //! - [`backtrack_err`]: Attempts a parse, allowing alternative parsers to be attempted despite
 //!   use of `cut_err`
 //! - [`Parser::context`]: Add context to the error if the parser fails
-//! - [`trace`][crate::trace::trace]: Print the parse state with the `debug` feature flag
+//! - [`trace`]: Print the parse state with the `debug` feature flag
 //! - [`todo()`]: Placeholder parser
 //!
 //! ## Remaining combinators
@@ -157,6 +157,7 @@
 
 mod branch;
 mod core;
+mod debug;
 mod multi;
 mod parser;
 mod sequence;
@@ -166,6 +167,7 @@ mod tests;
 
 pub use self::branch::*;
 pub use self::core::*;
+pub use self::debug::*;
 pub use self::multi::*;
 pub use self::parser::*;
 pub use self::sequence::*;

src/combinator/multi.rs

@@ -1,12 +1,12 @@
 //! Combinators applying their child parser multiple times
 
+use crate::combinator::trace;
 use crate::error::ErrMode;
 use crate::error::ErrorKind;
 use crate::error::ParserError;
 use crate::stream::Accumulate;
 use crate::stream::Range;
 use crate::stream::Stream;
-use crate::trace::trace;
 use crate::PResult;
 use crate::Parser;
 

src/combinator/parser.rs

@@ -1,10 +1,10 @@
+use crate::combinator::trace;
+use crate::combinator::trace_result;
 use crate::error::{AddContext, ErrMode, ErrorKind, FromExternalError, ParserError};
 use crate::lib::std::borrow::Borrow;
 use crate::lib::std::ops::Range;
 use crate::stream::StreamIsPartial;
 use crate::stream::{Location, Stream};
-use crate::trace::trace;
-use crate::trace::trace_result;
 use crate::*;
 
 /// Implementation of [`Parser::by_ref`]

src/combinator/sequence.rs

@@ -1,6 +1,6 @@
+use crate::combinator::trace;
 use crate::error::ParserError;
 use crate::stream::Stream;
-use crate::trace::trace;
 use crate::*;
 
 #[doc(inline)]

src/macros/dispatch.rs

@@ -41,7 +41,7 @@
 #[doc(hidden)] // forced to be visible in intended location
 macro_rules! dispatch {
     ($match_parser: expr; $( $pat:pat $(if $pred:expr)? => $expr: expr ),+ $(,)? ) => {
-        $crate::trace::trace("dispatch", move |i: &mut _|
+        $crate::combinator::trace("dispatch", move |i: &mut _|
         {
             use $crate::Parser;
             let initial = $match_parser.parse_next(i)?;

src/macros/seq.rs

@@ -64,15 +64,15 @@
 #[doc(alias = "struct_parser")]
 macro_rules! seq {
     ($name: ident { $($fields: tt)* }) => {
-        $crate::trace::trace(stringify!($name), move |input: &mut _| {
+        $crate::combinator::trace(stringify!($name), move |input: &mut _| {
             use $crate::Parser;
             $crate::seq_parse_struct_fields!(input; $($fields)*);
             #[allow(clippy::redundant_field_names)]
             Ok($crate::seq_init_struct_fields!( ($($fields)*); $name;))
         })
     };
     ($name: ident ( $($elements: tt)* )) => {
-        $crate::trace::trace(stringify!($name), move |input: &mut _| {
+        $crate::combinator::trace(stringify!($name), move |input: &mut _| {
             use $crate::Parser;
             $crate::seq_parse_tuple_fields!( ($($elements)*) ; ).map(|t| {
                 $crate::seq_init_tuple_fields!(
@@ -84,7 +84,7 @@ macro_rules! seq {
         })
     };
     (( $($elements: tt)* )) => {
-        $crate::trace::trace("tuple", move |input: &mut _| {
+        $crate::combinator::trace("tuple", move |input: &mut _| {
             use $crate::Parser;
             $crate::seq_parse_tuple_fields!( ($($elements)*) ; ).map(|t| {
                 $crate::seq_init_tuple_fields!(

src/token/mod.rs

@@ -3,6 +3,7 @@
 #[cfg(test)]
 mod tests;
 
+use crate::combinator::trace;
 use crate::error::ErrMode;
 use crate::error::ErrorKind;
 use crate::error::Needed;
@@ -11,7 +12,6 @@ use crate::lib::std::result::Result::Ok;
 use crate::stream::Range;
 use crate::stream::{Compare, CompareResult, ContainsToken, FindSlice, SliceLen, Stream};
 use crate::stream::{StreamIsPartial, ToUsize};
-use crate::trace::trace;
 use crate::PResult;
 use crate::Parser;
 

src/trace.rs

@@ -0,0 +1,11 @@
+//! Deprecated, replaced with [`winnow::combinator`][crate::combinator]
+
+/// Deprecated, replaced with [`winnow::combinator::trace`][crate::combinator::trace]
+#[deprecated(since = "0.5.35", note = "Replaced with `winnow::combinator::trace`")]
+#[inline(always)]
+pub fn trace<I: crate::stream::Stream, O, E>(
+    name: impl crate::lib::std::fmt::Display,
+    parser: impl crate::Parser<I, O, E>,
+) -> impl crate::Parser<I, O, E> {
+    crate::combinator::trace(name, parser)
+}