nom/combinator/
mod.rs

Help
1//! General purpose combinators
2
3#![allow(unused_imports)]
4
5use core::marker::PhantomData;
6
7#[cfg(feature = "alloc")]
8use crate::lib::std::boxed::Box;
9
10use crate::error::{ErrorKind, FromExternalError, ParseError};
11use crate::internal::*;
12use crate::lib::std::borrow::Borrow;
13use crate::lib::std::convert::Into;
14#[cfg(feature = "std")]
15use crate::lib::std::fmt::Debug;
16use crate::lib::std::mem::transmute;
17use crate::lib::std::ops::{Range, RangeFrom, RangeTo};
18use crate::traits::{AsChar, Input, ParseTo};
19use crate::traits::{Compare, CompareResult, Offset};
20
21#[cfg(test)]
22mod tests;
23
24/// Return the remaining input.
25///
26/// ```rust
27/// # use nom::error::ErrorKind;
28/// use nom::combinator::rest;
29/// assert_eq!(rest::<_,(_, ErrorKind)>("abc"), Ok(("", "abc")));
30/// assert_eq!(rest::<_,(_, ErrorKind)>(""), Ok(("", "")));
31/// ```
32#[inline]
33pub fn rest<T, E: ParseError<T>>(input: T) -> IResult<T, T, E>
34where
35  T: Input,
36{
37  Ok(input.take_split(input.input_len()))
38}
39
40/// Return the length of the remaining input.
41///
42/// ```rust
43/// # use nom::error::ErrorKind;
44/// use nom::combinator::rest_len;
45/// assert_eq!(rest_len::<_,(_, ErrorKind)>("abc"), Ok(("abc", 3)));
46/// assert_eq!(rest_len::<_,(_, ErrorKind)>(""), Ok(("", 0)));
47/// ```
48#[inline]
49pub fn rest_len<T, E: ParseError<T>>(input: T) -> IResult<T, usize, E>
50where
51  T: Input,
52{
53  let len = input.input_len();
54  Ok((input, len))
55}
56
57/// Maps a function on the result of a parser.
58///
59/// ```rust
60/// use nom::{Err,error::ErrorKind, IResult, Parser};
61/// use nom::character::complete::digit1;
62/// use nom::combinator::map;
63/// # fn main() {
64///
65/// let mut parser = map(digit1, |s: &str| s.len());
66///
67/// // the parser will count how many characters were returned by digit1
68/// assert_eq!(parser.parse("123456"), Ok(("", 6)));
69///
70/// // this will fail if digit1 fails
71/// assert_eq!(parser.parse("abc"), Err(Err::Error(("abc", ErrorKind::Digit))));
72/// # }
73/// ```
74pub fn map<I, O, E: ParseError<I>, F, G>(parser: F, f: G) -> impl Parser<I, Output = O, Error = E>
75where
76  F: Parser<I, Error = E>,
77  G: FnMut(<F as Parser<I>>::Output) -> O,
78{
79  parser.map(f)
80}
81
82/// Applies a function returning a `Result` over the result of a parser.
83///
84/// ```rust
85/// # use nom::{Err,error::ErrorKind, IResult, Parser};
86/// use nom::character::complete::digit1;
87/// use nom::combinator::map_res;
88/// # fn main() {
89///
90/// let mut parse = map_res(digit1, |s: &str| s.parse::<u8>());
91///
92/// // the parser will convert the result of digit1 to a number
93/// assert_eq!(parse.parse("123"), Ok(("", 123)));
94///
95/// // this will fail if digit1 fails
96/// assert_eq!(parse.parse("abc"), Err(Err::Error(("abc", ErrorKind::Digit))));
97///
98/// // this will fail if the mapped function fails (a `u8` is too small to hold `123456`)
99/// assert_eq!(parse.parse("123456"), Err(Err::Error(("123456", ErrorKind::MapRes))));
100/// # }
101/// ```
102pub fn map_res<I: Clone, O, E: ParseError<I> + FromExternalError<I, E2>, E2, F, G>(
103  parser: F,
104  f: G,
105) -> impl Parser<I, Output = O, Error = E>
106where
107  F: Parser<I, Error = E>,
108  G: FnMut(<F as Parser<I>>::Output) -> Result<O, E2>,
109{
110  parser.map_res(f)
111}
112
113/// Applies a function returning an `Option` over the result of a parser.
114///
115/// ```rust
116/// # use nom::{Err,error::ErrorKind, IResult, Parser};
117/// use nom::character::complete::digit1;
118/// use nom::combinator::map_opt;
119/// # fn main() {
120///
121/// let mut parse = map_opt(digit1, |s: &str| s.parse::<u8>().ok());
122///
123/// // the parser will convert the result of digit1 to a number
124/// assert_eq!(parse.parse("123"), Ok(("", 123)));
125///
126/// // this will fail if digit1 fails
127/// assert_eq!(parse.parse("abc"), Err(Err::Error(("abc", ErrorKind::Digit))));
128///
129/// // this will fail if the mapped function fails (a `u8` is too small to hold `123456`)
130/// assert_eq!(parse.parse("123456"), Err(Err::Error(("123456", ErrorKind::MapOpt))));
131/// # }
132/// ```
133pub fn map_opt<I: Clone, O, E: ParseError<I>, F, G>(
134  parser: F,
135  f: G,
136) -> impl Parser<I, Output = O, Error = E>
137where
138  F: Parser<I, Error = E>,
139  G: FnMut(<F as Parser<I>>::Output) -> Option<O>,
140{
141  parser.map_opt(f)
142}
143
144/// Applies a parser over the result of another one.
145///
146/// ```rust
147/// # use nom::{Err,error::ErrorKind, IResult, Parser};
148/// use nom::character::complete::digit1;
149/// use nom::bytes::complete::take;
150/// use nom::combinator::map_parser;
151/// # fn main() {
152///
153/// let mut parse = map_parser(take(5u8), digit1);
154///
155/// assert_eq!(parse.parse("12345"), Ok(("", "12345")));
156/// assert_eq!(parse.parse("123ab"), Ok(("", "123")));
157/// assert_eq!(parse.parse("123"), Err(Err::Error(("123", ErrorKind::Eof))));
158/// # }
159/// ```
160pub fn map_parser<I, O, E: ParseError<I>, F, G>(
161  parser: F,
162  applied_parser: G,
163) -> impl Parser<I, Output = O, Error = E>
164where
165  F: Parser<I, Error = E>,
166  G: Parser<<F as Parser<I>>::Output, Output = O, Error = E>,
167{
168  parser.and_then(applied_parser)
169}
170
171/// Creates a new parser from the output of the first parser, then apply that parser over the rest of the input.
172///
173/// ```rust
174/// # use nom::{Err,error::ErrorKind, IResult, Parser};
175/// use nom::bytes::complete::take;
176/// use nom::number::complete::u8;
177/// use nom::combinator::flat_map;
178/// # fn main() {
179///
180/// let mut parse = flat_map(u8, take);
181///
182/// assert_eq!(parse.parse(&[2, 0, 1, 2][..]), Ok((&[2][..], &[0, 1][..])));
183/// assert_eq!(parse.parse(&[4, 0, 1, 2][..]), Err(Err::Error((&[0, 1, 2][..], ErrorKind::Eof))));
184/// # }
185/// ```
186pub fn flat_map<I, O, E: ParseError<I>, F, G, H>(
187  parser: F,
188  applied_parser: G,
189) -> impl Parser<I, Output = O, Error = E>
190where
191  F: Parser<I, Error = E>,
192  G: FnMut(<F as Parser<I>>::Output) -> H,
193  H: Parser<I, Output = O, Error = E>,
194{
195  parser.flat_map(applied_parser)
196}
197
198/// Optional parser, will return `None` on [`Err::Error`].
199///
200/// To chain an error up, see [`cut`].
201///
202/// ```rust
203/// # use nom::{Err,error::ErrorKind, IResult, Parser};
204/// use nom::combinator::opt;
205/// use nom::character::complete::alpha1;
206/// # fn main() {
207///
208/// fn parser(i: &str) -> IResult<&str, Option<&str>> {
209///   opt(alpha1).parse(i)
210/// }
211///
212/// assert_eq!(parser("abcd;"), Ok((";", Some("abcd"))));
213/// assert_eq!(parser("123;"), Ok(("123;", None)));
214/// # }
215/// ```
216pub fn opt<I: Clone, E: ParseError<I>, F>(
217  f: F,
218) -> impl Parser<I, Output = Option<<F as Parser<I>>::Output>, Error = E>
219where
220  F: Parser<I, Error = E>,
221{
222  Opt { parser: f }
223}
224
225/// Parser implementation for [opt]
226pub struct Opt<F> {
227  parser: F,
228}
229
230impl<I, F: Parser<I>> Parser<I> for Opt<F>
231where
232  I: Clone,
233{
234  type Output = Option<<F as Parser<I>>::Output>;
235
236  type Error = <F as Parser<I>>::Error;
237
238  #[inline(always)]
239  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
240    let i = input.clone();
241    match self
242      .parser
243      .process::<OutputM<OM::Output, Check, OM::Incomplete>>(input)
244    {
245      Ok((i, o)) => Ok((i, OM::Output::map(o, Some))),
246      Err(Err::Error(_)) => Ok((i, OM::Output::bind(|| None))),
247      Err(Err::Failure(e)) => Err(Err::Failure(e)),
248      Err(Err::Incomplete(i)) => Err(Err::Incomplete(i)),
249    }
250  }
251}
252
253/// Calls the parser if the condition is met.
254///
255/// ```rust
256/// # use nom::{Err, error::{Error, ErrorKind}, IResult, Parser};
257/// use nom::combinator::cond;
258/// use nom::character::complete::alpha1;
259/// # fn main() {
260///
261/// fn parser(b: bool, i: &str) -> IResult<&str, Option<&str>> {
262///   cond(b, alpha1).parse(i)
263/// }
264///
265/// assert_eq!(parser(true, "abcd;"), Ok((";", Some("abcd"))));
266/// assert_eq!(parser(false, "abcd;"), Ok(("abcd;", None)));
267/// assert_eq!(parser(true, "123;"), Err(Err::Error(Error::new("123;", ErrorKind::Alpha))));
268/// assert_eq!(parser(false, "123;"), Ok(("123;", None)));
269/// # }
270/// ```
271pub fn cond<I, E: ParseError<I>, F>(
272  b: bool,
273  f: F,
274) -> impl Parser<I, Output = Option<<F as Parser<I>>::Output>, Error = E>
275where
276  F: Parser<I, Error = E>,
277{
278  Cond {
279    parser: if b { Some(f) } else { None },
280  }
281}
282
283/// Parser implementation for [cond]
284pub struct Cond<F> {
285  parser: Option<F>,
286}
287
288impl<I, F> Parser<I> for Cond<F>
289where
290  F: Parser<I>,
291{
292  type Output = Option<<F as Parser<I>>::Output>;
293  type Error = <F as Parser<I>>::Error;
294
295  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
296    match &mut self.parser {
297      None => Ok((input, OM::Output::bind(|| None))),
298      Some(f) => f
299        .process::<OM>(input)
300        .map(|(i, o)| (i, OM::Output::map(o, Some))),
301    }
302  }
303}
304
305/// Tries to apply its parser without consuming the input.
306///
307/// ```rust
308/// # use nom::{Err,error::ErrorKind, IResult, Parser};
309/// use nom::combinator::peek;
310/// use nom::character::complete::alpha1;
311/// # fn main() {
312///
313/// let mut parser = peek(alpha1);
314///
315/// assert_eq!(parser.parse("abcd;"), Ok(("abcd;", "abcd")));
316/// assert_eq!(parser.parse("123;"), Err(Err::Error(("123;", ErrorKind::Alpha))));
317/// # }
318/// ```
319pub fn peek<I: Clone, F>(
320  parser: F,
321) -> impl Parser<I, Output = <F as Parser<I>>::Output, Error = <F as Parser<I>>::Error>
322where
323  F: Parser<I>,
324{
325  Peek { parser }
326}
327
328/// Parsr implementation for [peek]
329pub struct Peek<F> {
330  parser: F,
331}
332
333impl<I, F> Parser<I> for Peek<F>
334where
335  I: Clone,
336  F: Parser<I>,
337{
338  type Output = <F as Parser<I>>::Output;
339  type Error = <F as Parser<I>>::Error;
340
341  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
342    let i = input.clone();
343    match self.parser.process::<OM>(input) {
344      Ok((_, o)) => Ok((i, o)),
345      Err(e) => Err(e),
346    }
347  }
348}
349
350/// returns its input if it is at the end of input data
351///
352/// When we're at the end of the data, this combinator
353/// will succeed
354///
355/// ```
356/// # use std::str;
357/// # use nom::{Err, error::ErrorKind, IResult};
358/// # use nom::combinator::eof;
359///
360/// # fn main() {
361/// let parser = eof;
362/// assert_eq!(parser("abc"), Err(Err::Error(("abc", ErrorKind::Eof))));
363/// assert_eq!(parser(""), Ok(("", "")));
364/// # }
365/// ```
366pub fn eof<I: Input + Clone, E: ParseError<I>>(input: I) -> IResult<I, I, E> {
367  if input.input_len() == 0 {
368    let clone = input.clone();
369    Ok((input, clone))
370  } else {
371    Err(Err::Error(E::from_error_kind(input, ErrorKind::Eof)))
372  }
373}
374
375/// Transforms Incomplete into `Error`.
376///
377/// ```rust
378/// # use nom::{Err,error::ErrorKind, IResult, Parser};
379/// use nom::bytes::streaming::take;
380/// use nom::combinator::complete;
381/// # fn main() {
382///
383/// let mut parser = complete(take(5u8));
384///
385/// assert_eq!(parser.parse("abcdefg"), Ok(("fg", "abcde")));
386/// assert_eq!(parser.parse("abcd"), Err(Err::Error(("abcd", ErrorKind::Complete))));
387/// # }
388/// ```
389pub fn complete<I: Clone, O, E: ParseError<I>, F>(
390  parser: F,
391) -> impl Parser<I, Output = O, Error = E>
392where
393  F: Parser<I, Output = O, Error = E>,
394{
395  MakeComplete { parser }
396}
397
398/// Parser implementation for [complete]
399pub struct MakeComplete<F> {
400  parser: F,
401}
402
403impl<I, F> Parser<I> for MakeComplete<F>
404where
405  I: Clone,
406  F: Parser<I>,
407{
408  type Output = <F as Parser<I>>::Output;
409  type Error = <F as Parser<I>>::Error;
410
411  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
412    let i = input.clone();
413
414    match self
415      .parser
416      .process::<OutputM<OM::Output, OM::Error, Complete>>(input)
417    {
418      Err(Err::Incomplete(_)) => Err(Err::Error(OM::Error::bind(|| {
419        <F as Parser<I>>::Error::from_error_kind(i, ErrorKind::Complete)
420      }))),
421      Err(e) => Err(e),
422      Ok(o) => Ok(o),
423    }
424  }
425}
426
427/// Succeeds if all the input has been consumed by its child parser.
428///
429/// ```rust
430/// # use nom::{Err,error::ErrorKind, IResult, Parser};
431/// use nom::combinator::all_consuming;
432/// use nom::character::complete::alpha1;
433/// # fn main() {
434///
435/// let mut parser = all_consuming(alpha1);
436///
437/// assert_eq!(parser.parse("abcd"), Ok(("", "abcd")));
438/// assert_eq!(parser.parse("abcd;"),Err(Err::Error((";", ErrorKind::Eof))));
439/// assert_eq!(parser.parse("123abcd;"),Err(Err::Error(("123abcd;", ErrorKind::Alpha))));
440/// # }
441/// ```
442pub fn all_consuming<I, E: ParseError<I>, F>(
443  parser: F,
444) -> impl Parser<I, Output = <F as Parser<I>>::Output, Error = E>
445where
446  I: Input,
447  F: Parser<I, Error = E>,
448{
449  AllConsuming { parser }
450}
451
452/// Parser implementation for [all_consuming]
453pub struct AllConsuming<F> {
454  parser: F,
455}
456
457impl<I, F> Parser<I> for AllConsuming<F>
458where
459  I: Input,
460  F: Parser<I>,
461{
462  type Output = <F as Parser<I>>::Output;
463  type Error = <F as Parser<I>>::Error;
464
465  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
466    let (input, res) = self.parser.process::<OM>(input)?;
467    if input.input_len() == 0 {
468      Ok((input, res))
469    } else {
470      Err(Err::Error(OM::Error::bind(|| {
471        <F as Parser<I>>::Error::from_error_kind(input, ErrorKind::Eof)
472      })))
473    }
474  }
475}
476
477/// Returns the result of the child parser if it satisfies a verification function.
478///
479/// The verification function takes as argument a reference to the output of the
480/// parser.
481///
482/// ```rust
483/// # use nom::{Err,error::ErrorKind, IResult, Parser};
484/// use nom::combinator::verify;
485/// use nom::character::complete::alpha1;
486/// # fn main() {
487///
488/// let mut parser = verify(alpha1, |s: &str| s.len() == 4);
489///
490/// assert_eq!(parser.parse("abcd"), Ok(("", "abcd")));
491/// assert_eq!(parser.parse("abcde"), Err(Err::Error(("abcde", ErrorKind::Verify))));
492/// assert_eq!(parser.parse("123abcd;"),Err(Err::Error(("123abcd;", ErrorKind::Alpha))));
493/// # }
494/// ```
495pub fn verify<I: Clone, O2, E: ParseError<I>, F, G>(
496  first: F,
497  second: G,
498) -> impl Parser<I, Output = <F as Parser<I>>::Output, Error = E>
499where
500  F: Parser<I, Error = E>,
501  G: Fn(&O2) -> bool,
502  <F as Parser<I>>::Output: Borrow<O2>,
503  O2: ?Sized,
504{
505  Verify {
506    first,
507    second,
508    o2: PhantomData,
509  }
510}
511
512/// Parser iplementation for verify
513pub struct Verify<F, G, O2: ?Sized> {
514  first: F,
515  second: G,
516  o2: PhantomData<O2>,
517}
518
519impl<I, F: Parser<I>, G, O2> Parser<I> for Verify<F, G, O2>
520where
521  I: Clone,
522  G: Fn(&O2) -> bool,
523  <F as Parser<I>>::Output: Borrow<O2>,
524  O2: ?Sized,
525{
526  type Output = <F as Parser<I>>::Output;
527
528  type Error = <F as Parser<I>>::Error;
529
530  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
531    let (i, o) = self
532      .first
533      .process::<OutputM<Emit, OM::Error, OM::Incomplete>>(input.clone())?;
534
535    if (self.second)(o.borrow()) {
536      Ok((i, OM::Output::bind(|| o)))
537    } else {
538      Err(Err::Error(OM::Error::bind(move || {
539        let e: ErrorKind = ErrorKind::Verify;
540        <F as Parser<I>>::Error::from_error_kind(input, e)
541      })))
542    }
543  }
544}
545
546/// Returns the provided value if the child parser succeeds.
547///
548/// ```rust
549/// # use nom::{Err,error::ErrorKind, IResult, Parser};
550/// use nom::combinator::value;
551/// use nom::character::complete::alpha1;
552/// # fn main() {
553///
554/// let mut parser = value(1234, alpha1);
555///
556/// assert_eq!(parser.parse("abcd"), Ok(("", 1234)));
557/// assert_eq!(parser.parse("123abcd;"), Err(Err::Error(("123abcd;", ErrorKind::Alpha))));
558/// # }
559/// ```
560pub fn value<I, O1: Clone, E: ParseError<I>, F>(
561  val: O1,
562  parser: F,
563) -> impl Parser<I, Output = O1, Error = E>
564where
565  F: Parser<I, Error = E>,
566{
567  parser.map(move |_| val.clone())
568}
569
570/// Succeeds if the child parser returns an error.
571///
572/// ```rust
573/// # use nom::{Err,error::ErrorKind, IResult, Parser};
574/// use nom::combinator::not;
575/// use nom::character::complete::alpha1;
576/// # fn main() {
577///
578/// let mut parser = not(alpha1);
579///
580/// assert_eq!(parser.parse("123"), Ok(("123", ())));
581/// assert_eq!(parser.parse("abcd"), Err(Err::Error(("abcd", ErrorKind::Not))));
582/// # }
583/// ```
584pub fn not<I: Clone, E: ParseError<I>, F>(parser: F) -> impl Parser<I, Output = (), Error = E>
585where
586  F: Parser<I, Error = E>,
587{
588  Not { parser }
589}
590
591/// Parser implementation for [not]
592pub struct Not<F> {
593  parser: F,
594}
595
596impl<I, F> Parser<I> for Not<F>
597where
598  I: Clone,
599  F: Parser<I>,
600{
601  type Output = ();
602  type Error = <F as Parser<I>>::Error;
603
604  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
605    let i = input.clone();
606    match self.parser.process::<OM>(input) {
607      Ok(_) => Err(Err::Error(OM::Error::bind(|| {
608        <F as Parser<I>>::Error::from_error_kind(i, ErrorKind::Not)
609      }))),
610      Err(Err::Error(_)) => Ok((i, OM::Output::bind(|| ()))),
611      Err(e) => Err(e),
612    }
613  }
614}
615
616/// If the child parser was successful, return the consumed input as produced value.
617///
618/// ```rust
619/// # use nom::{Err,error::ErrorKind, IResult, Parser};
620/// use nom::combinator::recognize;
621/// use nom::character::complete::{char, alpha1};
622/// use nom::sequence::separated_pair;
623/// # fn main() {
624///
625/// let mut parser = recognize(separated_pair(alpha1, char(','), alpha1));
626///
627/// assert_eq!(parser.parse("abcd,efgh"), Ok(("", "abcd,efgh")));
628/// assert_eq!(parser.parse("abcd;"),Err(Err::Error((";", ErrorKind::Char))));
629/// # }
630/// ```
631pub fn recognize<I: Clone + Offset + Input, E: ParseError<I>, F>(
632  parser: F,
633) -> impl Parser<I, Output = I, Error = E>
634where
635  F: Parser<I, Error = E>,
636{
637  Recognize { parser }
638}
639
640/// Parser implementation for [recognize]
641pub struct Recognize<F> {
642  parser: F,
643}
644
645impl<I, F> Parser<I> for Recognize<F>
646where
647  I: Clone + Offset + Input,
648  F: Parser<I>,
649{
650  type Output = I;
651  type Error = <F as Parser<I>>::Error;
652
653  #[inline(always)]
654  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
655    let i = input.clone();
656    match self
657      .parser
658      .process::<OutputM<Check, OM::Error, OM::Incomplete>>(i)
659    {
660      Ok((i, _)) => {
661        let index = input.offset(&i);
662        Ok((i, OM::Output::bind(|| input.take(index))))
663      }
664      Err(e) => Err(e),
665    }
666  }
667}
668
669/// if the child parser was successful, return the consumed input with the output
670/// as a tuple. Functions similarly to [recognize](fn.recognize.html) except it
671/// returns the parser output as well.
672///
673/// This can be useful especially in cases where the output is not the same type
674/// as the input, or the input is a user defined type.
675///
676/// Returned tuple is of the format `(consumed input, produced output)`.
677///
678/// ```rust
679/// # use nom::{Err,error::ErrorKind, IResult, Parser};
680/// use nom::combinator::{consumed, value, recognize, map};
681/// use nom::character::complete::{char, alpha1};
682/// use nom::bytes::complete::tag;
683/// use nom::sequence::separated_pair;
684///
685/// fn inner_parser(input: &str) -> IResult<&str, bool> {
686///     value(true, tag("1234")).parse(input)
687/// }
688///
689/// # fn main() {
690///
691/// let mut consumed_parser = consumed(value(true, separated_pair(alpha1, char(','), alpha1)));
692///
693/// assert_eq!(consumed_parser.parse("abcd,efgh1"), Ok(("1", ("abcd,efgh", true))));
694/// assert_eq!(consumed_parser.parse("abcd;"),Err(Err::Error((";", ErrorKind::Char))));
695///
696///
697/// // the first output (representing the consumed input)
698/// // should be the same as that of the `recognize` parser.
699/// let mut recognize_parser = recognize(inner_parser);
700/// let mut consumed_parser = map(consumed(inner_parser), |(consumed, output)| consumed);
701///
702/// assert_eq!(recognize_parser.parse("1234"), consumed_parser.parse("1234"));
703/// assert_eq!(recognize_parser.parse("abcd"), consumed_parser.parse("abcd"));
704/// # }
705/// ```
706pub fn consumed<I, F, E>(
707  parser: F,
708) -> impl Parser<I, Output = (I, <F as Parser<I>>::Output), Error = E>
709where
710  I: Clone + Offset + Input,
711  E: ParseError<I>,
712  F: Parser<I, Error = E>,
713{
714  Consumed { parser }
715}
716
717/// Parser implementation for [consumed]
718pub struct Consumed<F> {
719  parser: F,
720}
721
722impl<I, F> Parser<I> for Consumed<F>
723where
724  I: Clone + Offset + Input,
725  F: Parser<I>,
726{
727  type Output = (I, <F as Parser<I>>::Output);
728  type Error = <F as Parser<I>>::Error;
729
730  #[inline(always)]
731  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
732    let i = input.clone();
733    match self.parser.process::<OM>(i) {
734      Ok((remaining, result)) => {
735        let index = input.offset(&remaining);
736
737        Ok((
738          remaining,
739          OM::Output::map(result, |res| {
740            let consumed = input.take(index);
741            (consumed, res)
742          }),
743        ))
744      }
745      Err(e) => Err(e),
746    }
747  }
748}
749
750/// Transforms an [`Err::Error`] (recoverable) to [`Err::Failure`] (unrecoverable)
751///
752/// This commits the parse result, preventing alternative branch paths like with
753/// [`nom::branch::alt`][crate::branch::alt].
754///
755/// # Example
756///
757/// Without `cut`:
758/// ```rust
759/// # use nom::{Err,error::ErrorKind, IResult, Parser};
760/// # use nom::character::complete::{one_of, digit1};
761/// # use nom::combinator::rest;
762/// # use nom::branch::alt;
763/// # use nom::sequence::preceded;
764/// # fn main() {
765///
766/// fn parser(input: &str) -> IResult<&str, &str> {
767///   alt((
768///     preceded(one_of("+-"), digit1),
769///     rest
770///   )).parse(input)
771/// }
772///
773/// assert_eq!(parser("+10 ab"), Ok((" ab", "10")));
774/// assert_eq!(parser("ab"), Ok(("", "ab")));
775/// assert_eq!(parser("+"), Ok(("", "+")));
776/// # }
777/// ```
778///
779/// With `cut`:
780/// ```rust
781/// # use nom::{Err,error::ErrorKind, IResult, Parser, error::Error};
782/// # use nom::character::complete::{one_of, digit1};
783/// # use nom::combinator::rest;
784/// # use nom::branch::alt;
785/// # use nom::sequence::preceded;
786/// use nom::combinator::cut;
787/// # fn main() {
788///
789/// fn parser(input: &str) -> IResult<&str, &str> {
790///   alt((
791///     preceded(one_of("+-"), cut(digit1)),
792///     rest
793///   )).parse(input)
794/// }
795///
796/// assert_eq!(parser("+10 ab"), Ok((" ab", "10")));
797/// assert_eq!(parser("ab"), Ok(("", "ab")));
798/// assert_eq!(parser("+"), Err(Err::Failure(Error { input: "", code: ErrorKind::Digit })));
799/// # }
800/// ```
801pub fn cut<I, E: ParseError<I>, F>(
802  parser: F,
803) -> impl Parser<I, Output = <F as Parser<I>>::Output, Error = E>
804where
805  F: Parser<I, Error = E>,
806{
807  Cut { parser }
808}
809
810/// Parser implementation for [cut]
811pub struct Cut<F> {
812  parser: F,
813}
814
815impl<I, F> Parser<I> for Cut<F>
816where
817  F: Parser<I>,
818{
819  type Output = <F as Parser<I>>::Output;
820
821  type Error = <F as Parser<I>>::Error;
822
823  #[inline(always)]
824  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
825    match self
826      .parser
827      .process::<OutputM<OM::Output, Emit, OM::Incomplete>>(input)
828    {
829      Err(Err::Error(e)) => Err(Err::Failure(e)),
830      Err(Err::Failure(e)) => Err(Err::Failure(e)),
831      Err(Err::Incomplete(i)) => Err(Err::Incomplete(i)),
832      Ok((i, o)) => Ok((i, o)),
833    }
834  }
835}
836
837/// automatically converts the child parser's result to another type
838///
839/// it will be able to convert the output value and the error value
840/// as long as the `Into` implementations are available
841///
842/// ```rust
843/// # use nom::{IResult, Parser};
844/// use nom::combinator::into;
845/// use nom::character::complete::alpha1;
846/// # fn main() {
847///
848/// fn parser1(i: &str) -> IResult<&str, &str> {
849///   alpha1(i)
850/// }
851///
852/// let mut parser2 = into(parser1);
853///
854/// // the parser converts the &str output of the child parser into a Vec<u8>
855/// let bytes: IResult<&str, Vec<u8>> = parser2.parse("abcd");
856/// assert_eq!(bytes, Ok(("", vec![97, 98, 99, 100])));
857/// # }
858/// ```
859pub fn into<I, O1, O2, E1, E2, F>(parser: F) -> impl Parser<I, Output = O2, Error = E2>
860where
861  O2: From<O1>,
862  E2: From<E1>,
863  E1: ParseError<I>,
864  E2: ParseError<I>,
865  F: Parser<I, Output = O1, Error = E1>,
866{
867  parser.into::<O2, E2>()
868}
869
870/// Creates an iterator from input data and a parser.
871///
872/// Call the iterator's [ParserIterator::finish] method to get the remaining input if successful,
873/// or the error value if we encountered an error.
874///
875/// On [`Err::Error`], iteration will stop. To instead chain an error up, see [`cut`].
876///
877/// ```rust
878/// use nom::{combinator::iterator, IResult, bytes::complete::tag, character::complete::alpha1, sequence::terminated};
879/// use std::collections::HashMap;
880///
881/// let data = "abc|defg|hijkl|mnopqr|123";
882/// let mut it = iterator(data, terminated(alpha1, tag("|")));
883///
884/// let parsed = it.by_ref().map(|v| (v, v.len())).collect::<HashMap<_,_>>();
885/// let res: IResult<_,_> = it.finish();
886///
887/// assert_eq!(parsed, [("abc", 3usize), ("defg", 4), ("hijkl", 5), ("mnopqr", 6)].iter().cloned().collect());
888/// assert_eq!(res, Ok(("123", ())));
889/// ```
890pub fn iterator<Input, Error, F>(input: Input, f: F) -> ParserIterator<Input, Error, F>
891where
892  F: Parser<Input>,
893  Error: ParseError<Input>,
894{
895  ParserIterator {
896    iterator: f,
897    input,
898    state: Some(State::Running),
899  }
900}
901
902/// Main structure associated to the [iterator] function.
903pub struct ParserIterator<I, E, F> {
904  iterator: F,
905  input: I,
906  state: Option<State<E>>,
907}
908
909impl<I: Clone, E, F> ParserIterator<I, E, F> {
910  /// Returns the remaining input if parsing was successful, or the error if we encountered an error.
911  pub fn finish(mut self) -> IResult<I, (), E> {
912    match self.state.take().unwrap() {
913      State::Running | State::Done => Ok((self.input, ())),
914      State::Failure(e) => Err(Err::Failure(e)),
915      State::Incomplete(i) => Err(Err::Incomplete(i)),
916    }
917  }
918}
919
920impl<Input, Output, Error, F> core::iter::Iterator for ParserIterator<Input, Error, F>
921where
922  F: Parser<Input, Output = Output, Error = Error>,
923  Input: Clone,
924{
925  type Item = Output;
926
927  fn next(&mut self) -> Option<Self::Item> {
928    if let State::Running = self.state.take().unwrap() {
929      let input = self.input.clone();
930
931      match (self.iterator).parse(input) {
932        Ok((i, o)) => {
933          self.input = i;
934          self.state = Some(State::Running);
935          Some(o)
936        }
937        Err(Err::Error(_)) => {
938          self.state = Some(State::Done);
939          None
940        }
941        Err(Err::Failure(e)) => {
942          self.state = Some(State::Failure(e));
943          None
944        }
945        Err(Err::Incomplete(i)) => {
946          self.state = Some(State::Incomplete(i));
947          None
948        }
949      }
950    } else {
951      None
952    }
953  }
954}
955
956enum State<E> {
957  Running,
958  Done,
959  Failure(E),
960  Incomplete(Needed),
961}
962
963/// a parser which always succeeds with given value without consuming any input.
964///
965/// It can be used for example as the last alternative in `alt` to
966/// specify the default case.
967///
968/// ```rust
969/// # use nom::{Err,error::ErrorKind, IResult, Parser};
970/// use nom::branch::alt;
971/// use nom::combinator::{success, value};
972/// use nom::character::complete::char;
973/// # fn main() {
974///
975/// let mut parser = success::<_,_,(_,ErrorKind)>(10);
976/// assert_eq!(parser.parse("xyz"), Ok(("xyz", 10)));
977///
978/// let mut sign = alt((value(-1, char('-')), value(1, char('+')), success::<_,_,(_,ErrorKind)>(1)));
979/// assert_eq!(sign.parse("+10"), Ok(("10", 1)));
980/// assert_eq!(sign.parse("-10"), Ok(("10", -1)));
981/// assert_eq!(sign.parse("10"), Ok(("10", 1)));
982/// # }
983/// ```
984pub fn success<I, O: Clone, E: ParseError<I>>(val: O) -> impl Parser<I, Output = O, Error = E> {
985  Success {
986    val,
987    e: PhantomData,
988  }
989}
990
991/// Parser implementation for [success]
992pub struct Success<O: Clone, E> {
993  val: O,
994  e: PhantomData<E>,
995}
996
997impl<I, O, E> Parser<I> for Success<O, E>
998where
999  O: Clone,
1000  E: ParseError<I>,
1001{
1002  type Output = O;
1003  type Error = E;
1004
1005  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
1006    Ok((input, OM::Output::bind(|| self.val.clone())))
1007  }
1008}
1009
1010/// A parser which always fails.
1011///
1012/// ```rust
1013/// # use nom::{Err, error::ErrorKind, IResult, Parser};
1014/// use nom::combinator::fail;
1015///
1016/// let s = "string";
1017/// assert_eq!(fail::<_, &str, _>().parse(s), Err(Err::Error((s, ErrorKind::Fail))));
1018/// ```
1019pub fn fail<I, O, E: ParseError<I>>() -> impl Parser<I, Output = O, Error = E> {
1020  Fail {
1021    o: PhantomData,
1022    e: PhantomData,
1023  }
1024}
1025
1026/// Parser implementation for [fail]
1027pub struct Fail<O, E> {
1028  o: PhantomData<O>,
1029  e: PhantomData<E>,
1030}
1031
1032impl<I, O, E> Parser<I> for Fail<O, E>
1033where
1034  E: ParseError<I>,
1035{
1036  type Output = O;
1037  type Error = E;
1038
1039  fn process<OM: OutputMode>(&mut self, input: I) -> PResult<OM, I, Self::Output, Self::Error> {
1040    Err(Err::Error(OM::Error::bind(|| {
1041      E::from_error_kind(input, ErrorKind::Fail)
1042    })))
1043  }
1044}
nom/combinator/mod.rs

nom/combinator/
mod.rs
