winnow/_topic/error.rs
1//! # Custom Errors
2//!
3//! A lot can be accomplished with the built-in error tools, like:
4//! - [`ContextError`]
5//! - [`Parser::context`]
6//! - [`cut_err`]
7//!
8//! *(see [tutorial][chapter_7])*
9//!
10//! Most other needs can likely be met by using a custom context type with [`ContextError`] instead
11//! of [`StrContext`].
12//! This will require implementing a custom renderer.
13//!
14//! ## `ParserError` Trait
15//!
16//! When needed, you can also create your own type that implements [`ParserError`].
17//!
18//! Optional traits include:
19//! - [`AddContext`]
20//! - [`FromExternalError`]
21//! - [`ErrorConvert`]
22//!
23//! There are multiple strategies for implementing support for [`AddContext`] and [`FromExternalError`]:
24//! - Make your error type generic over the context or external error
25//! - Require a trait for the context or external error and `Box` it
26//! - Make the context an enum like [`StrContext`]
27//! - Implement the trait multiple times, one for each concrete context or external error type,
28//! allowing custom behavior per type
29//!
30//! Example:
31//!```rust
32#![doc = include_str!("../../examples/custom_error.rs")]
33//!```
34
35#![allow(unused_imports)]
36use crate::combinator::cut_err;
37use crate::error::ContextError;
38use crate::error::ErrorConvert;
39use crate::error::StrContext;
40use crate::Parser;
41use crate::_tutorial::chapter_7;
42use crate::error::AddContext;
43use crate::error::FromExternalError;
44use crate::error::ParserError;