combine/parser/mod.rs
1//! A collection of both concrete parsers as well as parser combinators.
2//!
3//! Implements the [`Parser`] trait which is the core of `combine` and contains the submodules
4//! implementing all combine parsers.
5
6use crate::{
7 error::{
8 ErrorInfo, ParseError,
9 ParseResult::{self, *},
10 ResultExt, StreamError, Token, Tracked,
11 },
12 parser::{
13 combinator::{
14 and_then, flat_map, map, map_input, spanned, AndThen, Either, FlatMap, Map, MapInput,
15 Spanned,
16 },
17 error::{expected, message, silent, Expected, Message, Silent},
18 repeat::Iter,
19 sequence::{then, then_partial, then_ref, Then, ThenPartial, ThenRef},
20 },
21 stream::{Stream, StreamErrorFor, StreamOnce},
22 ErrorOffset,
23};
24
25use self::{
26 choice::{or, Or},
27 sequence::{skip, with, Skip, With},
28};
29
30#[cfg(feature = "alloc")]
31use alloc::boxed::Box;
32
33/// Internal API. May break without a semver bump
34#[macro_export]
35#[doc(hidden)]
36macro_rules! parse_mode {
37 ($input_type: ty) => {
38 #[inline]
39 fn parse_partial(
40 &mut self,
41 input: &mut $input_type,
42 state: &mut Self::PartialState,
43 ) -> $crate::error::ParseResult<Self::Output, <$input_type as $crate::StreamOnce>::Error> {
44 self.parse_mode($crate::parser::PartialMode::default(), input, state)
45 }
46
47 #[inline]
48 fn parse_first(
49 &mut self,
50 input: &mut $input_type,
51 state: &mut Self::PartialState,
52 ) -> $crate::error::ParseResult<Self::Output, <$input_type as $crate::StreamOnce>::Error> {
53 self.parse_mode($crate::parser::FirstMode, input, state)
54 }
55 };
56}
57
58pub mod byte;
59pub mod char;
60pub mod choice;
61pub mod combinator;
62pub mod error;
63pub mod function;
64pub mod range;
65#[cfg(feature = "regex")]
66#[cfg_attr(docsrs, doc(cfg(feature = "regex")))]
67pub mod regex;
68pub mod repeat;
69pub mod sequence;
70pub mod token;
71
72/// By implementing the `Parser` trait a type says that it can be used to parse an input stream
73/// into the type `Output`.
74///
75/// All methods have a default implementation but there needs to be at least an implementation of
76/// [`parse_stream`], [`parse_stream`], or [`parse_lazy`]. If the last is implemented, an
77/// implementation of [`add_error`] may also be required. See the documentation for
78/// [`parse_lazy`] for details.
79///
80/// [`parse_stream`]: trait.Parser.html#method.parse_stream
81/// [`parse_stream`]: trait.Parser.html#method.parse_stream
82/// [`parse_lazy`]: trait.Parser.html#method.parse_lazy
83/// [`add_error`]: trait.Parser.html#method.add_error
84pub trait Parser<Input: Stream> {
85 /// The type which is returned if the parser is successful.
86 type Output;
87
88 /// Determines the state necessary to resume parsing after more input is supplied.
89 ///
90 /// If partial parsing is not supported this can be set to `()`.
91 type PartialState: Default;
92
93 /// Entry point of the parser. Takes some input and tries to parse it.
94 ///
95 /// Returns the parsed result and the remaining input if the parser succeeds, or a
96 /// error otherwise.
97 ///
98 /// This is the most straightforward entry point to a parser. Since it does not decorate the
99 /// input in any way you may find the error messages a hard to read. If that is the case you
100 /// may want to try wrapping your input with an [`easy::Stream`] or call [`easy_parse`]
101 /// instead.
102 ///
103 /// [`easy::Stream`]: super::easy::Stream
104 /// [`easy_parse`]: super::parser::EasyParser::easy_parse
105 fn parse(
106 &mut self,
107 mut input: Input,
108 ) -> Result<(Self::Output, Input), <Input as StreamOnce>::Error> {
109 match self.parse_stream(&mut input).into() {
110 Ok((v, _)) => Ok((v, input)),
111 Err(error) => Err(error.into_inner().error),
112 }
113 }
114
115 /// Entry point of the parser when using partial parsing.
116 /// Takes some input and tries to parse it.
117 ///
118 /// Returns the parsed result and the remaining input if the parser succeeds, or a
119 /// error otherwise.
120 fn parse_with_state(
121 &mut self,
122 input: &mut Input,
123 state: &mut Self::PartialState,
124 ) -> Result<Self::Output, <Input as StreamOnce>::Error> {
125 match self.parse_stream_partial(input, state).into() {
126 Ok((v, _)) => Ok(v),
127 Err(error) => Err(error.into_inner().error),
128 }
129 }
130
131 /// Parses using the stream `input` by calling [`Stream::uncons`] one or more times.
132 ///
133 /// Semantically equivalent to [`parse_stream`], except this method returns a flattened result
134 /// type, combining `Result` and [`Commit`] into a single [`ParseResult`].
135 ///
136 /// [`Stream::uncons`]: super::stream::StreamOnce::uncons
137 /// [`parse_stream`]: Parser::parse_stream
138 /// [`Commit`]: super::error::Commit
139 /// [`ParseResult`]: super::error::ParseResult
140 #[inline]
141 fn parse_stream(
142 &mut self,
143 input: &mut Input,
144 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
145 let before = input.checkpoint();
146 let mut state = Default::default();
147 let mut result = self.parse_first(input, &mut state);
148 if let ParseResult::PeekErr(ref mut error) = result {
149 ctry!(input.reset(before.clone()).committed());
150 if let Ok(t) = input.uncons() {
151 ctry!(input.reset(before).committed());
152 error.error.add_unexpected(Token(t));
153 } else {
154 error.error.add(StreamErrorFor::<Input>::end_of_input());
155 }
156 self.add_error(error);
157 }
158 result
159 }
160
161 /// Parses using the stream `input` by calling [`Stream::uncons`] one or more times.
162 ///
163 /// Specialized version of [`parse_stream`] which permits error value creation to be
164 /// skipped in the common case.
165 ///
166 /// When this parser returns `PeekErr`, this method is allowed to return an empty
167 /// [`Error`]. The error value that would have been returned can instead be obtained by
168 /// calling [`add_error`]. This allows a parent parser such as `choice` to skip the creation of
169 /// an unnecessary error value, if an alternative parser succeeds.
170 ///
171 /// Parsers should seek to implement this function instead of the above two if errors can be
172 /// encountered before consuming input. The default implementation always returns all errors,
173 /// with [`add_error`] being a no-op.
174 ///
175 /// [`Stream::uncons`]: super::stream::StreamOnce::uncons
176 /// [`parse_stream`]: Parser::parse_stream
177 /// [`Error`]: super::stream::StreamOnce::Error
178 /// [`add_error`]: trait.Parser.html#method.add_error
179 #[inline]
180 fn parse_lazy(
181 &mut self,
182 input: &mut Input,
183 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
184 if input.is_partial() {
185 // If a partial parser were called from a non-partial parser (as it is here) we must
186 // reset the input to before the partial parser were called on errors that committed
187 // data as that parser's partial state was just temporary and it will not be able to
188 // resume itself
189 let before = input.checkpoint();
190 let result = self.parse_first(input, &mut Default::default());
191 if let CommitErr(_) = result {
192 ctry!(input.reset(before).committed());
193 }
194 result
195 } else {
196 self.parse_first(input, &mut Default::default())
197 }
198 }
199
200 /// Adds the first error that would normally be returned by this parser if it failed with an
201 /// `PeekErr` result.
202 ///
203 /// See [`parse_lazy`] for details.
204 ///
205 /// [`parse_lazy`]: trait.Parser.html#method.parse_lazy
206 fn add_error(&mut self, _error: &mut Tracked<<Input as StreamOnce>::Error>) {}
207
208 /// Like `parse_stream` but supports partial parsing.
209 #[inline]
210 fn parse_stream_partial(
211 &mut self,
212 input: &mut Input,
213 state: &mut Self::PartialState,
214 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
215 let before = input.checkpoint();
216 let mut result = self.parse_partial(input, state);
217 if let ParseResult::PeekErr(ref mut error) = result {
218 ctry!(input.reset(before.clone()).committed());
219 if let Ok(t) = input.uncons() {
220 ctry!(input.reset(before).committed());
221 error.error.add_unexpected(Token(t));
222 } else {
223 error.error.add(StreamErrorFor::<Input>::end_of_input());
224 }
225 self.add_error(error);
226 }
227 result
228 }
229
230 /// Parses using the stream `input` and allows itself to be resumed at a later point using
231 /// `parse_partial` by storing the necessary intermediate state in `state`.
232 ///
233 /// Unlike `parse_partial` function this is allowed to assume that there is no partial state to
234 /// resume.
235 ///
236 /// Internal API. May break without a semver bump
237 /// Always overridden by the `parse_mode!` macro
238 #[inline]
239 #[doc(hidden)]
240 fn parse_first(
241 &mut self,
242 input: &mut Input,
243 state: &mut Self::PartialState,
244 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
245 self.parse_partial(input, state)
246 }
247
248 /// Parses using the stream `input` and allows itself to be resumed at a later point using
249 /// `parse_partial` by storing the necessary intermediate state in `state`
250 ///
251 /// Internal API. May break without a semver bump
252 /// Always overridden by the `parse_mode!` macro
253 #[inline]
254 #[doc(hidden)]
255 fn parse_partial(
256 &mut self,
257 input: &mut Input,
258 state: &mut Self::PartialState,
259 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
260 let _ = state;
261 self.parse_lazy(input)
262 }
263
264 /// Internal API. May break without a semver bump
265 #[doc(hidden)]
266 #[inline]
267 fn parse_mode<M>(
268 &mut self,
269 mode: M,
270 input: &mut Input,
271 state: &mut Self::PartialState,
272 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error>
273 where
274 M: ParseMode,
275 Self: Sized,
276 {
277 mode.parse(self, input, state)
278 }
279
280 /// Internal API. May break without a semver bump
281 #[doc(hidden)]
282 #[inline]
283 fn parse_mode_impl<M>(
284 &mut self,
285 mode: M,
286 input: &mut Input,
287 state: &mut Self::PartialState,
288 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error>
289 where
290 M: ParseMode,
291 Self: Sized,
292 {
293 if mode.is_first() {
294 self.parse_first(input, state)
295 } else {
296 self.parse_partial(input, state)
297 }
298 }
299
300 /// Internal API. May break without a semver bump
301 #[doc(hidden)]
302 #[inline]
303 fn parse_committed_mode<M>(
304 &mut self,
305 mode: M,
306 input: &mut Input,
307 state: &mut Self::PartialState,
308 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error>
309 where
310 M: ParseMode,
311 Self: Sized,
312 {
313 if mode.is_first() {
314 FirstMode.parse_committed(self, input, state)
315 } else {
316 PartialMode::default().parse_committed(self, input, state)
317 }
318 }
319
320 /// Returns how many parsers this parser contains
321 ///
322 /// Internal API: This should not be implemented explicitly outside of combine.
323 #[doc(hidden)]
324 fn parser_count(&self) -> ErrorOffset {
325 ErrorOffset(1)
326 }
327
328 /// Internal API: This should not be implemented explicitly outside of combine.
329 #[doc(hidden)]
330 fn add_committed_expected_error(&mut self, _error: &mut Tracked<<Input as StreamOnce>::Error>) {
331 }
332
333 /// Borrows a parser instead of consuming it.
334 ///
335 /// Used to apply parser combinators on `self` without losing ownership.
336 ///
337 /// ```
338 /// # extern crate combine;
339 /// # use combine::*;
340 /// # use combine::error::Commit;
341 /// # use combine::parser::char::{digit, letter};
342 /// fn test(input: &mut &'static str) -> StdParseResult<(char, char), &'static str> {
343 /// let mut p = digit();
344 /// let ((d, _), committed) = (p.by_ref(), letter()).parse_stream(input).into_result()?;
345 /// let (d2, committed) = committed.combine(|_| p.parse_stream(input).into_result())?;
346 /// Ok(((d, d2), committed))
347 /// }
348 ///
349 /// fn main() {
350 /// let mut input = "1a23";
351 /// assert_eq!(
352 /// test(&mut input).map(|(t, c)| (t, c.map(|_| input))),
353 /// Ok((('1', '2'), Commit::Commit("3")))
354 /// );
355 /// }
356 /// ```
357 fn by_ref(&mut self) -> &mut Self
358 where
359 Self: Sized,
360 {
361 self
362 }
363
364 /// Discards the value of the `self` parser and returns the value of `p`.
365 /// Fails if any of the parsers fails.
366 ///
367 /// ```
368 /// # extern crate combine;
369 /// # use combine::*;
370 /// # use combine::parser::char::digit;
371 /// # fn main() {
372 /// let result = digit()
373 /// .with(token('i'))
374 /// .parse("9i")
375 /// .map(|x| x.0);
376 /// assert_eq!(result, Ok('i'));
377 /// # }
378 /// ```
379 fn with<P2>(self, p: P2) -> With<Self, P2>
380 where
381 Self: Sized,
382 P2: Parser<Input>,
383 {
384 with(self, p)
385 }
386
387 /// Discards the value of the `p` parser and returns the value of `self`.
388 /// Fails if any of the parsers fails.
389 ///
390 /// ```
391 /// # extern crate combine;
392 /// # use combine::*;
393 /// # use combine::parser::char::digit;
394 /// # fn main() {
395 /// let result = digit()
396 /// .skip(token('i'))
397 /// .parse("9i")
398 /// .map(|x| x.0);
399 /// assert_eq!(result, Ok('9'));
400 /// # }
401 /// ```
402 fn skip<P2>(self, p: P2) -> Skip<Self, P2>
403 where
404 Self: Sized,
405 P2: Parser<Input>,
406 {
407 skip(self, p)
408 }
409
410 /// Parses with `self` followed by `p`.
411 /// Succeeds if both parsers succeed, otherwise fails.
412 /// Returns a tuple with both values on success.
413 ///
414 /// ```
415 /// # extern crate combine;
416 /// # use combine::*;
417 /// # use combine::parser::char::digit;
418 /// # fn main() {
419 /// let result = digit()
420 /// .and(token('i'))
421 /// .parse("9i")
422 /// .map(|x| x.0);
423 /// assert_eq!(result, Ok(('9', 'i')));
424 /// # }
425 /// ```
426 fn and<P2>(self, p: P2) -> (Self, P2)
427 where
428 Self: Sized,
429 P2: Parser<Input>,
430 {
431 (self, p)
432 }
433
434 /// Returns a parser which attempts to parse using `self`. If `self` fails without committing
435 /// it tries to consume the same input using `p`.
436 ///
437 /// If you are looking to chain 3 or more parsers using `or` you may consider using the
438 /// [`choice!`] macro instead, which can be clearer and may result in a faster parser.
439 ///
440 /// ```
441 /// # extern crate combine;
442 /// # use combine::*;
443 /// # use combine::parser::char::{digit, string};
444 /// # fn main() {
445 /// let mut parser = string("let")
446 /// .or(digit().map(|_| "digit"))
447 /// .or(string("led"));
448 /// assert_eq!(parser.parse("let"), Ok(("let", "")));
449 /// assert_eq!(parser.parse("1"), Ok(("digit", "")));
450 /// assert!(parser.parse("led").is_err());
451 ///
452 /// let mut parser2 = string("two").or(string("three"));
453 /// // Fails as the parser for "two" consumes the first 't' before failing
454 /// assert!(parser2.parse("three").is_err());
455 ///
456 /// // Use 'attempt' to make failing parsers always act as if they have not committed any input
457 /// let mut parser3 = attempt(string("two")).or(attempt(string("three")));
458 /// assert_eq!(parser3.parse("three"), Ok(("three", "")));
459 /// # }
460 /// ```
461 ///
462 /// [`choice!`]: super::choice!
463 fn or<P2>(self, p: P2) -> Or<Self, P2>
464 where
465 Self: Sized,
466 P2: Parser<Input, Output = Self::Output>,
467 {
468 or(self, p)
469 }
470
471 /// Parses using `self` and then passes the value to `f` which returns a parser used to parse
472 /// the rest of the input.
473 ///
474 /// Since the parser returned from `f` must have a single type it can be useful to use the
475 /// [`left`](Parser::left) and [`right`](Parser::right) methods to merge parsers of differing types into one.
476 ///
477 /// If you are using partial parsing you may want to use [`then_partial`](Parser::then_partial) instead.
478 ///
479 /// ```
480 /// # #![cfg(feature = "std")]
481 /// # extern crate combine;
482 /// # use combine::*;
483 /// # use combine::parser::char::digit;
484 /// # use combine::error::Commit;
485 /// # use combine::stream::easy;
486 /// # fn main() {
487 /// let result = digit()
488 /// .then(|d| {
489 /// if d == '9' {
490 /// value(9).left()
491 /// }
492 /// else {
493 /// unexpected_any(d).message("Not a nine").right()
494 /// }
495 /// })
496 /// .easy_parse("9");
497 /// assert_eq!(result, Ok((9, "")));
498 /// # }
499 /// ```
500 fn then<N, F>(self, f: F) -> Then<Self, F>
501 where
502 Self: Sized,
503 F: FnMut(Self::Output) -> N,
504 N: Parser<Input>,
505 {
506 then(self, f)
507 }
508
509 /// Variant of [`then`](Parser::then) which parses using `self` and then passes the value to `f` as a `&mut` reference.
510 ///
511 /// Useful when doing partial parsing since it does not need to store the parser returned by
512 /// `f` in the partial state. Instead it will call `f` each to request a new parser each time
513 /// parsing resumes and that parser is needed.
514 ///
515 /// Since the parser returned from `f` must have a single type it can be useful to use the
516 /// [`left`](Parser::left) and [`right`](Parser::right) methods to merge parsers of differing types into one.
517 ///
518 /// ```
519 /// # #![cfg(feature = "std")]
520 /// # extern crate combine;
521 /// # use combine::*;
522 /// # use combine::parser::char::digit;
523 /// # use combine::error::Commit;
524 /// # use combine::stream::easy;
525 /// # fn main() {
526 /// let result = digit()
527 /// .then_partial(|d| {
528 /// if *d == '9' {
529 /// value(9).left()
530 /// }
531 /// else {
532 /// unexpected_any(*d).message("Not a nine").right()
533 /// }
534 /// })
535 /// .easy_parse("9");
536 /// assert_eq!(result, Ok((9, "")));
537 /// # }
538 /// ```
539 fn then_partial<N, F>(self, f: F) -> ThenPartial<Self, F>
540 where
541 Self: Sized,
542 F: FnMut(&mut Self::Output) -> N,
543 N: Parser<Input>,
544 {
545 then_partial(self, f)
546 }
547
548 /// Parses using `self` and then passes a reference to the value to `f` which returns a parser
549 /// used to parse the rest of the input. The value is then combined with the output of `f`.
550 ///
551 /// Since the parser returned from `f` must have a single type it can be useful to use the
552 /// `left` and `right` methods to merge parsers of differing types into one.
553 ///
554 /// ```
555 /// # #![cfg(feature = "std")]
556 /// # extern crate combine;
557 /// # use combine::*;
558 /// # use combine::parser::char::digit;
559 /// # use combine::error::Commit;
560 /// # use combine::stream::easy;
561 /// # fn main() {
562 /// let result = digit()
563 /// .then_ref(|d| {
564 /// if *d == '9' {
565 /// digit().left()
566 /// }
567 /// else {
568 /// unexpected_any(*d).message("Not a nine").right()
569 /// }
570 /// })
571 /// .easy_parse("98");
572 /// assert_eq!(result, Ok((('9', '8'), "")));
573 /// # }
574 /// ```
575 fn then_ref<N, F>(self, f: F) -> ThenRef<Self, F>
576 where
577 Self: Sized,
578 F: FnMut(&Self::Output) -> N,
579 N: Parser<Input>,
580 {
581 then_ref(self, f)
582 }
583
584 /// Uses `f` to map over the parsed value.
585 ///
586 /// ```
587 /// # extern crate combine;
588 /// # use combine::*;
589 /// # use combine::parser::char::digit;
590 /// # fn main() {
591 /// let result = digit()
592 /// .map(|c| c == '9')
593 /// .parse("9")
594 /// .map(|x| x.0);
595 /// assert_eq!(result, Ok(true));
596 /// # }
597 /// ```
598 fn map<F, B>(self, f: F) -> Map<Self, F>
599 where
600 Self: Sized,
601 F: FnMut(Self::Output) -> B,
602 {
603 map(self, f)
604 }
605
606 fn map_input<F, B>(self, f: F) -> MapInput<Self, F>
607 where
608 Self: Sized,
609 F: FnMut(Self::Output, &mut Input) -> B,
610 {
611 map_input(self, f)
612 }
613
614 /// Uses `f` to map over the output of `self`. If `f` returns an error the parser fails.
615 ///
616 /// ```
617 /// # extern crate combine;
618 /// # use combine::*;
619 /// # use combine::parser::char::digit;
620 /// # use combine::parser::range::take;
621 /// # fn main() {
622 /// let result = take(4)
623 /// .flat_map(|bs| many(digit()).parse(bs).map(|t| t.0))
624 /// .parse("12abcd");
625 /// assert_eq!(result, Ok((String::from("12"), "cd")));
626 /// # }
627 /// ```
628 fn flat_map<F, B>(self, f: F) -> FlatMap<Self, F>
629 where
630 Self: Sized,
631 F: FnMut(Self::Output) -> Result<B, <Input as StreamOnce>::Error>,
632 {
633 flat_map(self, f)
634 }
635
636 /// Parses with `self` and if it fails, adds the message `msg` to the error.
637 ///
638 /// ```
639 /// # #![cfg(feature = "std")]
640 /// # extern crate combine;
641 /// # use combine::*;
642 /// # use combine::stream::easy;
643 /// # use combine::stream::position::{self, SourcePosition};
644 /// # fn main() {
645 /// let result = token('9')
646 /// .message("Not a nine")
647 /// .easy_parse(position::Stream::new("8"));
648 /// assert_eq!(result, Err(easy::Errors {
649 /// position: SourcePosition::default(),
650 /// errors: vec![
651 /// easy::Error::Unexpected('8'.into()),
652 /// easy::Error::Expected('9'.into()),
653 /// easy::Error::Message("Not a nine".into())
654 /// ]
655 /// }));
656 /// # }
657 /// ```
658 fn message<S>(self, msg: S) -> Message<Self, S>
659 where
660 Self: Sized,
661 S: for<'s> ErrorInfo<'s, Input::Token, Input::Range>,
662 {
663 message(self, msg)
664 }
665
666 /// Parses with `self` and if it fails without consuming any input any expected errors are
667 /// replaced by `msg`. `msg` is then used in error messages as "Expected `msg`".
668 ///
669 /// ```
670 /// # #![cfg(feature = "std")]
671 /// # extern crate combine;
672 /// # use combine::*;
673 /// # use combine::error;
674 /// # use combine::stream::easy;
675 /// # use combine::stream::position::{self, SourcePosition};
676 /// # fn main() {
677 /// let result = token('9')
678 /// .expected("nine")
679 /// .easy_parse(position::Stream::new("8"));
680 /// assert_eq!(result, Err(easy::Errors {
681 /// position: SourcePosition::default(),
682 /// errors: vec![
683 /// easy::Error::Unexpected('8'.into()),
684 /// easy::Error::Expected("nine".into())
685 /// ]
686 /// }));
687 ///
688 /// let result = token('9')
689 /// .expected(error::Format(format_args!("That is not a nine!")))
690 /// .easy_parse(position::Stream::new("8"));
691 /// assert_eq!(result, Err(easy::Errors {
692 /// position: SourcePosition::default(),
693 /// errors: vec![
694 /// easy::Error::Unexpected('8'.into()),
695 /// easy::Error::Expected("That is not a nine!".to_string().into())
696 /// ]
697 /// }));
698 /// # }
699 /// ```
700 fn expected<S>(self, msg: S) -> Expected<Self, S>
701 where
702 Self: Sized,
703 S: for<'s> ErrorInfo<'s, Input::Token, Input::Range>,
704 {
705 expected(self, msg)
706 }
707
708 /// Parses with `self`, if it fails without consuming any input any expected errors that would
709 /// otherwise be emitted by `self` are suppressed.
710 ///
711 /// ```
712 /// # #![cfg(feature = "std")]
713 /// # extern crate combine;
714 /// # use combine::*;
715 /// # use combine::stream::easy;
716 /// # use combine::stream::position::{self, SourcePosition};
717 /// # fn main() {
718 /// let result = token('9')
719 /// .expected("nine")
720 /// .silent()
721 /// .easy_parse(position::Stream::new("8"));
722 /// assert_eq!(result, Err(easy::Errors {
723 /// position: SourcePosition::default(),
724 /// errors: vec![
725 /// easy::Error::Unexpected('8'.into()),
726 /// ]
727 /// }));
728 /// # }
729 /// ```
730 fn silent(self) -> Silent<Self>
731 where
732 Self: Sized,
733 {
734 silent(self)
735 }
736
737 /// Parses with `self` and applies `f` on the result if `self` parses successfully.
738 /// `f` may optionally fail with an error which is automatically converted to a `ParseError`.
739 ///
740 /// ```
741 /// # extern crate combine;
742 /// # use combine::*;
743 /// # use combine::stream::position::{self, SourcePosition};
744 /// # use combine::parser::char::digit;
745 /// # fn main() {
746 /// let mut parser = many1(digit())
747 /// .and_then(|s: String| s.parse::<i32>());
748 /// let result = parser.easy_parse(position::Stream::new("1234")).map(|(x, state)| (x, state.input));
749 /// assert_eq!(result, Ok((1234, "")));
750 /// let result = parser.easy_parse(position::Stream::new("999999999999999999999999"));
751 /// assert!(result.is_err());
752 /// // Errors are report as if they occurred at the start of the parse
753 /// assert_eq!(result.unwrap_err().position, SourcePosition { line: 1, column: 1 });
754 /// # }
755 /// ```
756 fn and_then<F, O, E>(self, f: F) -> AndThen<Self, F>
757 where
758 Self: Parser<Input> + Sized,
759 F: FnMut(Self::Output) -> Result<O, E>,
760 E: Into<
761 <Input::Error as ParseError<Input::Token, Input::Range, Input::Position>>::StreamError,
762 >,
763 {
764 and_then(self, f)
765 }
766
767 /// Creates an iterator from a parser and a state. Can be used as an alternative to [`many`]
768 /// when collecting directly into a `Extend` type is not desirable.
769 ///
770 /// ```
771 /// # extern crate combine;
772 /// # use combine::*;
773 /// # use combine::parser::char::{char, digit};
774 /// # fn main() {
775 /// let mut buffer = String::new();
776 /// let number = parser(|input| {
777 /// buffer.clear();
778 /// let mut iter = digit().iter(input);
779 /// buffer.extend(&mut iter);
780 /// let i = buffer.parse::<i32>().unwrap();
781 /// iter.into_result(i)
782 /// });
783 /// let result = sep_by(number, char(','))
784 /// .parse("123,45,6");
785 /// assert_eq!(result, Ok((vec![123, 45, 6], "")));
786 /// # }
787 /// ```
788 ///
789 /// [`many`]: repeat::many
790 fn iter(self, input: &mut Input) -> Iter<'_, Input, Self, Self::PartialState, FirstMode>
791 where
792 Self: Parser<Input> + Sized,
793 {
794 Iter::new(self, FirstMode, input, Default::default())
795 }
796
797 /// Creates an iterator from a parser and a state. Can be used as an alternative to [`many`]
798 /// when collecting directly into a `Extend` type is not desirable.
799 ///
800 /// ```
801 /// # extern crate combine;
802 /// # use combine::*;
803 /// # use combine::parser::char::{char, digit};
804 /// # fn main() {
805 /// let mut buffer = String::new();
806 /// let number = parser(|input| {
807 /// buffer.clear();
808 /// let mut iter = digit().iter(input);
809 /// buffer.extend(&mut iter);
810 /// let i = buffer.parse::<i32>().unwrap();
811 /// iter.into_result(i)
812 /// });
813 /// let result = sep_by(number, char(','))
814 /// .parse("123,45,6");
815 /// assert_eq!(result, Ok((vec![123, 45, 6], "")));
816 /// # }
817 /// ```
818 ///
819 /// [`many`]: repeat::many
820 fn partial_iter<'a, 's, M>(
821 self,
822 mode: M,
823 input: &'a mut Input,
824 partial_state: &'s mut Self::PartialState,
825 ) -> Iter<'a, Input, Self, &'s mut Self::PartialState, M>
826 where
827 Self: Parser<Input> + Sized,
828 M: ParseMode,
829 {
830 Iter::new(self, mode, input, partial_state)
831 }
832
833 /// Turns the parser into a trait object by putting it in a `Box`. Can be used to easily
834 /// return parsers from functions without naming the type.
835 ///
836 /// ```
837 /// # use combine::*;
838 /// # fn main() {
839 /// fn test<'input, F>(
840 /// c: char,
841 /// f: F)
842 /// -> Box<dyn Parser<&'input str, Output = (char, char), PartialState = ()> + 'input>
843 /// where F: FnMut(char) -> bool + 'static
844 /// {
845 /// combine::parser::combinator::no_partial((token(c), satisfy(f))).boxed()
846 /// }
847 /// let result = test('a', |c| c >= 'a' && c <= 'f')
848 /// .parse("ac");
849 /// assert_eq!(result, Ok((('a', 'c'), "")));
850 /// # }
851 /// ```
852 #[cfg(feature = "alloc")]
853 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
854 fn boxed<'a>(
855 self,
856 ) -> Box<dyn Parser<Input, Output = Self::Output, PartialState = Self::PartialState> + 'a>
857 where
858 Self: Sized + 'a,
859 {
860 Box::new(self)
861 }
862
863 /// Wraps the parser into the [`Either`](combinator::Either) enum which allows combinators such as [`then`](Parser::then) to return
864 /// multiple different parser types (merging them to one)
865 ///
866 /// ```
867 /// # extern crate combine;
868 /// # use combine::*;
869 /// # use combine::parser::char::{digit, letter};
870 /// # fn main() {
871 /// let mut parser = any().then(|c|
872 /// if c == '#' {
873 /// skip_many(satisfy(|c| c != '\n'))
874 /// .with(value("".to_string()))
875 /// .left()
876 /// } else {
877 /// many1(letter())
878 /// .map(move |mut s: String| { s.insert(0, c); s })
879 /// .right()
880 /// });
881 ///
882 /// let result = parser.parse("ac2");
883 /// assert_eq!(result, Ok(("ac".to_string(), "2")));
884 ///
885 /// let result = parser.parse("# ac2");
886 /// assert_eq!(result, Ok(("".to_string(), "")));
887 /// # }
888 /// ```
889 fn left<R>(self) -> Either<Self, R>
890 where
891 Self: Sized,
892 R: Parser<Input, Output = Self::Output>,
893 {
894 Either::Left(self)
895 }
896
897 /// Wraps the parser into the [`Either`](combinator::Either) enum which allows combinators such as [`then`](Parser::then) to return
898 /// multiple different parser types (merging them to one)
899 ///
900 /// ```
901 /// # extern crate combine;
902 /// # use combine::*;
903 /// # use combine::parser::char::{digit, letter};
904 /// # fn main() {
905 /// let mut parser = any().then(|c|
906 /// if c == '#' {
907 /// skip_many(satisfy(|c| c != '\n'))
908 /// .with(value("".to_string()))
909 /// .left()
910 /// } else {
911 /// many1(letter())
912 /// .map(move |mut s: String| { s.insert(0, c); s })
913 /// .right()
914 /// });
915 ///
916 /// let result = parser.parse("ac2");
917 /// assert_eq!(result, Ok(("ac".to_string(), "2")));
918 ///
919 /// let result = parser.parse("# ac2");
920 /// assert_eq!(result, Ok(("".to_string(), "")));
921 /// # }
922 /// ```
923 fn right<L>(self) -> Either<L, Self>
924 where
925 Self: Sized,
926 L: Parser<Input, Output = Self::Output>,
927 {
928 Either::Right(self)
929 }
930
931 /// Marks errors produced inside the `self` parser with the span from the start of the parse to
932 /// the end of it.
933 ///
934 /// [`p.spanned()`]: ../trait.Parser.html#method.spanned
935 ///
936 /// ```
937 /// use combine::{*, parser::{char::string, combinator::spanned}};
938 /// use combine::stream::{easy, span};
939 ///
940 /// let input = "hel";
941 /// let result = spanned(string("hello")).parse(
942 /// span::Stream::<_, easy::Errors<_, _, span::Span<_>>>::from(easy::Stream::from(input)),
943 /// );
944 /// assert!(result.is_err());
945 /// assert_eq!(
946 /// result.unwrap_err().position.map(|p| p.translate_position(input)),
947 /// span::Span { start: 0, end: 3 },
948 /// );
949 /// ```
950 fn spanned(self) -> Spanned<Self>
951 where
952 Self: Sized,
953 {
954 spanned(self)
955 }
956}
957
958/// Provides the `easy_parse` method which provides good error messages by default
959#[cfg(feature = "std")]
960#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
961pub trait EasyParser<Input: Stream>: Parser<crate::easy::Stream<Input>>
962where
963 Input::Token: PartialEq,
964 Input::Range: PartialEq,
965{
966 /// Entry point of the parser. Takes some input and tries to parse it, returning an easy to use
967 /// and format error if parsing did not succeed.
968 ///
969 /// Returns the parsed result and the remaining input if the parser succeeds, or a
970 /// This function wraps requires `Input == easy::Stream<Input>` which makes it return
971 /// return `easy::Errors` if an error occurs. Due to this wrapping it is recommended that the
972 /// parser `Self` is written with a generic input type.
973 ///
974 /// ```
975 /// # #[macro_use]
976 /// # extern crate combine;
977 ///
978 /// use combine::*;
979 /// use combine::parser::repeat::many1;
980 /// use combine::parser::char::letter;
981 ///
982 /// // Good!
983 /// parser!{
984 /// fn my_parser[Input]()(Input) -> String
985 /// where [Input: Stream<Token = char>]
986 /// {
987 /// many1::<String, _, _>(letter())
988 /// }
989 /// }
990 ///
991 /// // Won't compile with `easy_parse` since it is specialized on `&str`
992 /// parser!{
993 /// fn my_parser2['a]()(&'a str) -> String
994 /// where [&'a str: Stream<Token = char, Range = &'a str>]
995 /// {
996 /// many1(letter())
997 /// }
998 /// }
999 ///
1000 /// fn main() {
1001 /// assert_eq!(my_parser().parse("abc"), Ok(("abc".to_string(), "")));
1002 /// // Would fail to compile if uncommented
1003 /// // my_parser2().parse("abc")
1004 /// }
1005 /// ```
1006 ///
1007 /// [`ParseError`]: struct.ParseError.html
1008 fn easy_parse(
1009 &mut self,
1010 input: Input,
1011 ) -> Result<
1012 (<Self as Parser<crate::easy::Stream<Input>>>::Output, Input),
1013 crate::easy::ParseError<Input>,
1014 >
1015 where
1016 Input: Stream,
1017 crate::easy::Stream<Input>: StreamOnce<
1018 Token = Input::Token,
1019 Range = Input::Range,
1020 Error = crate::easy::ParseError<crate::easy::Stream<Input>>,
1021 Position = Input::Position,
1022 >,
1023 Input::Position: Default,
1024 Self: Sized + Parser<crate::easy::Stream<Input>>,
1025 {
1026 let input = crate::easy::Stream(input);
1027 self.parse(input).map(|(v, input)| (v, input.0))
1028 }
1029}
1030
1031#[cfg(feature = "std")]
1032impl<Input, P> EasyParser<Input> for P
1033where
1034 P: ?Sized + Parser<crate::easy::Stream<Input>>,
1035 Input: Stream,
1036 Input::Token: PartialEq,
1037 Input::Range: PartialEq,
1038{
1039}
1040
1041macro_rules! forward_deref {
1042 (Input) => {
1043 type Output = P::Output;
1044 type PartialState = P::PartialState;
1045
1046 #[inline]
1047 fn parse_first(
1048 &mut self,
1049 input: &mut Input,
1050 state: &mut Self::PartialState,
1051 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
1052 (**self).parse_first(input, state)
1053 }
1054
1055 #[inline]
1056 fn parse_partial(
1057 &mut self,
1058 input: &mut Input,
1059 state: &mut Self::PartialState,
1060 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
1061 (**self).parse_partial(input, state)
1062 }
1063
1064 #[inline]
1065 fn add_error(&mut self, error: &mut Tracked<<Input as StreamOnce>::Error>) {
1066 (**self).add_error(error)
1067 }
1068
1069 #[inline]
1070 fn add_committed_expected_error(
1071 &mut self,
1072 error: &mut Tracked<<Input as StreamOnce>::Error>,
1073 ) {
1074 (**self).add_committed_expected_error(error)
1075 }
1076
1077 #[inline]
1078 fn parser_count(&self) -> ErrorOffset {
1079 (**self).parser_count()
1080 }
1081 };
1082}
1083
1084impl<'a, P, Input> Parser<Input> for &'a mut P
1085where
1086 P: ?Sized + Parser<Input>,
1087 Input: Stream,
1088{
1089 forward_deref!(Input);
1090}
1091
1092#[cfg(feature = "alloc")]
1093impl<P, Input> Parser<Input> for Box<P>
1094where
1095 P: ?Sized + Parser<Input>,
1096 Input: Stream,
1097{
1098 forward_deref!(Input);
1099}
1100
1101/// Internal API. May break without a semver bump
1102#[doc(hidden)]
1103/// Specifies whether the parser must check for partial state that must be resumed
1104pub trait ParseMode: Copy {
1105 /// If `true` then the parser has no previous state to resume otherwise the parser *might* have
1106 /// state to resume which it must check.
1107 fn is_first(self) -> bool;
1108 /// Puts the mode into `first` parsing.
1109 fn set_first(&mut self);
1110
1111 fn parse<P, Input>(
1112 self,
1113 parser: &mut P,
1114 input: &mut Input,
1115 state: &mut P::PartialState,
1116 ) -> ParseResult<P::Output, Input::Error>
1117 where
1118 P: Parser<Input>,
1119 Input: Stream;
1120
1121 #[inline]
1122 fn parse_committed<P, Input>(
1123 self,
1124 parser: &mut P,
1125 input: &mut Input,
1126 state: &mut P::PartialState,
1127 ) -> ParseResult<P::Output, <Input as StreamOnce>::Error>
1128 where
1129 P: Parser<Input>,
1130 Input: Stream,
1131 {
1132 let before = input.checkpoint();
1133 let mut result = parser.parse_mode_impl(self, input, state);
1134 if let ParseResult::PeekErr(ref mut error) = result {
1135 ctry!(input.reset(before.clone()).committed());
1136 if let Ok(t) = input.uncons() {
1137 ctry!(input.reset(before).committed());
1138 error.error.add_unexpected(Token(t));
1139 } else {
1140 error.error.add(StreamErrorFor::<Input>::end_of_input());
1141 }
1142 parser.add_error(error);
1143 }
1144 result
1145 }
1146}
1147
1148/// Internal API. May break without a semver bump
1149#[doc(hidden)]
1150#[derive(Copy, Clone)]
1151pub struct FirstMode;
1152impl ParseMode for FirstMode {
1153 #[inline]
1154 fn is_first(self) -> bool {
1155 true
1156 }
1157 #[inline]
1158 fn set_first(&mut self) {}
1159
1160 fn parse<P, Input>(
1161 self,
1162 parser: &mut P,
1163 input: &mut Input,
1164 state: &mut P::PartialState,
1165 ) -> ParseResult<P::Output, Input::Error>
1166 where
1167 P: Parser<Input>,
1168 Input: Stream,
1169 {
1170 parser.parse_mode_impl(FirstMode, input, state)
1171 }
1172}
1173
1174/// Internal API. May break without a semver bump
1175#[doc(hidden)]
1176#[derive(Copy, Clone, Default)]
1177pub struct PartialMode {
1178 pub first: bool,
1179}
1180impl ParseMode for PartialMode {
1181 #[inline]
1182 fn is_first(self) -> bool {
1183 self.first
1184 }
1185
1186 #[inline]
1187 fn set_first(&mut self) {
1188 self.first = true;
1189 }
1190
1191 fn parse<P, Input>(
1192 self,
1193 parser: &mut P,
1194 input: &mut Input,
1195 state: &mut P::PartialState,
1196 ) -> ParseResult<P::Output, Input::Error>
1197 where
1198 P: Parser<Input>,
1199 Input: Stream,
1200 {
1201 if self.is_first() {
1202 parser.parse_mode_impl(FirstMode, input, state)
1203 } else {
1204 parser.parse_mode_impl(self, input, state)
1205 }
1206 }
1207}