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 /// // Using no_partial here we do not need to name the type of `PartialState`
846 /// // (though it disables partial parsing, if partial parsing is used `any_partial_state` can be used instead)
847 /// combine::parser::combinator::no_partial((token(c), satisfy(f))).boxed()
848 /// }
849 /// let result = test('a', |c| c >= 'a' && c <= 'f')
850 /// .parse("ac");
851 /// assert_eq!(result, Ok((('a', 'c'), "")));
852 /// # }
853 /// ```
854 #[cfg(feature = "alloc")]
855 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
856 fn boxed<'a>(
857 self,
858 ) -> Box<dyn Parser<Input, Output = Self::Output, PartialState = Self::PartialState> + 'a>
859 where
860 Self: Sized + 'a,
861 {
862 Box::new(self)
863 }
864
865 /// Wraps the parser into the [`Either`](combinator::Either) enum which allows combinators such as [`then`](Parser::then) to return
866 /// multiple different parser types (merging them to one)
867 ///
868 /// ```
869 /// # extern crate combine;
870 /// # use combine::*;
871 /// # use combine::parser::char::{digit, letter};
872 /// # fn main() {
873 /// let mut parser = any().then(|c|
874 /// if c == '#' {
875 /// skip_many(satisfy(|c| c != '\n'))
876 /// .with(value("".to_string()))
877 /// .left()
878 /// } else {
879 /// many1(letter())
880 /// .map(move |mut s: String| { s.insert(0, c); s })
881 /// .right()
882 /// });
883 ///
884 /// let result = parser.parse("ac2");
885 /// assert_eq!(result, Ok(("ac".to_string(), "2")));
886 ///
887 /// let result = parser.parse("# ac2");
888 /// assert_eq!(result, Ok(("".to_string(), "")));
889 /// # }
890 /// ```
891 fn left<R>(self) -> Either<Self, R>
892 where
893 Self: Sized,
894 R: Parser<Input, Output = Self::Output>,
895 {
896 Either::Left(self)
897 }
898
899 /// Wraps the parser into the [`Either`](combinator::Either) enum which allows combinators such as [`then`](Parser::then) to return
900 /// multiple different parser types (merging them to one)
901 ///
902 /// ```
903 /// # extern crate combine;
904 /// # use combine::*;
905 /// # use combine::parser::char::{digit, letter};
906 /// # fn main() {
907 /// let mut parser = any().then(|c|
908 /// if c == '#' {
909 /// skip_many(satisfy(|c| c != '\n'))
910 /// .with(value("".to_string()))
911 /// .left()
912 /// } else {
913 /// many1(letter())
914 /// .map(move |mut s: String| { s.insert(0, c); s })
915 /// .right()
916 /// });
917 ///
918 /// let result = parser.parse("ac2");
919 /// assert_eq!(result, Ok(("ac".to_string(), "2")));
920 ///
921 /// let result = parser.parse("# ac2");
922 /// assert_eq!(result, Ok(("".to_string(), "")));
923 /// # }
924 /// ```
925 fn right<L>(self) -> Either<L, Self>
926 where
927 Self: Sized,
928 L: Parser<Input, Output = Self::Output>,
929 {
930 Either::Right(self)
931 }
932
933 /// Marks errors produced inside the `self` parser with the span from the start of the parse to
934 /// the end of it.
935 ///
936 /// [`p.spanned()`]: ../trait.Parser.html#method.spanned
937 ///
938 /// ```
939 /// use combine::{*, parser::{char::string, combinator::spanned}};
940 /// use combine::stream::{easy, span};
941 ///
942 /// let input = "hel";
943 /// let result = spanned(string("hello")).parse(
944 /// span::Stream::<_, easy::Errors<_, _, span::Span<_>>>::from(easy::Stream::from(input)),
945 /// );
946 /// assert!(result.is_err());
947 /// assert_eq!(
948 /// result.unwrap_err().position.map(|p| p.translate_position(input)),
949 /// span::Span { start: 0, end: 3 },
950 /// );
951 /// ```
952 fn spanned(self) -> Spanned<Self>
953 where
954 Self: Sized,
955 {
956 spanned(self)
957 }
958}
959
960/// Provides the `easy_parse` method which provides good error messages by default
961#[cfg(feature = "std")]
962#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
963pub trait EasyParser<Input: Stream>: Parser<crate::easy::Stream<Input>>
964where
965 Input::Token: PartialEq,
966 Input::Range: PartialEq,
967{
968 /// Entry point of the parser. Takes some input and tries to parse it, returning an easy to use
969 /// and format error if parsing did not succeed.
970 ///
971 /// Returns the parsed result and the remaining input if the parser succeeds, or a
972 /// This function wraps requires `Input == easy::Stream<Input>` which makes it return
973 /// return `easy::Errors` if an error occurs. Due to this wrapping it is recommended that the
974 /// parser `Self` is written with a generic input type.
975 ///
976 /// ```
977 /// # #[macro_use]
978 /// # extern crate combine;
979 ///
980 /// use combine::*;
981 /// use combine::parser::repeat::many1;
982 /// use combine::parser::char::letter;
983 ///
984 /// // Good!
985 /// parser!{
986 /// fn my_parser[Input]()(Input) -> String
987 /// where [Input: Stream<Token = char>]
988 /// {
989 /// many1::<String, _, _>(letter())
990 /// }
991 /// }
992 ///
993 /// // Won't compile with `easy_parse` since it is specialized on `&str`
994 /// parser!{
995 /// fn my_parser2['a]()(&'a str) -> String
996 /// where [&'a str: Stream<Token = char, Range = &'a str>]
997 /// {
998 /// many1(letter())
999 /// }
1000 /// }
1001 ///
1002 /// fn main() {
1003 /// assert_eq!(my_parser().parse("abc"), Ok(("abc".to_string(), "")));
1004 /// // Would fail to compile if uncommented
1005 /// // my_parser2().parse("abc")
1006 /// }
1007 /// ```
1008 ///
1009 /// [`ParseError`]: struct.ParseError.html
1010 fn easy_parse(
1011 &mut self,
1012 input: Input,
1013 ) -> Result<
1014 (<Self as Parser<crate::easy::Stream<Input>>>::Output, Input),
1015 crate::easy::ParseError<Input>,
1016 >
1017 where
1018 Input: Stream,
1019 crate::easy::Stream<Input>: StreamOnce<
1020 Token = Input::Token,
1021 Range = Input::Range,
1022 Error = crate::easy::ParseError<crate::easy::Stream<Input>>,
1023 Position = Input::Position,
1024 >,
1025 Input::Position: Default,
1026 Self: Sized + Parser<crate::easy::Stream<Input>>,
1027 {
1028 let input = crate::easy::Stream(input);
1029 self.parse(input).map(|(v, input)| (v, input.0))
1030 }
1031}
1032
1033#[cfg(feature = "std")]
1034impl<Input, P> EasyParser<Input> for P
1035where
1036 P: ?Sized + Parser<crate::easy::Stream<Input>>,
1037 Input: Stream,
1038 Input::Token: PartialEq,
1039 Input::Range: PartialEq,
1040{
1041}
1042
1043macro_rules! forward_deref {
1044 (Input) => {
1045 type Output = P::Output;
1046 type PartialState = P::PartialState;
1047
1048 #[inline]
1049 fn parse_first(
1050 &mut self,
1051 input: &mut Input,
1052 state: &mut Self::PartialState,
1053 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
1054 (**self).parse_first(input, state)
1055 }
1056
1057 #[inline]
1058 fn parse_partial(
1059 &mut self,
1060 input: &mut Input,
1061 state: &mut Self::PartialState,
1062 ) -> ParseResult<Self::Output, <Input as StreamOnce>::Error> {
1063 (**self).parse_partial(input, state)
1064 }
1065
1066 #[inline]
1067 fn add_error(&mut self, error: &mut Tracked<<Input as StreamOnce>::Error>) {
1068 (**self).add_error(error)
1069 }
1070
1071 #[inline]
1072 fn add_committed_expected_error(
1073 &mut self,
1074 error: &mut Tracked<<Input as StreamOnce>::Error>,
1075 ) {
1076 (**self).add_committed_expected_error(error)
1077 }
1078
1079 #[inline]
1080 fn parser_count(&self) -> ErrorOffset {
1081 (**self).parser_count()
1082 }
1083 };
1084}
1085
1086impl<'a, P, Input> Parser<Input> for &'a mut P
1087where
1088 P: ?Sized + Parser<Input>,
1089 Input: Stream,
1090{
1091 forward_deref!(Input);
1092}
1093
1094#[cfg(feature = "alloc")]
1095impl<P, Input> Parser<Input> for Box<P>
1096where
1097 P: ?Sized + Parser<Input>,
1098 Input: Stream,
1099{
1100 forward_deref!(Input);
1101}
1102
1103/// Internal API. May break without a semver bump
1104#[doc(hidden)]
1105/// Specifies whether the parser must check for partial state that must be resumed
1106pub trait ParseMode: Copy {
1107 /// If `true` then the parser has no previous state to resume otherwise the parser *might* have
1108 /// state to resume which it must check.
1109 fn is_first(self) -> bool;
1110 /// Puts the mode into `first` parsing.
1111 fn set_first(&mut self);
1112
1113 fn parse<P, Input>(
1114 self,
1115 parser: &mut P,
1116 input: &mut Input,
1117 state: &mut P::PartialState,
1118 ) -> ParseResult<P::Output, Input::Error>
1119 where
1120 P: Parser<Input>,
1121 Input: Stream;
1122
1123 #[inline]
1124 fn parse_committed<P, Input>(
1125 self,
1126 parser: &mut P,
1127 input: &mut Input,
1128 state: &mut P::PartialState,
1129 ) -> ParseResult<P::Output, <Input as StreamOnce>::Error>
1130 where
1131 P: Parser<Input>,
1132 Input: Stream,
1133 {
1134 let before = input.checkpoint();
1135 let mut result = parser.parse_mode_impl(self, input, state);
1136 if let ParseResult::PeekErr(ref mut error) = result {
1137 ctry!(input.reset(before.clone()).committed());
1138 if let Ok(t) = input.uncons() {
1139 ctry!(input.reset(before).committed());
1140 error.error.add_unexpected(Token(t));
1141 } else {
1142 error.error.add(StreamErrorFor::<Input>::end_of_input());
1143 }
1144 parser.add_error(error);
1145 }
1146 result
1147 }
1148}
1149
1150/// Internal API. May break without a semver bump
1151#[doc(hidden)]
1152#[derive(Copy, Clone)]
1153pub struct FirstMode;
1154impl ParseMode for FirstMode {
1155 #[inline]
1156 fn is_first(self) -> bool {
1157 true
1158 }
1159 #[inline]
1160 fn set_first(&mut self) {}
1161
1162 fn parse<P, Input>(
1163 self,
1164 parser: &mut P,
1165 input: &mut Input,
1166 state: &mut P::PartialState,
1167 ) -> ParseResult<P::Output, Input::Error>
1168 where
1169 P: Parser<Input>,
1170 Input: Stream,
1171 {
1172 parser.parse_mode_impl(FirstMode, input, state)
1173 }
1174}
1175
1176/// Internal API. May break without a semver bump
1177#[doc(hidden)]
1178#[derive(Copy, Clone, Default)]
1179pub struct PartialMode {
1180 pub first: bool,
1181}
1182impl ParseMode for PartialMode {
1183 #[inline]
1184 fn is_first(self) -> bool {
1185 self.first
1186 }
1187
1188 #[inline]
1189 fn set_first(&mut self) {
1190 self.first = true;
1191 }
1192
1193 fn parse<P, Input>(
1194 self,
1195 parser: &mut P,
1196 input: &mut Input,
1197 state: &mut P::PartialState,
1198 ) -> ParseResult<P::Output, Input::Error>
1199 where
1200 P: Parser<Input>,
1201 Input: Stream,
1202 {
1203 if self.is_first() {
1204 parser.parse_mode_impl(FirstMode, input, state)
1205 } else {
1206 parser.parse_mode_impl(self, input, state)
1207 }
1208 }
1209}