How does `nom::sequence::tuple` combine multiple parsers into a single tuple result?

nom::sequence::tuple takes multiple parsers as arguments and returns a parser that applies each one in sequence, collecting all successful results into a tuple with the same arity as the input parsers—if any parser fails, the entire tuple parser fails and backtracks. The function tuple((parser1, parser2, parser3)) produces a parser that returns ((I, O1, O2, O3), I) on success, where I is the remaining input and O1, O2, O3 are the outputs of each sub-parser. This enables building complex parsers from simpler ones while preserving all parsed values in a structured result.

Basic tuple Usage

use nom::{sequence::tuple, character::complete::{digit1, alpha1}, IResult};
 
fn basic_tuple() {
    // Combine two parsers
    let mut parser = tuple((alpha1, digit1));
    
    // Parse "abc123"
    let result: IResult<&str, (&str, &str)> = parser("abc123");
    
    match result {
        Ok((remaining, (letters, numbers))) => {
            assert_eq!(remaining, "");
            assert_eq!(letters, "abc");
            assert_eq!(numbers, "123");
        }
        Err(e) => panic!("Parse failed: {:?}", e),
    }
}

tuple returns a tuple of all parser results in order.

Three or More Parsers

use nom::{sequence::tuple, character::complete::{digit1, alpha1, char}, IResult};
 
fn multiple_parsers() {
    // Combine three parsers
    let mut parser = tuple((alpha1, char(':'), digit1));
    
    let result: IResult<&str, (&str, char, &str)> = parser("key:42");
    
    match result {
        Ok((remaining, (key, colon, value))) => {
            assert_eq!(remaining, "");
            assert_eq!(key, "key");
            assert_eq!(colon, ':');
            assert_eq!(value, "42");
        }
        Err(e) => panic!("Parse failed: {:?}", e),
    }
}

The output tuple grows with each additional parser.

Type Signature

use nom::{IResult, InputLength, Parser};
 
// The tuple function signature (simplified):
// pub fn tuple<I, O>(mut tuple: (P1, P2, ...)) -> impl Fn(I) -> IResult<I, (O1, O2, ...)>
// where
//     P1: Parser<I, O1>,
//     P2: Parser<I, O2>,
//     ...
 
// The input is a tuple of parsers
// The output is a parser that produces a tuple of outputs
 
fn type_signature() {
    // Input: (Parser<I, O1>, Parser<I, O2>, Parser<I, O3>)
    // Output: impl Parser<I, (O1, O2, O3)>
    
    // The input and output tuple arities match
    // Each parser in the input contributes one element to the output
}

The output tuple has the same number of elements as the input parser tuple.

Failure Propagation

use nom::{sequence::tuple, character::complete::{digit1, alpha1}, error::ErrorKind, IResult};
 
fn failure_propagation() {
    let mut parser = tuple((alpha1, digit1));
    
    // First parser fails
    let result = parser("123abc");
    assert!(result.is_err());
    // The entire tuple fails; digit1 is never called
    
    // Second parser fails
    let result = parser("abcdef");
    assert!(result.is_err());
    // alpha1 succeeds ("abcdef"), then digit1 fails
    
    // Partial consumption behavior:
    // On failure, the input is NOT consumed
    // The parser backtracks to the original position
}

If any parser fails, the entire tuple fails without consuming input.

Sequential Application

use nom::{sequence::tuple, character::complete::{alpha1, digit1, multispace0}, IResult};
 
fn sequential_application() {
    let mut parser = tuple((alpha1, multispace0, digit1));
    
    // Each parser is applied to the remaining input from the previous
    let result = parser("word   123extra");
    
    match result {
        Ok((remaining, (word, spaces, number))) => {
            // word is parsed first from full input
            assert_eq!(word, "word");
            // spaces is parsed from "   123extra"
            assert_eq!(spaces, "   ");
            // number is parsed from "123extra"
            assert_eq!(number, "123");
            // remaining is what's left
            assert_eq!(remaining, "extra");
        }
        Err(_) => panic!("Should succeed"),
    }
}

Each parser sees the input remaining after the previous parser.

