1//! > winnow, making parsing a breeze
2//!
3//! `winnow` is a parser combinator library
4//!
5//! Quick links:
6//! - [List of combinators][crate::combinator]
7//! - [Tutorial][_tutorial::chapter_0]
8//! - [Special Topics][_topic]
9//! - [Discussions](https://github.com/winnow-rs/winnow/discussions)
10//! - [CHANGELOG](https://github.com/winnow-rs/winnow/blob/v0.7.6/CHANGELOG.md) (includes major version migration
11//! guides)
12//!
13//! ## Aspirations
14//!
15//! `winnow` aims to be your "do everything" parser, much like people treat regular expressions.
16//!
17//! In roughly priority order:
18//! 1. Support writing parser declaratively while not getting in the way of imperative-style
19//! parsing when needed, working as an open-ended toolbox rather than a close-ended framework.
20//! 2. Flexible enough to be used for any application, including parsing binary data, strings, or
21//! separate lexing and parsing phases
22//! 3. Zero-cost abstractions, making it easy to write high performance parsers
23//! 4. Easy to use, making it trivial for one-off uses
24//!
25//! In addition:
26//! - Resilient maintainership, including
27//! - Willing to break compatibility rather than batching up breaking changes in large releases
28//! - Leverage feature flags to keep one active branch
29//! - We will support the last 6 months of rust releases (MSRV, currently 1.64.0)
30//!
31//! See also [Special Topic: Why winnow?][crate::_topic::why]
32//!
33//! ## Example
34//!
35//! Run
36//! ```console
37//! $ cargo add winnow
38//! ```
39//!
40//! Then use it to parse:
41//! ```rust
42//! # #[cfg(feature = "alloc")] {
43#![doc = include_str!("../examples/css/parser.rs")]
44//! # }
45//! ```
46//!
47//! See also the [Tutorial][_tutorial::chapter_0] and [Special Topics][_topic]
48
49#![cfg_attr(docsrs, feature(doc_auto_cfg))]
50#![cfg_attr(docsrs, feature(doc_cfg))]
51#![cfg_attr(docsrs, feature(extended_key_value_attributes))]
52#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
53#![warn(missing_docs)]
54#![warn(clippy::std_instead_of_core)]
55#![warn(clippy::print_stderr)]
56#![warn(clippy::print_stdout)]
57
58#[cfg(feature = "alloc")]
59#[cfg_attr(test, macro_use)]
60#[allow(unused_extern_crates)]
61extern crate alloc;
62
63#[doc = include_str!("../README.md")]
64#[cfg(doctest)]
65pub struct ReadmeDoctests;
66
67/// Lib module to re-export everything needed from `std` or `core`/`alloc`. This is how `serde` does
68/// it, albeit there it is not public.
69#[doc(hidden)]
70pub(crate) mod lib {
71 #![allow(unused_imports)]
72
73 /// `std` facade allowing `std`/`core` to be interchangeable. Reexports `alloc` crate optionally,
74 /// as well as `core` or `std`
75 #[cfg(not(feature = "std"))]
76 /// internal std exports for no_std compatibility
77 pub(crate) mod std {
78 #[doc(hidden)]
79 #[cfg(not(feature = "alloc"))]
80 pub(crate) use core::borrow;
81
82 #[cfg(feature = "alloc")]
83 #[doc(hidden)]
84 pub(crate) use alloc::{borrow, boxed, collections, string, vec};
85
86 #[doc(hidden)]
87 pub(crate) use core::{
88 cmp, convert, fmt, hash, iter, mem, ops, option, result, slice, str,
89 };
90 }
91
92 #[cfg(feature = "std")]
93 /// internal std exports for `no_std` compatibility
94 pub(crate) mod std {
95 #![allow(clippy::std_instead_of_core)]
96 #[doc(hidden)]
97 pub(crate) use std::{
98 borrow, boxed, cmp, collections, convert, fmt, hash, iter, mem, ops, result, slice,
99 str, string, vec,
100 };
101 }
102}
103
104#[macro_use]
105mod macros;
106
107#[macro_use]
108pub mod error;
109
110mod parser;
111
112pub mod stream;
113
114pub mod ascii;
115pub mod binary;
116pub mod combinator;
117pub mod token;
118
119#[cfg(feature = "unstable-doc")]
120pub mod _topic;
121#[cfg(feature = "unstable-doc")]
122pub mod _tutorial;
123
124/// Core concepts available for glob import
125///
126/// Including
127/// - [`StreamIsPartial`][crate::stream::StreamIsPartial]
128/// - [`Parser`]
129///
130/// ## Example
131///
132/// ```rust
133/// use winnow::prelude::*;
134///
135/// fn parse_data(input: &mut &str) -> ModalResult<u64> {
136/// // ...
137/// # winnow::ascii::dec_uint(input)
138/// }
139///
140/// fn main() {
141/// let result = parse_data.parse("100");
142/// assert_eq!(result, Ok(100));
143/// }
144/// ```
145pub mod prelude {
146 pub use crate::error::ModalError as _;
147 pub use crate::error::ParserError as _;
148 pub use crate::stream::AsChar as _;
149 pub use crate::stream::ContainsToken as _;
150 pub use crate::stream::Stream as _;
151 pub use crate::stream::StreamIsPartial as _;
152 pub use crate::ModalParser;
153 pub use crate::ModalResult;
154 pub use crate::Parser;
155 #[cfg(feature = "unstable-recover")]
156 #[cfg(feature = "std")]
157 pub use crate::RecoverableParser as _;
158
159 #[cfg(test)]
160 pub(crate) use crate::TestResult;
161}
162
163pub use error::ModalResult;
164pub use error::Result;
165pub use parser::*;
166pub use stream::BStr;
167pub use stream::Bytes;
168pub use stream::LocatingSlice;
169pub use stream::Partial;
170pub use stream::Stateful;
171pub use stream::Str;
172
173#[cfg(test)]
174pub(crate) use error::TestResult;
175