nom/sequence/
mod.rs

1//! Combinators applying parsers in sequence
2
3#[cfg(test)]
4mod tests;
5
6use crate::error::ParseError;
7use crate::internal::{IResult, Parser};
8use crate::{Check, OutputM, OutputMode, PResult};
9
10/// Gets an object from the first parser,
11/// then gets another object from the second parser.
12///
13/// # Arguments
14/// * `first` The first parser to apply.
15/// * `second` The second parser to apply.
16///
17/// # Example
18/// ```rust
19/// use nom::sequence::pair;
20/// use nom::bytes::complete::tag;
21/// use nom::{error::ErrorKind, Err, Parser};
22///
23/// let mut parser = pair(tag("abc"), tag("efg"));
24///
25/// assert_eq!(parser.parse("abcefg"), Ok(("", ("abc", "efg"))));
26/// assert_eq!(parser.parse("abcefghij"), Ok(("hij", ("abc", "efg"))));
27/// assert_eq!(parser.parse(""), Err(Err::Error(("", ErrorKind::Tag))));
28/// assert_eq!(parser.parse("123"), Err(Err::Error(("123", ErrorKind::Tag))));
29/// ```
30pub fn pair<I, O1, O2, E: ParseError<I>, F, G>(
31  first: F,
32  second: G,
33) -> impl Parser<I, Output = (O1, O2), Error = E>
34where
35  F: Parser<I, Output = O1, Error = E>,
36  G: Parser<I, Output = O2, Error = E>,
37{
38  first.and(second)
39}
40
41/// Matches an object from the first parser and discards it,
42/// then gets an object from the second parser.
43///
44/// # Arguments
45/// * `first` The opening parser.
46/// * `second` The second parser to get object.
47///
48/// ```rust
49/// # use nom::{Err, error::ErrorKind, Needed, Parser};
50/// # use nom::Needed::Size;
51/// use nom::sequence::preceded;
52/// use nom::bytes::complete::tag;
53///
54/// let mut parser = preceded(tag("abc"), tag("efg"));
55///
56/// assert_eq!(parser.parse("abcefg"), Ok(("", "efg")));
57/// assert_eq!(parser.parse("abcefghij"), Ok(("hij", "efg")));
58/// assert_eq!(parser.parse(""), Err(Err::Error(("", ErrorKind::Tag))));
59/// assert_eq!(parser.parse("123"), Err(Err::Error(("123", ErrorKind::Tag))));
60/// ```
61pub fn preceded<I, O, E: ParseError<I>, F, G>(
62  first: F,
63  second: G,
64) -> impl Parser<I, Output = O, Error = E>
65where
66  F: Parser<I, Error = E>,
67  G: Parser<I, Output = O, Error = E>,
68{
69  Preceded {
70    f: first,
71    g: second,
72  }
73}
74
75/// a
76pub struct Preceded<F, G> {
77  f: F,
78  g: G,
79}
80
81impl<I, E: ParseError<I>, F: Parser<I, Error = E>, G: Parser<I, Error = E>> Parser<I>
82  for Preceded<F, G>
83{
84  type Output = <G as Parser<I>>::Output;
85  type Error = E;
86
87  #[inline(always)]
88  fn process<OM: OutputMode>(&mut self, i: I) -> PResult<OM, I, Self::Output, Self::Error> {
89    let (i, _) = self
90      .f
91      .process::<OutputM<Check, OM::Error, OM::Incomplete>>(i)?;
92    let (i, o2) = self.g.process::<OM>(i)?;
93
94    Ok((i, o2))
95  }
96}
97
98/// Gets an object from the first parser,
99/// then matches an object from the second parser and discards it.
100///
101/// # Arguments
102/// * `first` The first parser to apply.
103/// * `second` The second parser to match an object.
104///
105/// ```rust
106/// # use nom::{Err, error::ErrorKind, Needed, Parser};
107/// # use nom::Needed::Size;
108/// use nom::sequence::terminated;
109/// use nom::bytes::complete::tag;
110///
111/// let mut parser = terminated(tag("abc"), tag("efg"));
112///
113/// assert_eq!(parser.parse("abcefg"), Ok(("", "abc")));
114/// assert_eq!(parser.parse("abcefghij"), Ok(("hij", "abc")));
115/// assert_eq!(parser.parse(""), Err(Err::Error(("", ErrorKind::Tag))));
116/// assert_eq!(parser.parse("123"), Err(Err::Error(("123", ErrorKind::Tag))));
117/// ```
118pub fn terminated<I, O, E: ParseError<I>, F, G>(
119  first: F,
120  second: G,
121) -> impl Parser<I, Output = O, Error = E>
122where
123  F: Parser<I, Output = O, Error = E>,
124  G: Parser<I, Error = E>,
125{
126  Terminated {
127    f: first,
128    g: second,
129  }
130}
131
132/// a
133pub struct Terminated<F, G> {
134  f: F,
135  g: G,
136}
137
138impl<I, E: ParseError<I>, F: Parser<I, Error = E>, G: Parser<I, Error = E>> Parser<I>
139  for Terminated<F, G>
140{
141  type Output = <F as Parser<I>>::Output;
142  type Error = E;
143
144  #[inline(always)]
145  fn process<OM: OutputMode>(&mut self, i: I) -> PResult<OM, I, Self::Output, Self::Error> {
146    let (i, o1) = self.f.process::<OM>(i)?;
147    let (i, _) = self
148      .g
149      .process::<OutputM<Check, OM::Error, OM::Incomplete>>(i)?;
150
151    Ok((i, o1))
152  }
153}
154
155/// Gets an object from the first parser,
156/// then matches an object from the sep_parser and discards it,
157/// then gets another object from the second parser.
158///
159/// # Arguments
160/// * `first` The first parser to apply.
161/// * `sep` The separator parser to apply.
162/// * `second` The second parser to apply.
163///
164/// ```rust
165/// # use nom::{Err, error::ErrorKind, Needed, Parser};
166/// # use nom::Needed::Size;
167/// use nom::sequence::separated_pair;
168/// use nom::bytes::complete::tag;
169///
170/// let mut parser = separated_pair(tag("abc"), tag("|"), tag("efg"));
171///
172/// assert_eq!(parser.parse("abc|efg"), Ok(("", ("abc", "efg"))));
173/// assert_eq!(parser.parse("abc|efghij"), Ok(("hij", ("abc", "efg"))));
174/// assert_eq!(parser.parse(""), Err(Err::Error(("", ErrorKind::Tag))));
175/// assert_eq!(parser.parse("123"), Err(Err::Error(("123", ErrorKind::Tag))));
176/// ```
177pub fn separated_pair<I, O1, O2, E: ParseError<I>, F, G, H>(
178  first: F,
179  sep: G,
180  second: H,
181) -> impl Parser<I, Output = (O1, O2), Error = E>
182where
183  F: Parser<I, Output = O1, Error = E>,
184  G: Parser<I, Error = E>,
185  H: Parser<I, Output = O2, Error = E>,
186{
187  first.and(preceded(sep, second))
188}
189
190/// Matches an object from the first parser and discards it,
191/// then gets an object from the second parser,
192/// and finally matches an object from the third parser and discards it.
193///
194/// # Arguments
195/// * `first` The first parser to apply and discard.
196/// * `second` The second parser to apply.
197/// * `third` The third parser to apply and discard.
198///
199/// ```rust
200/// # use nom::{Err, error::ErrorKind, Needed, Parser};
201/// # use nom::Needed::Size;
202/// use nom::sequence::delimited;
203/// use nom::bytes::complete::tag;
204///
205/// let mut parser = delimited(tag("("), tag("abc"), tag(")"));
206///
207/// assert_eq!(parser.parse("(abc)"), Ok(("", "abc")));
208/// assert_eq!(parser.parse("(abc)def"), Ok(("def", "abc")));
209/// assert_eq!(parser.parse(""), Err(Err::Error(("", ErrorKind::Tag))));
210/// assert_eq!(parser.parse("123"), Err(Err::Error(("123", ErrorKind::Tag))));
211/// ```
212pub fn delimited<I, O, E: ParseError<I>, F, G, H>(
213  first: F,
214  second: G,
215  third: H,
216) -> impl Parser<I, Output = O, Error = E>
217where
218  F: Parser<I, Error = E>,
219  G: Parser<I, Output = O, Error = E>,
220  H: Parser<I, Error = E>,
221{
222  preceded(first, terminated(second, third))
223}
224
225/// Helper trait for the tuple combinator.
226///
227/// This trait is implemented for tuples of parsers of up to 21 elements.
228#[deprecated(since = "8.0.0", note = "`Parser` is directly implemented for tuples")]
229#[allow(deprecated)]
230pub trait Tuple<I, O, E> {
231  /// Parses the input and returns a tuple of results of each parser.
232  fn parse_tuple(&mut self, input: I) -> IResult<I, O, E>;
233}
234
235#[allow(deprecated)]
236impl<Input, Output, Error: ParseError<Input>, F: Parser<Input, Output = Output, Error = Error>>
237  Tuple<Input, (Output,), Error> for (F,)
238{
239  fn parse_tuple(&mut self, input: Input) -> IResult<Input, (Output,), Error> {
240    self.0.parse(input).map(|(i, o)| (i, (o,)))
241  }
242}
243
244macro_rules! tuple_trait(
245  ($name1:ident $ty1:ident, $name2: ident $ty2:ident, $($name:ident $ty:ident),*) => (
246    tuple_trait!(__impl $name1 $ty1, $name2 $ty2; $($name $ty),*);
247  );
248  (__impl $($name:ident $ty: ident),+; $name1:ident $ty1:ident, $($name2:ident $ty2:ident),*) => (
249    tuple_trait_impl!($($name $ty),+);
250    tuple_trait!(__impl $($name $ty),+ , $name1 $ty1; $($name2 $ty2),*);
251  );
252  (__impl $($name:ident $ty: ident),+; $name1:ident $ty1:ident) => (
253    tuple_trait_impl!($($name $ty),+);
254    tuple_trait_impl!($($name $ty),+, $name1 $ty1);
255  );
256);
257
258macro_rules! tuple_trait_impl(
259  ($($name:ident $ty: ident),+) => (
260    #[allow(deprecated)]
261    impl<
262      Input: Clone, $($ty),+ , Error: ParseError<Input>,
263      $($name: Parser<Input, Output = $ty, Error = Error>),+
264    > Tuple<Input, ( $($ty),+ ), Error> for ( $($name),+ ) {
265      fn parse_tuple(&mut self, input: Input) -> IResult<Input, ( $($ty),+ ), Error> {
266        tuple_trait_inner!(0, self, input, (), $($name)+)
267
268      }
269    }
270  );
271);
272
273macro_rules! tuple_trait_inner(
274  ($it:tt, $self:expr, $input:expr, (), $head:ident $($id:ident)+) => ({
275    let (i, o) = $self.$it.parse($input)?;
276
277    succ!($it, tuple_trait_inner!($self, i, ( o ), $($id)+))
278  });
279  ($it:tt, $self:expr, $input:expr, ($($parsed:tt)*), $head:ident $($id:ident)+) => ({
280    let (i, o) = $self.$it.parse($input)?;
281
282    succ!($it, tuple_trait_inner!($self, i, ($($parsed)* , o), $($id)+))
283  });
284  ($it:tt, $self:expr, $input:expr, ($($parsed:tt)*), $head:ident) => ({
285    let (i, o) = $self.$it.parse($input)?;
286
287    Ok((i, ($($parsed)* , o)))
288  });
289);
290
291tuple_trait!(FnA A, FnB B, FnC C, FnD D, FnE E, FnF F, FnG G, FnH H, FnI I, FnJ J, FnK K, FnL L,
292  FnM M, FnN N, FnO O, FnP P, FnQ Q, FnR R, FnS S, FnT T, FnU U);
293
294// Special case: implement `Tuple` for `()`, the unit type.
295// This can come up in macros which accept a variable number of arguments.
296// Literally, `()` is an empty tuple, so it should simply parse nothing.
297#[allow(deprecated)]
298impl<I, E: ParseError<I>> Tuple<I, (), E> for () {
299  fn parse_tuple(&mut self, input: I) -> IResult<I, (), E> {
300    Ok((input, ()))
301  }
302}
303
304///Applies a tuple of parsers one by one and returns their results as a tuple.
305///There is a maximum of 21 parsers
306/// ```rust
307/// # use nom::{Err, error::ErrorKind};
308/// use nom::sequence::tuple;
309/// use nom::character::complete::{alpha1, digit1};
310/// let mut parser = tuple((alpha1, digit1, alpha1));
311///
312/// assert_eq!(parser("abc123def"), Ok(("", ("abc", "123", "def"))));
313/// assert_eq!(parser("123def"), Err(Err::Error(("123def", ErrorKind::Alpha))));
314/// ```
315#[deprecated(since = "8.0.0", note = "`Parser` is directly implemented for tuples")]
316#[allow(deprecated)]
317pub fn tuple<I, O, E: ParseError<I>, List: Tuple<I, O, E>>(
318  mut l: List,
319) -> impl FnMut(I) -> IResult<I, O, E> {
320  move |i: I| l.parse_tuple(i)
321}
nom/sequence/mod.rs

nom/sequence/
mod.rs