Combining with Other Combinators

use nom::{sequence::tuple, character::complete::{char, digit1}, combinator::map, IResult};
 
fn with_map() {
    // Transform tuple output into a struct
    #[derive(Debug, PartialEq)]
    struct Point {
        x: i32,
        y: i32,
    }
    
    let mut parser = map(
        tuple((char('('), digit1, char(','), digit1, char(')'))),
        |(_, x, _, y, _): (char, &str, char, &str, char)| Point {
            x: x.parse().unwrap(),
            y: y.parse().unwrap(),
        }
    );
    
    let result = parser("(3,4)");
    assert_eq!(result, Ok(("", Point { x: 3, y: 4 })));
}

Combine tuple with map to transform results into structured types.

Ignoring Values in Tuple

use nom::{sequence::tuple, character::complete::{char, digit1}, combinator::map, IResult};
 
fn ignoring_values() {
    // When some parsed values are not needed
    let mut parser = map(
        tuple((char('('), digit1, char(','), digit1, char(')'))),
        |(_, x, _, y, _)| (x, y)  // Keep only the digits
    );
    
    let result: IResult<&str, (&str, &str)> = parser("(10,20)");
    assert_eq!(result, Ok(("", ("10", "20"))));
}
 
// Alternative: use preceded, delimited, separated_pair
use nom::sequence::{preceded, delimited, separated_pair};
 
fn alternatives() {
    // separated_pair is more idiomatic for this pattern
    let mut parser = separated_pair(digit1, char(','), digit1);
    let result = parser("10,20");
    assert_eq!(result, Ok(("", ("10", "20"))));
    
    // delimited for wrapped content
    let mut parser = delimited(char('('), separated_pair(digit1, char(','), digit1), char(')'));
    let result = parser("(10,20)");
    assert_eq!(result, Ok(("", ("10", "20"))));
}

For common patterns, specialized combinators may be more readable than tuple.

Nested Tuple Parsers

use nom::{sequence::tuple, character::complete::{alpha1, digit1, char}, IResult};
 
fn nested_tuples() {
    // Tuple parsers can be nested
    let mut parser = tuple((
        alpha1,
        tuple((char(':'), digit1)),
        alpha1
    ));
    
    let result: IResult<&str, (&str, (char, &str), &str)> = parser("a:123b");
    
    match result {
        Ok((remaining, (first, (_colon, number), last))) => {
            assert_eq!(first, "a");
            assert_eq!(number, "123");
            assert_eq!(last, "b");
            assert_eq!(remaining, "");
        }
        Err(_) => panic!("Should succeed"),
    }
}

Tuples can contain other tuples, creating nested result structures.

Zero and One Element Tuples

use nom::{sequence::tuple, character::complete::alpha1, IResult};
 
fn zero_one_element() {
    // Zero-element tuple (unit type)
    let mut empty_parser = tuple(());
    let result: IResult<&str, ()> = empty_parser("anything");
    assert_eq!(result, Ok(("anything", ())));
    // Always succeeds, consumes nothing
    
    // One-element tuple (wraps in single-element tuple)
    let mut single_parser = tuple((alpha1,));
    let result: IResult<&str, (&str,)> = single_parser("abc");
    assert_eq!(result, Ok(("", ("abc",))));
    // Note the trailing comma for single-element tuple syntax
}

Empty tuples always succeed; single-element tuples wrap the result.

Working with Different Return Types

use nom::{
    sequence::tuple,
    character::complete::{char, digit1, alpha1},
    bytes::complete::tag,
    IResult,
};
 
fn different_types() {
    // Each parser can return a different type
    let mut parser = tuple((
        alpha1,        // returns &str
        char(':'),     // returns char
        digit1,        // returns &str
        tag("end"),    // returns &str
    ));
    
    let result: IResult<&str, (&str, char, &str, &str)> = parser("key:123end");
    
    match result {
        Ok((remaining, (alpha, colon, digits, tag_result))) => {
            assert_eq!(alpha, "key");
            assert_eq!(colon, ':');
            assert_eq!(digits, "123");
            assert_eq!(tag_result, "end");
            assert_eq!(remaining, "");
        }
        Err(_) => panic!("Should succeed"),
    }
}

