diff --git a/src/ascii/mod.rs b/src/ascii/mod.rs index cb1815a3..a2d34a7f 100644 --- a/src/ascii/mod.rs +++ b/src/ascii/mod.rs @@ -61,6 +61,17 @@ impl Caseless<&str> { /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn crlf<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::crlf.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -100,6 +111,17 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn till_line_ending<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::till_line_ending.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -185,6 +207,17 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn line_ending<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::line_ending.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -224,6 +257,17 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn newline(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::newline.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -264,6 +308,17 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn tab(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::tab.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -305,6 +360,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non alphabetic character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn alpha0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::alpha0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -347,6 +413,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non alphabetic character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn alpha1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::alpha1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -389,6 +466,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn digit0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::digit0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -432,6 +520,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn digit1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::digit1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -491,6 +590,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non hexadecimal digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn hex_digit0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::hex_digit0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -534,6 +644,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non hexadecimal digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn hex_digit1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::hex_digit1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -576,6 +697,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non octal digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn oct_digit0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::oct_digit0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -619,6 +751,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non octal digit character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn oct_digit1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::oct_digit1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -661,6 +804,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non alphanumerical character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn alphanumeric0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::alphanumeric0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -703,6 +857,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non alphanumerical character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn alphanumeric1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::alphanumeric1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -745,6 +910,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non space character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn space0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::space0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -774,6 +950,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non space character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn space1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::space1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -816,6 +1003,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non space character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn multispace0<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::multispace0.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -858,6 +1056,17 @@ where /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data, /// or if no terminating token is found (a non space character). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn multispace1<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::ascii::multispace1.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ``` @@ -897,6 +1106,17 @@ where /// *Complete version*: can parse until the end of input. /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. +/// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` into a `u32`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn dec_uint(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::dec_uint.parse_next(input) +/// # } +/// ``` #[doc(alias = "u8")] #[doc(alias = "u16")] #[doc(alias = "u32")] @@ -971,6 +1191,17 @@ impl Uint for usize { /// *Complete version*: can parse until the end of input. /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. +/// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` into an `i32`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn dec_int(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::dec_int.parse_next(input) +/// # } +/// ``` #[doc(alias = "i8")] #[doc(alias = "i16")] #[doc(alias = "i32")] @@ -1053,6 +1284,17 @@ impl Int for isize { /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if end-of-input /// is hit before a hard boundary (non-hex character, more characters than supported). /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` into a `u32`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn hex_uint(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::hex_uint.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -1190,6 +1432,17 @@ impl HexUint for u128 { /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there is not enough data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` into an `f64`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn float(input: &mut &str) -> PResult +/// # { +/// # winnow::ascii::float.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust diff --git a/src/binary/bits/mod.rs b/src/binary/bits/mod.rs index f5865e95..be24d854 100644 --- a/src/binary/bits/mod.rs +++ b/src/binary/bits/mod.rs @@ -148,6 +148,18 @@ where /// Parse taking `count` bits /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::error::ContextError; +/// pub fn take<'i>(count: usize) -> impl Parser<(&'i [u8], usize), u8, ContextError> +/// # { +/// # winnow::binary::bits::take(count) +/// # } +/// ``` +/// /// # Example /// ```rust /// # use winnow::prelude::*; @@ -254,6 +266,18 @@ where /// Parse taking `count` bits and comparing them to `pattern` /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::error::ContextError; +/// pub fn pattern<'i>(pattern: u8, count: usize) -> impl Parser<(&'i [u8], usize), u8, ContextError> +/// # { +/// # winnow::binary::bits::pattern(pattern, count) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -342,6 +366,18 @@ where /// Parses one specific bit as a bool. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::error::ContextError; +/// pub fn bool(input: &mut (&[u8], usize)) -> PResult +/// # { +/// # winnow::binary::bits::bool.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust diff --git a/src/combinator/core.rs b/src/combinator/core.rs index 9b808d6f..0c1647d6 100644 --- a/src/combinator/core.rs +++ b/src/combinator/core.rs @@ -5,6 +5,17 @@ use crate::*; /// Return the remaining input. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn rest<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::combinator::rest.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -28,6 +39,17 @@ where /// /// Note: this does not advance the [`Stream`] /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn rest_len(input: &mut &str) -> PResult +/// # { +/// # winnow::combinator::rest_len.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -170,6 +192,17 @@ where /// /// Otherwise, it will error. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn eof<'i>(input: &mut &'i str) -> PResult<&'i str> +/// # { +/// # winnow::combinator::eof.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust diff --git a/src/stream/mod.rs b/src/stream/mod.rs index 7aa25689..91ce5a48 100644 --- a/src/stream/mod.rs +++ b/src/stream/mod.rs @@ -2688,6 +2688,31 @@ impl crate::lib::std::fmt::Debug for Checkpoi } /// A range bounded inclusively for counting parses performed +/// +/// This is flexible in what can be converted to a [Range]: +/// ```rust +/// # use winnow::prelude::*; +/// # use winnow::token::any; +/// # use winnow::combinator::repeat; +/// # fn inner(input: &mut &str) -> PResult { +/// # any.parse_next(input) +/// # } +/// # let mut input = "0123456789012345678901234567890123456789"; +/// # let input = &mut input; +/// let parser: Vec<_> = repeat(5, inner).parse_next(input).unwrap(); +/// # let mut input = "0123456789012345678901234567890123456789"; +/// # let input = &mut input; +/// let parser: Vec<_> = repeat(.., inner).parse_next(input).unwrap(); +/// # let mut input = "0123456789012345678901234567890123456789"; +/// # let input = &mut input; +/// let parser: Vec<_> = repeat(1.., inner).parse_next(input).unwrap(); +/// # let mut input = "0123456789012345678901234567890123456789"; +/// # let input = &mut input; +/// let parser: Vec<_> = repeat(5..8, inner).parse_next(input).unwrap(); +/// # let mut input = "0123456789012345678901234567890123456789"; +/// # let input = &mut input; +/// let parser: Vec<_> = repeat(5..=8, inner).parse_next(input).unwrap(); +/// ``` #[derive(PartialEq, Eq)] pub struct Range { pub(crate) start_inclusive: usize, diff --git a/src/token/mod.rs b/src/token/mod.rs index 804bfa3b..f6338af8 100644 --- a/src/token/mod.rs +++ b/src/token/mod.rs @@ -22,6 +22,17 @@ use crate::Parser; /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// pub fn any(input: &mut &str) -> PResult +/// # { +/// # winnow::token::any.parse_next(input) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -85,11 +96,23 @@ where /// **Note:** [`Parser`] is implemented for strings and byte strings as a convenience (complete /// only) /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::error::ContextError; +/// pub fn literal(literal: &str) -> impl Parser<&str, &str, ContextError> +/// # { +/// # winnow::token::literal(literal) +/// # } +/// ``` +/// /// # Example /// ```rust /// # use winnow::prelude::*; /// # use winnow::{error::ErrMode, error::{InputError, ErrorKind}, error::Needed}; -/// +/// # /// fn parser(s: &str) -> IResult<&str, &str> { /// "Hello".parse_peek(s) /// } @@ -185,6 +208,19 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::stream::ContainsToken; +/// # use winnow::error::ContextError; +/// pub fn one_of<'i>(set: impl ContainsToken) -> impl Parser<&'i str, char, ContextError> +/// # { +/// # winnow::token::one_of(set) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -242,6 +278,19 @@ where /// /// *Partial version*: Will return `Err(winnow::error::ErrMode::Incomplete(_))` if there's not enough input data. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str`: +/// ```rust +/// # use winnow::prelude::*;; +/// # use winnow::stream::ContainsToken; +/// # use winnow::error::ContextError; +/// pub fn none_of<'i>(set: impl ContainsToken) -> impl Parser<&'i str, char, ContextError> +/// # { +/// # winnow::token::none_of(set) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -285,6 +334,20 @@ where /// /// To recognize a series of tokens, use [`repeat`][crate::combinator::repeat] to [`Accumulate`][crate::stream::Accumulate] into a `()` and then [`Parser::recognize`]. /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` with `0..` or `1..` ranges: +/// ```rust +/// # use std::ops::RangeFrom; +/// # use winnow::prelude::*; +/// # use winnow::stream::ContainsToken; +/// # use winnow::error::ContextError; +/// pub fn take_while<'i>(occurrences: RangeFrom, set: impl ContainsToken) -> impl Parser<&'i str, &'i str, ContextError> +/// # { +/// # winnow::token::take_while(occurrences, set) +/// # } +/// ``` +/// /// # Example /// /// Zero or more tokens: @@ -645,6 +708,20 @@ where /// - [`take_until`] for recognizing up-to a [`literal`] (w/ optional simd optimizations) /// - [`repeat_till`][crate::combinator::repeat_till] with [`Parser::recognize`] for recognizing up to a [`Parser`] /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` with `0..` or `1..` [ranges][Range]: +/// ```rust +/// # use std::ops::RangeFrom; +/// # use winnow::prelude::*; +/// # use winnow::stream::ContainsToken; +/// # use winnow::error::ContextError; +/// pub fn take_till<'i>(occurrences: RangeFrom, set: impl ContainsToken) -> impl Parser<&'i str, &'i str, ContextError> +/// # { +/// # winnow::token::take_till(occurrences, set) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -731,6 +808,20 @@ where /// but for types like `&str`, we cannot know how many bytes correspond for /// the next few chars, so the result will be `ErrMode::Incomplete(Needed::Unknown)` /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` with `0..` or `1..` ranges: +/// ```rust +/// # use std::ops::RangeFrom; +/// # use winnow::prelude::*; +/// # use winnow::stream::ContainsToken; +/// # use winnow::error::ContextError; +/// pub fn take<'i>(token_count: usize) -> impl Parser<&'i str, &'i str, ContextError> +/// # { +/// # winnow::token::take(token_count) +/// # } +/// ``` +/// /// # Example /// /// ```rust @@ -778,14 +869,14 @@ where /// ``` #[inline(always)] pub fn take( - count: UsizeLike, + token_count: UsizeLike, ) -> impl Parser::Slice, Error> where Input: StreamIsPartial + Stream, UsizeLike: ToUsize, Error: ParserError, { - let c = count.to_usize(); + let c = token_count.to_usize(); trace("take", move |i: &mut Input| { if ::is_partial_supported() { take_::<_, _, true>(i, c) @@ -826,6 +917,19 @@ where /// - [`take_till`] for recognizing up-to a [set of tokens][ContainsToken] /// - [`repeat_till`][crate::combinator::repeat_till] with [`Parser::recognize`] for recognizing up to a [`Parser`] /// +/// # Effective Signature +/// +/// Assuming you are parsing `&str` with `0..` or `1..` ranges: +/// ```rust +/// # use std::ops::RangeFrom; +/// # use winnow::prelude::*;; +/// # use winnow::error::ContextError; +/// pub fn take_until(occurrences: RangeFrom, literal: &str) -> impl Parser<&str, &str, ContextError> +/// # { +/// # winnow::token::take_until(occurrences, literal) +/// # } +/// ``` +/// /// # Example /// /// ```rust