From c3849179f76d03de45059ed6c1a2f3e0a7c578f0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Jan 2025 20:37:18 -0600 Subject: [PATCH 1/5] refactor(comb): Rename 'parser' to 'impls' --- src/combinator/{parser.rs => impls.rs} | 0 src/combinator/mod.rs | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) rename src/combinator/{parser.rs => impls.rs} (100%) diff --git a/src/combinator/parser.rs b/src/combinator/impls.rs similarity index 100% rename from src/combinator/parser.rs rename to src/combinator/impls.rs diff --git a/src/combinator/mod.rs b/src/combinator/mod.rs index df791ada..b8f5e0cc 100644 --- a/src/combinator/mod.rs +++ b/src/combinator/mod.rs @@ -162,8 +162,8 @@ mod branch; mod core; mod debug; +mod impls; mod multi; -mod parser; mod sequence; #[cfg(test)] @@ -172,8 +172,8 @@ mod tests; pub use self::branch::*; pub use self::core::*; pub use self::debug::*; +pub use self::impls::*; pub use self::multi::*; -pub use self::parser::*; pub use self::sequence::*; #[allow(unused_imports)] From 89dcf860beaf3017f5249bdb9bea46dc809e24a2 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Jan 2025 20:39:46 -0600 Subject: [PATCH 2/5] fix(comb): Deprecate top-level opaque impls --- src/combinator/impls.rs | 2 ++ src/combinator/mod.rs | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/combinator/impls.rs b/src/combinator/impls.rs index 3502cfa4..adb4c5be 100644 --- a/src/combinator/impls.rs +++ b/src/combinator/impls.rs @@ -1,3 +1,5 @@ +//! Opaque implementations of [`Parser`] + use crate::combinator::trace; use crate::combinator::trace_result; use crate::combinator::DisplayDebug; diff --git a/src/combinator/mod.rs b/src/combinator/mod.rs index b8f5e0cc..a7f540c5 100644 --- a/src/combinator/mod.rs +++ b/src/combinator/mod.rs @@ -162,16 +162,18 @@ mod branch; mod core; mod debug; -mod impls; mod multi; mod sequence; #[cfg(test)] mod tests; +pub mod impls; + pub use self::branch::*; pub use self::core::*; pub use self::debug::*; +#[deprecated(since = "0.6.23", note = "Replaced with `combinator::impls`")] pub use self::impls::*; pub use self::multi::*; pub use self::sequence::*; From 01113c5952408b2580af3d5c333118eba75230e1 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Jan 2025 20:41:40 -0600 Subject: [PATCH 3/5] refactor: Update for impls wildcard import deprecation --- src/parser.rs | 96 +++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/src/parser.rs b/src/parser.rs index cb325be4..35c566c0 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -1,7 +1,7 @@ //! Basic types to build the parsers use crate::ascii::Caseless as AsciiCaseless; -use crate::combinator::*; +use crate::combinator::impls; #[cfg(feature = "unstable-recover")] #[cfg(feature = "std")] use crate::error::FromRecoverableError; @@ -91,7 +91,7 @@ pub trait Parser { /// - Migrating from older versions / `nom` /// - Testing [`Parser`]s /// - /// For look-ahead parsing, see instead [`peek`]. + /// For look-ahead parsing, see instead [`peek`][crate::combinator::peek]. /// /// #[inline(always)] @@ -146,11 +146,11 @@ pub trait Parser { /// } /// ``` #[inline(always)] - fn by_ref(&mut self) -> ByRef<'_, Self> + fn by_ref(&mut self) -> impls::ByRef<'_, Self> where Self: core::marker::Sized, { - ByRef { p: self } + impls::ByRef { p: self } } /// Produce the provided value @@ -170,12 +170,12 @@ pub trait Parser { /// ``` #[doc(alias = "to")] #[inline(always)] - fn value(self, val: O2) -> Value + fn value(self, val: O2) -> impls::Value where Self: core::marker::Sized, O2: Clone, { - Value { + impls::Value { parser: self, val, i: Default::default(), @@ -200,12 +200,12 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn default_value(self) -> DefaultValue + fn default_value(self) -> impls::DefaultValue where Self: core::marker::Sized, O2: core::default::Default, { - DefaultValue { + impls::DefaultValue { parser: self, o2: Default::default(), i: Default::default(), @@ -230,11 +230,11 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn void(self) -> Void + fn void(self) -> impls::Void where Self: core::marker::Sized, { - Void { + impls::Void { parser: self, i: Default::default(), o: Default::default(), @@ -264,12 +264,12 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn output_into(self) -> OutputInto + fn output_into(self) -> impls::OutputInto where Self: core::marker::Sized, O: Into, { - OutputInto { + impls::OutputInto { parser: self, i: Default::default(), o: Default::default(), @@ -297,12 +297,12 @@ pub trait Parser { #[doc(alias = "concat")] #[doc(alias = "recognize")] #[inline(always)] - fn take(self) -> Take + fn take(self) -> impls::Take where Self: core::marker::Sized, I: Stream, { - Take { + impls::Take { parser: self, i: Default::default(), o: Default::default(), @@ -313,12 +313,12 @@ pub trait Parser { /// Replaced with [`Parser::take`] #[inline(always)] #[deprecated(since = "0.6.14", note = "Replaced with `Parser::take`")] - fn recognize(self) -> Take + fn recognize(self) -> impls::Take where Self: core::marker::Sized, I: Stream, { - Take { + impls::Take { parser: self, i: Default::default(), o: Default::default(), @@ -365,12 +365,12 @@ pub trait Parser { #[doc(alias = "consumed")] #[doc(alias = "with_recognized")] #[inline(always)] - fn with_taken(self) -> WithTaken + fn with_taken(self) -> impls::WithTaken where Self: core::marker::Sized, I: Stream, { - WithTaken { + impls::WithTaken { parser: self, i: Default::default(), o: Default::default(), @@ -381,12 +381,12 @@ pub trait Parser { /// Replaced with [`Parser::with_taken`] #[inline(always)] #[deprecated(since = "0.6.14", note = "Replaced with `Parser::with_taken`")] - fn with_recognized(self) -> WithTaken + fn with_recognized(self) -> impls::WithTaken where Self: core::marker::Sized, I: Stream, { - WithTaken { + impls::WithTaken { parser: self, i: Default::default(), o: Default::default(), @@ -411,12 +411,12 @@ pub trait Parser { /// assert_eq!(parser.parse_peek(LocatingSlice::new("abcd;")),Err(ErrMode::Backtrack(InputError::new(LocatingSlice::new("abcd;").peek_slice(4).0, ErrorKind::Tag)))); /// ``` #[inline(always)] - fn span(self) -> Span + fn span(self) -> impls::Span where Self: core::marker::Sized, I: Stream + Location, { - Span { + impls::Span { parser: self, i: Default::default(), o: Default::default(), @@ -465,12 +465,12 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn with_span(self) -> WithSpan + fn with_span(self) -> impls::WithSpan where Self: core::marker::Sized, I: Stream + Location, { - WithSpan { + impls::WithSpan { parser: self, i: Default::default(), o: Default::default(), @@ -497,12 +497,12 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn map(self, map: G) -> Map + fn map(self, map: G) -> impls::Map where G: FnMut(O) -> O2, Self: core::marker::Sized, { - Map { + impls::Map { parser: self, map, i: Default::default(), @@ -534,14 +534,14 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn try_map(self, map: G) -> TryMap + fn try_map(self, map: G) -> impls::TryMap where Self: core::marker::Sized, G: FnMut(O) -> Result, I: Stream, E: FromExternalError, { - TryMap { + impls::TryMap { parser: self, map, i: Default::default(), @@ -577,14 +577,14 @@ pub trait Parser { #[doc(alias = "filter_map")] #[doc(alias = "map_opt")] #[inline(always)] - fn verify_map(self, map: G) -> VerifyMap + fn verify_map(self, map: G) -> impls::VerifyMap where Self: core::marker::Sized, G: FnMut(O) -> Option, I: Stream, E: ParserError, { - VerifyMap { + impls::VerifyMap { parser: self, map, i: Default::default(), @@ -627,13 +627,13 @@ pub trait Parser { /// assert_eq!(length_take.parse_peek(&[4, 0, 1, 2][..]), Err(ErrMode::Backtrack(InputError::new(&[0, 1, 2][..], ErrorKind::Slice)))); /// ``` #[inline(always)] - fn flat_map(self, map: G) -> FlatMap + fn flat_map(self, map: G) -> impls::FlatMap where Self: core::marker::Sized, G: FnMut(O) -> H, H: Parser, { - FlatMap { + impls::FlatMap { f: self, g: map, h: Default::default(), @@ -662,14 +662,14 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn and_then(self, inner: G) -> AndThen + fn and_then(self, inner: G) -> impls::AndThen where Self: core::marker::Sized, G: Parser, O: StreamIsPartial, I: Stream, { - AndThen { + impls::AndThen { outer: self, inner, i: Default::default(), @@ -700,14 +700,14 @@ pub trait Parser { /// ``` #[doc(alias = "from_str")] #[inline(always)] - fn parse_to(self) -> ParseTo + fn parse_to(self) -> impls::ParseTo where Self: core::marker::Sized, I: Stream, O: ParseSlice, E: ParserError, { - ParseTo { + impls::ParseTo { p: self, i: Default::default(), o: Default::default(), @@ -738,7 +738,7 @@ pub trait Parser { #[doc(alias = "satisfy")] #[doc(alias = "filter")] #[inline(always)] - fn verify(self, filter: G) -> Verify + fn verify(self, filter: G) -> impls::Verify where Self: core::marker::Sized, G: FnMut(&O2) -> bool, @@ -747,7 +747,7 @@ pub trait Parser { O2: ?Sized, E: ParserError, { - Verify { + impls::Verify { parser: self, filter, i: Default::default(), @@ -763,14 +763,14 @@ pub trait Parser { /// to errors when backtracking through a parse tree. #[doc(alias = "labelled")] #[inline(always)] - fn context(self, context: C) -> Context + fn context(self, context: C) -> impls::Context where Self: core::marker::Sized, I: Stream, E: AddContext, C: Clone + crate::lib::std::fmt::Debug, { - Context { + impls::Context { parser: self, context, i: Default::default(), @@ -795,21 +795,21 @@ pub trait Parser { /// # } /// ``` #[inline(always)] - fn complete_err(self) -> CompleteErr + fn complete_err(self) -> impls::CompleteErr where Self: core::marker::Sized, { - CompleteErr { f: self } + impls::CompleteErr { f: self } } /// Convert the parser's error to another type using [`std::convert::From`] #[inline(always)] - fn err_into(self) -> ErrInto + fn err_into(self) -> impls::ErrInto where Self: core::marker::Sized, E: Into, { - ErrInto { + impls::ErrInto { parser: self, i: Default::default(), o: Default::default(), @@ -828,7 +828,7 @@ pub trait Parser { #[inline(always)] #[cfg(feature = "unstable-recover")] #[cfg(feature = "std")] - fn retry_after(self, recover: R) -> RetryAfter + fn retry_after(self, recover: R) -> impls::RetryAfter where Self: core::marker::Sized, R: Parser, @@ -836,7 +836,7 @@ pub trait Parser { I: Recover, E: FromRecoverableError, { - RetryAfter { + impls::RetryAfter { parser: self, recover, i: Default::default(), @@ -852,7 +852,7 @@ pub trait Parser { #[inline(always)] #[cfg(feature = "unstable-recover")] #[cfg(feature = "std")] - fn resume_after(self, recover: R) -> ResumeAfter + fn resume_after(self, recover: R) -> impls::ResumeAfter where Self: core::marker::Sized, R: Parser, @@ -860,7 +860,7 @@ pub trait Parser { I: Recover, E: FromRecoverableError, { - ResumeAfter { + impls::ResumeAfter { parser: self, recover, i: Default::default(), From a0b644e55e550d4ea79d9aa3e94f76c6e835573c Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 6 Jan 2025 09:15:50 -0600 Subject: [PATCH 4/5] docs(parser): Clarify what the opaque impls do --- src/combinator/impls.rs | 42 ++++++++++++++++++++--------------------- src/combinator/multi.rs | 2 +- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/combinator/impls.rs b/src/combinator/impls.rs index adb4c5be..648dc15c 100644 --- a/src/combinator/impls.rs +++ b/src/combinator/impls.rs @@ -16,7 +16,7 @@ use crate::stream::StreamIsPartial; use crate::stream::{Location, Stream}; use crate::*; -/// Implementation of [`Parser::by_ref`] +/// [`Parser`] implementation for [`Parser::by_ref`] pub struct ByRef<'p, P> { pub(crate) p: &'p mut P, } @@ -31,7 +31,7 @@ where } } -/// Implementation of [`Parser::map`] +/// [`Parser`] implementation for [`Parser::map`] pub struct Map where F: Parser, @@ -59,7 +59,7 @@ where } } -/// Implementation of [`Parser::try_map`] +/// [`Parser`] implementation for [`Parser::try_map`] pub struct TryMap where F: Parser, @@ -96,7 +96,7 @@ where } } -/// Implementation of [`Parser::verify_map`] +/// [`Parser`] implementation for [`Parser::verify_map`] pub struct VerifyMap where F: Parser, @@ -132,7 +132,7 @@ where } } -/// Implementation of [`Parser::and_then`] +/// [`Parser`] implementation for [`Parser::and_then`] pub struct AndThen where F: Parser, @@ -168,7 +168,7 @@ where } } -/// Implementation of [`Parser::parse_to`] +/// [`Parser`] implementation for [`Parser::parse_to`] pub struct ParseTo where P: Parser, @@ -203,7 +203,7 @@ where } } -/// Implementation of [`Parser::flat_map`] +/// [`Parser`] implementation for [`Parser::flat_map`] pub struct FlatMap where F: Parser, @@ -232,7 +232,7 @@ where } } -/// Implementation of [`Parser::complete_err`] +/// [`Parser`] implementation for [`Parser::complete_err`] pub struct CompleteErr { pub(crate) f: F, } @@ -257,7 +257,7 @@ where } } -/// Implementation of [`Parser::verify`] +/// [`Parser`] implementation for [`Parser::verify`] pub struct Verify where F: Parser, @@ -297,7 +297,7 @@ where } } -/// Implementation of [`Parser::value`] +/// [`Parser`] implementation for [`Parser::value`] pub struct Value where F: Parser, @@ -321,7 +321,7 @@ where } } -/// Implementation of [`Parser::default_value`] +/// [`Parser`] implementation for [`Parser::default_value`] pub struct DefaultValue where F: Parser, @@ -345,7 +345,7 @@ where } } -/// Implementation of [`Parser::void`] +/// [`Parser`] implementation for [`Parser::void`] pub struct Void where F: Parser, @@ -370,7 +370,7 @@ where #[deprecated(since = "0.6.14", note = "Replaced with `Take`")] pub type Recognize = Take; -/// Implementation of [`Parser::take`] +/// [`Parser`] implementation for [`Parser::take`] pub struct Take where F: Parser, @@ -406,7 +406,7 @@ where #[deprecated(since = "0.6.14", note = "Replaced with `WithTaken`")] pub type WithRecognized = WithTaken; -/// Implementation of [`Parser::with_taken`] +/// [`Parser`] implementation for [`Parser::with_taken`] pub struct WithTaken where F: Parser, @@ -438,7 +438,7 @@ where } } -/// Implementation of [`Parser::span`] +/// [`Parser`] implementation for [`Parser::span`] pub struct Span where F: Parser, @@ -465,7 +465,7 @@ where } } -/// Implementation of [`Parser::with_span`] +/// [`Parser`] implementation for [`Parser::with_span`] pub struct WithSpan where F: Parser, @@ -492,7 +492,7 @@ where } } -/// Implementation of [`Parser::output_into`] +/// [`Parser`] implementation for [`Parser::output_into`] pub struct OutputInto where F: Parser, @@ -516,7 +516,7 @@ where } } -/// Implementation of [`Parser::err_into`] +/// [`Parser`] implementation for [`Parser::err_into`] pub struct ErrInto where F: Parser, @@ -545,7 +545,7 @@ where } } -/// Implementation of [`Parser::context`] +/// [`Parser`] implementation for [`Parser::context`] pub struct Context where F: Parser, @@ -580,7 +580,7 @@ where } } -/// Implementation of [`Parser::retry_after`] +/// [`Parser`] implementation for [`Parser::retry_after`] #[cfg(feature = "unstable-recover")] #[cfg(feature = "std")] pub struct RetryAfter @@ -656,7 +656,7 @@ where } } -/// Implementation of [`Parser::resume_after`] +/// [`Parser`] implementation for [`Parser::resume_after`] #[cfg(feature = "unstable-recover")] #[cfg(feature = "std")] pub struct ResumeAfter diff --git a/src/combinator/multi.rs b/src/combinator/multi.rs index 0c1593a4..ae459952 100644 --- a/src/combinator/multi.rs +++ b/src/combinator/multi.rs @@ -132,7 +132,7 @@ where } } -/// Implementation of [`repeat`] +/// [`Parser`] implementation for [`repeat`] pub struct Repeat where P: Parser, From 010d73e3dedf45975a191510c5fe705d68a1a55a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 6 Jan 2025 09:18:18 -0600 Subject: [PATCH 5/5] docs(comb): Clarify Repeat is not just opaque --- src/combinator/multi.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/combinator/multi.rs b/src/combinator/multi.rs index ae459952..d91ac3ee 100644 --- a/src/combinator/multi.rs +++ b/src/combinator/multi.rs @@ -132,7 +132,7 @@ where } } -/// [`Parser`] implementation for [`repeat`] +/// Customizable [`Parser`] implementation for [`repeat`] pub struct Repeat where P: Parser,