Each parser in the tuple contributes its own return type to the output tuple.

Parsing Structured Data

use nom::{
    sequence::tuple,
    character::complete::{char, digit1, multispace0},
    combinator::map,
    IResult,
};
 
fn structured_data() {
    // Parse a key-value pair with type annotation
    // Format: "name : type = value"
    
    #[derive(Debug, PartialEq)]
    struct Field {
        name: String,
        type_name: String,
        value: String,
    }
    
    let mut parser = map(
        tuple((
            alpha1,                    // name
            multispace0,
            char(':'),
            multispace0,
            alpha1,                    // type
            multispace0,
            char('='),
            multispace0,
            digit1,                    // value
        )),
        |(name, _, _, _, type_name, _, _, _, value)| Field {
            name: name.to_string(),
            type_name: type_name.to_string(),
            value: value.to_string(),
        }
    );
    
    let result = parser("count : int = 42");
    assert_eq!(result, Ok(("", Field {
        name: "count".to_string(),
        type_name: "int".to_string(),
        value: "42".to_string(),
    })));
}

Complex structured parsing uses tuple to sequence all components.

Error Handling

use nom::{sequence::tuple, character::complete::{alpha1, digit1}, error::{Error, ErrorKind}, IResult};
 
fn error_handling() {
    let mut parser = tuple((alpha1, digit1));
    
    // Error on first parser
    let result = parser("123");
    match result {
        Err(nom::Err::Error(Error { input, code })) => {
            // input is the original input
            // code indicates what failed
            assert_eq!(input, "123");
            // alpha1 failed
        }
        _ => panic!("Should error"),
    }
    
    // Error on second parser
    let result = parser("abc");
    match result {
        Err(nom::Err::Error(Error { input, code })) => {
            // input is what digit1 saw ("")
            // because alpha1 consumed "abc"
            // But nom backtracks, so original input is restored
            // (depending on error mode)
        }
        _ => panic!("Should error"),
    }
}

Errors indicate which parser failed; input position is restored on failure.

Complete vs Streaming

use nom::{
    sequence::tuple,
    character::complete::digit1,
    character::streaming::digit1 as streaming_digit1,
    IResult,
};
 
fn complete_vs_streaming() {
    // Complete mode: assumes input is complete
    let mut complete_parser = tuple((digit1::<&str, nom::error::Error<&str>>, digit1));
    // digit1 in complete mode fails if there are no digits
    
    // Streaming mode: may need more input
    let mut streaming_parser = tuple((
        streaming_digit1::<&str, nom::error::Error<&str>>,
        streaming_digit1
    ));
    // digit1 in streaming mode returns Incomplete if insufficient input
    
    // tuple works with both complete and streaming parsers
    // All parsers in the tuple should use the same mode
}

tuple works with both complete and streaming input modes.

Performance Characteristics

use nom::{sequence::tuple, character::complete::digit1, IResult};
 
fn performance() {
    // tuple does NOT allocate
    // It returns a stack-allocated tuple
    
    // Each parser is called in sequence
    // No intermediate collections
    
    // The output tuple is constructed after all parsers succeed
    // If any fails, no output tuple is created
    
    let mut parser = tuple((digit1, digit1, digit1));
    
    // This is equivalent to manual sequencing:
    fn manual_parse(input: &str) -> IResult<&str, (&str, &str, &str)> {
        let (input, a) = digit1(input)?;
        let (input, b) = digit1(input)?;
        let (input, c) = digit1(input)?;
        Ok((input, (a, b, c)))
    }
    
    // tuple is zero-overhead abstraction over manual sequencing
}

tuple is a zero-overhead abstraction; it compiles to sequential parser calls.

Implementing Custom Tuple-Like Combinators

use nom::{IResult, Parser};
 
fn custom_combinator<I, O1, O2, E>(
    mut parser1: impl Parser<I, O1, E>,
    mut parser2: impl Parser<I, O2, E>,
) -> impl Fn(I) -> IResult<I, (O1, O2), E>
where
    I: Clone,
{
    move |input: I| {
        let (remaining, result1) = parser1.parse(input)?;
        let (remaining, result2) = parser2.parse(remaining)?;
        Ok((remaining, (result1, result2)))
    }
}
 
// This is essentially what tuple does internally
// The macro system handles arbitrary arities

The tuple combinator generalizes this pattern to any number of parsers.

Real-World Example: URL Parsing

use nom::{
    sequence::tuple,
    character::complete::{alpha1, digit1, char},
    bytes::complete::tag,
    combinator::opt,
    IResult,
};
 
fn url_parsing() {
    // Simplified URL: scheme://host:port/path
    
    #[derive(Debug)]
    struct Url<'a> {
        scheme: &'a str,
        host: &'a str,
        port: Option<u16>,
        path: &'a str,
    }
    
    fn parse_url(input: &str) -> IResult<&str, Url> {
        let (remaining, (scheme, _, host, port, path)) = tuple((
            alpha1,                    // scheme
            tag("://"),                // separator
            alpha1,                    // host
            opt(                       // optional port
                tuple((char(':'), digit1))
            ),
            tag("/"),                  // path start
        ))(input)?;
        
        // Remaining is the path
        Ok((remaining, Url {
            scheme,
            host,
            port: port.map(|(_, p)| p.parse().unwrap()),
            path: remaining,
        }))
    }
    
    let result = parse_url("http://example:8080/path");
    assert!(result.is_ok());
}

Complex real-world parsing combines tuple with other combinators.

Synthesis

How tuple combines parsers:

// tuple applies parsers sequentially
// (P1, P2, P3) -> applies P1, then P2, then P3
// Results are collected into tuple: (O1, O2, O3)
 
// If any parser fails:
// - The entire tuple fails
// - Input is restored to original position
// - No output tuple is created
 
// On success:
// - Returns remaining input and tuple of results
// - Each result is in the same position as its parser

Key characteristics:

// 1. Sequential: parsers run in order
// 2. Result preservation: all outputs are kept
// 3. Atomic failure: any failure fails the whole thing
// 4. Backtracking: input restored on failure
// 5. Zero overhead: compiles to sequential calls

When to use tuple:

// Use tuple when:
// - You need all parser results
// - Parsers must all succeed
// - Order matters
// - Building structured output
 
// Use alternatives when:
// - Only some values needed (preceded, delimited)
// - Pairs of values (separated_pair)
// - Optional values (opt)

Key insight: nom::sequence::tuple combines multiple parsers by applying them sequentially and collecting all results into a tuple with matching arity. It provides ordered, atomic parsing where all parsers must succeed—any failure causes the entire operation to fail with backtracking. The combinator is zero-overhead and works with any parser types that share the same input. For patterns where only some values are needed, specialized combinators like preceded, delimited, or separated_pair may be more readable, but tuple is the general-purpose building block that underlies them all.

Loading page…

How does nom::sequence::tuple combine multiple parsers into a single tuple result?

Basic tuple Usage

Three or More Parsers

Type Signature

Failure Propagation

Sequential Application

Combining with Other Combinators

Ignoring Values in Tuple

Nested Tuple Parsers

Zero and One Element Tuples

Working with Different Return Types

Parsing Structured Data

Error Handling

Complete vs Streaming

Performance Characteristics

Implementing Custom Tuple-Like Combinators

Real-World Example: URL Parsing

Synthesis

How does nom::sequence::tuple combine multiple parsers into a single tuple result?

Basic tuple Usage

Three or More Parsers

Type Signature

Failure Propagation

Sequential Application

Combining with Other Combinators

Ignoring Values in Tuple

Nested Tuple Parsers

Zero and One Element Tuples

Working with Different Return Types

Parsing Structured Data

Error Handling

Complete vs Streaming

Performance Characteristics

Implementing Custom Tuple-Like Combinators

Real-World Example: URL Parsing

Synthesis

How does `nom::sequence::tuple` combine multiple parsers into a single tuple result?

How does `nom::sequence::tuple` combine multiple parsers into a single tuple result?