When using `nom`, how do you combine parsers with `>>` vs `|` operators?

In nom, the >> (sequence) and | (alternative) operators are parser combinators that combine smaller parsers into larger ones. The >> operator sequences two parsers, running them in order and succeeding only if both succeed, returning the result of the second parser. The | operator tries alternatives in order, returning the result of the first parser that succeeds, or failing if all alternatives fail. These operators come from the nom::sequence::tuple and nom::branch::alt patterns but provide a more readable infix syntax when using the appropriate traits. Understanding how they compose is essential for building complex parsers from simple building blocks.

Basic Parser Setup

use nom::{
    IResult,
    bytes::complete::{tag, take},
    character::complete::{alpha1, digit1, space1},
    sequence::preceded,
    branch::alt,
};
 
// Basic parsers return IResult<Input, Output>
fn parse_hello(input: &str) -> IResult<&str, &str> {
    tag("hello")(input)
}
 
fn parse_world(input: &str) -> IResult<&str, &str> {
    tag("world")(input)
}
 
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_basic_parsers() {
        // tag returns the matched string on success
        assert_eq!(parse_hello("hello world"), Ok((" world", "hello")));
        assert_eq!(parse_world("world!"), Ok(("!", "world")));
        
        // Failure returns Err
        assert!(parse_hello("goodbye").is_err());
    }
}

Basic parsers in nom take an input and return IResult<Input, Output>.

Sequence Combination with `>>`

use nom::{IResult, bytes::complete::tag, sequence::tuple};
 
// The >> operator sequences parsers, keeping the rightmost result
fn sequence_with_tuple(input: &str) -> IResult<&str, (&str, &str)> {
    // tuple runs multiple parsers in sequence, returning all results
    tuple((tag("hello"), tag(" "), tag("world")))(input)
}
 
fn sequence_example() {
    let result = sequence_with_tuple("hello world");
    assert_eq!(result, Ok(("", ("hello", " ", "world"))));
    
    // If any parser fails, the whole sequence fails
    let result = sequence_with_tuple("hello there");
    assert!(result.is_err());  // " there" doesn't match " world"
}

tuple runs parsers in sequence and returns all results; >> is a specialized form.

The >> Operator Behavior

use nom::{IResult, bytes::complete::tag, sequence::preceded, Parser};
 
// >> is defined in nom's Parser trait
// It sequences two parsers and returns the result of the second
fn sequence_with_shiftr(input: &str) -> IResult<&str, &str> {
    // preceded is equivalent to >> for two parsers
    // preceded(first, second) runs first, then second, returns second
    preceded(tag("hello "), tag("world"))(input)
}
 
// Using the >> operator syntax (requires importing Parser trait)
fn sequence_operator(input: &str) -> IResult<&str, &str> {
    // tag("hello ") >> tag("world") would be:
    // Run tag("hello "), then tag("world"), return "world"
    preceded(tag("hello "), tag("world"))(input)
}
 
fn shift_right_examples() {
    let input = "hello world";
    
    // preceded discards first result, keeps second
    let result = sequence_with_shiftr(input);
    assert_eq!(result, Ok(("", "world")));
    
    // First parser must consume its input
    let result = sequence_with_shiftr("hellox world");
    assert!(result.is_err());  // "hellox " doesn't match "hello "
}

The >> (shift-right) operator sequences parsers and returns the second result.

Alternative Combination with `|`

use nom::{IResult, bytes::complete::tag, branch::alt};
 
// The | operator tries alternatives, returning the first success
fn alternative_with_alt(input: &str) -> IResult<&str, &str> {
    alt((tag("hello"), tag("goodbye"), tag("hi")))(input)
}
 
fn alternative_example() {
    // First alternative matches
    let result = alternative_with_alt("hello world");
    assert_eq!(result, Ok((" world", "hello")));
    
    // Second alternative matches
    let result = alternative_with_alt("goodbye world");
    assert_eq!(result, Ok((" world", "goodbye")));
    
    // Third alternative matches
    let result = alternative_with_alt("hi there");
    assert_eq!(result, Ok((" there", "hi")));
    
    // None match
    let result = alternative_with_alt("farewell");
    assert!(result.is_err());
}

alt tries each parser in order; the | operator provides this functionality.

Combining >> and | Operators

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::alpha1,
    sequence::{preceded, tuple},
    branch::alt,
};
 
// Parse a greeting followed by a name
fn parse_greeting(input: &str) -> IResult<&str, (&str, &str)> {
    // Sequence: greeting >> name
    // Alternative for greeting: "hello" | "hi" | "hey"
    tuple((
        alt((tag("hello"), tag("hi"), tag("hey"))),
        tag(" "),
        alpha1
    ))(input)
}
 
fn combined_example() {
    let result = parse_greeting("hello Alice");
    assert_eq!(result, Ok(("", ("hello", " ", "Alice"))));
    
    let result = parse_greeting("hi Bob");
    assert_eq!(result, Ok(("", ("hi", " ", "Bob"))));
    
    let result = parse_greeting("hey Charlie");
    assert_eq!(result, Ok(("", ("hey", " ", "Charlie"))));
    
    // Invalid greeting
    let result = parse_greeting("greetings Dave");
    assert!(result.is_err());
}

Real parsers combine sequence and alternative operations.

Sequence Combinators in Detail

use nom::{
    IResult,
    bytes::complete::tag,
    sequence::{tuple, preceded, terminated, delimited, pair},
};
 
fn sequence_combinators() {
    let input = "<content>";
    
    // tuple: run all, return all results
    let result: IResult<&str, (&str, &str, &str)> = 
        tuple((tag("<"), tag("content"), tag(">")))(input);
    assert_eq!(result, Ok(("", ("<", "content", ">"))));
    
    // preceded: run both, return second (equivalent to >>)
    let result: IResult<&str, &str> = 
        preceded(tag("<"), tag("content"))(input);
    assert_eq!(result, Ok((">", "content")));
    
    // terminated: run both, return first
    let result: IResult<&str, &str> = 
        terminated(tag("<content"), tag(">"))(input);
    assert_eq!(result, Ok(("", "<content")));
    
    // delimited: run three, return middle
    let result: IResult<&str, &str> = 
        delimited(tag("<"), tag("content"), tag(">"))(input);
    assert_eq!(result, Ok(("", "content")));
    
    // pair: run two, return both
    let result: IResult<&str, (&str, &str)> = 
        pair(tag("<"), tag("content"))(input);
    assert_eq!(result, Ok((">", ("<", "content"))));
}

nom provides several sequence combinators with different result behaviors.

Alternative Combinators in Detail

use nom::{
    IResult,
    bytes::complete::tag,
    branch::{alt, permutation},
    character::complete::{alpha1, digit1},
};
 
fn alternative_combinators() {
    // alt: try in order, return first success
    let result: IResult<&str, &str> = 
        alt((tag("abc"), tag("abd"), tag("abe")))("abd123");
    assert_eq!(result, Ok(("123", "abd")));
    
    // alt stops at first match
    let result: IResult<&str, &str> = 
        alt((tag("a"), tag("ab"), tag("abc")))("abc");
    assert_eq!(result, Ok(("bc", "a")));  // Matches "a" first
    
    // Order matters for overlapping patterns!
    let result: IResult<&str, &str> = 
        alt((tag("abc"), tag("a")))("abc");
    assert_eq!(result, Ok(("", "abc")));  // "abc" tried first
}
 
fn permutation_example() {
    // permutation: match all in any order
    let input = "123abc";
    let result: IResult<&str, (&str, &str)> = 
        permutation((digit1, alpha1))(input);
    assert_eq!(result, Ok(("", ("123", "abc"))));
    
    // Different order
    let input = "abc123";
    let result: IResult<&str, (&str, &str)> = 
        permutation((digit1, alpha1))(input);
    assert_eq!(result, Ok(("", ("123", "abc"))));
}

alt tries alternatives in order; permutation matches all in any order.

Return Type Differences

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::digit1,
    sequence::{preceded, pair},
    branch::alt,
    combinator::map,
};
 
// >> returns only the second result
fn shift_right_return() {
    let input = "hello123";
    
    // preceded (>>) returns only the second parser's result
    let result: IResult<&str, &str> = 
        preceded(tag("hello"), digit1)(input);
    assert_eq!(result, Ok(("", "123")));
    
    // "hello" is discarded, only "123" returned
}
 
// | returns the type of the chosen alternative
fn alternative_return() {
    // All alternatives must return the same type
    let result: IResult<&str, &str> = 
        alt((tag("hello"), tag("world")))("world");
    assert_eq!(result, Ok(("", "world")));
    
    // If alternatives have different return types, use map to unify
    let result: IResult<&str, i64> = alt((
        map(tag("one"), |_| 1),
        map(tag("two"), |_| 2),
        map(digit1, |s: &str| s.parse().unwrap()),
    ))("two");
    assert_eq!(result, Ok(("", 2)));
}

>> discards the first result; | alternatives must return compatible types.

Building Complex Parsers

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::{alpha1, digit1, space0, space1, char},
    sequence::{tuple, preceded, delimited, separated_pair},
    branch::alt,
    combinator::{map, opt, recognize},
    multi::{many0, many1},
};
 
// Parse a simple expression: number or identifier
#[derive(Debug, PartialEq)]
enum Expr {
    Number(i64),
    Identifier(String),
    BinaryOp(Box<Expr>, char, Box<Expr>),
}
 
fn parse_number(input: &str) -> IResult<&str, Expr> {
    map(digit1, |s: &str| Expr::Number(s.parse().unwrap()))(input)
}
 
fn parse_identifier(input: &str) -> IResult<&str, Expr> {
    map(alpha1, |s: &str| Expr::Identifier(s.to_string()))(input)
}
 
fn parse_primary(input: &str) -> IResult<&str, Expr> {
    // Alternative: number | identifier | (expression)
    alt((
        parse_number,
        parse_identifier,
        delimited(char('('), parse_expr, char(')')),
    ))(input)
}
 
fn parse_expr(input: &str) -> IResult<&str, Expr> {
    // For simplicity, just parse primary expressions
    parse_primary(input)
}
 
fn complex_parser_example() {
    let result = parse_expr("123");
    assert_eq!(result, Ok(("", Expr::Number(123))));
    
    let result = parse_expr("abc");
    assert_eq!(result, Ok(("", Expr::Identifier("abc".to_string()))));
}

Complex parsers are built by combining >> (sequence) and | (alternative).

Parsing Structured Data

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::{alpha1, alphanumeric1, digit1, space0, char, multispace0},
    sequence::{tuple, preceded, delimited, separated_pair},
    branch::alt,
    combinator::map,
    multi::many0,
};
 
#[derive(Debug)]
struct KeyValue {
    key: String,
    value: Value,
}
 
#[derive(Debug)]
enum Value {
    String(String),
    Number(i64),
    Boolean(bool),
}
 
fn parse_key(input: &str) -> IResult<&str, String> {
    map(alpha1, |s: &str| s.to_string())(input)
}
 
fn parse_string_value(input: &str) -> IResult<&str, Value> {
    map(
        delimited(char('"'), alphanumeric1, char('"')),
        |s: &str| Value::String(s.to_string())
    )(input)
}
 
fn parse_number_value(input: &str) -> IResult<&str, Value> {
    map(digit1, |s: &str| Value::Number(s.parse().unwrap()))(input)
}
 
fn parse_bool_value(input: &str) -> IResult<&str, Value> {
    map(
        alt((tag("true"), tag("false"))),
        |s: &str| Value::Boolean(s == "true")
    )(input)
}
 
fn parse_value(input: &str) -> IResult<&str, Value> {
    // Try each alternative in order
    alt((parse_string_value, parse_number_value, parse_bool_value))(input)
}
 
fn parse_key_value(input: &str) -> IResult<&str, KeyValue> {
    // Sequence: key >> ":" >> value
    map(
        tuple((
            parse_key,
            delimited(space0, char(':'), space0),
            parse_value
        )),
        |(key, _, value)| KeyValue { key, value }
    )(input)
}
 
fn structured_data_example() {
    let result = parse_key_value(r#"name: "Alice""#);
    assert_eq!(result, Ok(("", KeyValue { 
        key: "name".to_string(), 
        value: Value::String("Alice".to_string()) 
    })));
    
    let result = parse_key_value("count: 42");
    assert_eq!(result, Ok(("", KeyValue { 
        key: "count".to_string(), 
        value: Value::Number(42) 
    })));
    
    let result = parse_key_value("active: true");
    assert_eq!(result, Ok(("", KeyValue { 
        key: "active".to_string(), 
        value: Value::Boolean(true) 
    })));
}

Combining sequence and alternative combinators enables parsing complex structures.

Error Handling with Alternatives

use nom::{
    IResult,
    bytes::complete::tag,
    branch::alt,
    error::{Error, ErrorKind, ParseError, VerboseError, context},
    combinator::map,
};
 
// alt tries each parser and returns the error from the last one
fn alternative_errors() {
    let input = "xyz";
    
    // If all alternatives fail, alt returns the last error
    let result: IResult<&str, &str, Error<&str>> = 
        alt((tag("abc"), tag("def"), tag("ghi")))(input);
    
    assert!(result.is_err());
    // Error from trying "ghi" on "xyz"
}
 
// Using context for better error messages
fn parse_with_context(input: &str) -> IResult<&str, &str, VerboseError<&str>> {
    alt((
        context("expected 'hello'", tag("hello")),
        context("expected 'world'", tag("world")),
    ))(input)
}
 
fn error_context_example() {
    let result = parse_with_context("foo");
    assert!(result.is_err());
    // Error will include context about what was expected
}

alt returns the error from the last failed alternative; use context for better messages.

The Parser Trait and >> Operator

use nom::{
    IResult,
    bytes::complete::tag,
    Parser,
    sequence::preceded,
};
 
// The >> operator is part of the Parser trait
// It's equivalent to preceded for two parsers
fn parser_trait_example() {
    // Using preceded directly
    fn parse_after_hello(input: &str) -> IResult<&str, &str> {
        preceded(tag("hello "), tag("world"))(input)
    }
    
    // The Parser trait allows chaining
    // This is conceptually: tag("hello ") >> tag("world")
    fn parse_with_chain(input: &str) -> IResult<&str, &str> {
        tag("hello ")
            .and_then(|_| tag("world"))
            .parse(input)
            .map(|(remaining, _)| (remaining, "world"))
    }
    
    // Actually using >> requires the shift-right trait
    // In nom, this is typically done with preceded/terminated
}

The >> operator in nom is usually expressed using preceded for clarity.

Many0 and Many1 with Sequences

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::{alpha1, space1, char},
    sequence::{preceded, delimited},
    multi::{many0, many1, separated_list0},
    branch::alt,
};
 
fn parse_items(input: &str) -> IResult<&str, Vec<&str>> {
    // Parse zero or more comma-separated words
    separated_list0(char(','), alpha1)(input)
}
 
fn many_with_sequence(input: &str) -> IResult<&str, Vec<&str>> {
    // Parse many sequences
    many0(preceded(tag("item:"), alpha1))(input)
}
 
fn repeating_parsers_example() {
    let result = parse_items("apple,banana,cherry");
    assert_eq!(result, Ok(("", vec!["apple", "banana", "cherry"])));
    
    let result = parse_items("single");
    assert_eq!(result, Ok(("", vec!["single"])));
    
    let result = parse_items("");
    assert_eq!(result, Ok(("", vec![])));
    
    // Sequence repeated
    let result = many_with_sequence("item:one item:two item:three");
    assert_eq!(result, Ok((" item:two item:three", vec!["one"])));
    // Note: many0 doesn't consume between items - need space handling
}

Combining repetition with sequence/alternative creates powerful parsers.

Real-World Example: URL Parser

use nom::{
    IResult,
    bytes::complete::{tag, take_while, take_while1},
    character::complete::char,
    sequence::{preceded, tuple, separated_pair},
    branch::alt,
    combinator::{map, opt, recognize},
};
 
#[derive(Debug, PartialEq)]
struct Url<'a> {
    scheme: &'a str,
    host: &'a str,
    port: Option<u16>,
    path: &'a str,
}
 
fn parse_scheme(input: &str) -> IResult<&str, &str> {
    recognize(tuple((
        take_while1(|c: char| c.is_alphabetic()),
        tag("://")
    )))(input)
}
 
fn parse_host(input: &str) -> IResult<&str, &str> {
    take_while1(|c: char| c.is_alphanumeric() || c == '.' || c == '-')(input)
}
 
fn parse_port(input: &str) -> IResult<&str, u16> {
    preceded(char(':'), 
        map(take_while1(|c: char| c.is_numeric()), 
            |s: &str| s.parse().unwrap())
    )(input)
}
 
fn parse_path(input: &str) -> IResult<&str, &str> {
    alt((
        take_while(|c: char| c != ' ' && c != '\n'),
        map(tag(""), |_| "")
    ))(input)
}
 
fn parse_url(input: &str) -> IResult<&str, Url> {
    map(
        tuple((
            parse_scheme,          // scheme://
            parse_host,            // host
            opt(parse_port),       // :port (optional)
            parse_path             // /path
        )),
        |(scheme_with_sep, host, port, path)| {
            // Extract scheme without ://
            let scheme = &scheme_with_sep[..scheme_with_sep.len() - 3];
            Url { scheme, host, port, path }
        }
    )(input)
}
 
fn url_parser_example() {
    let result = parse_url("https://example.com/path");
    assert_eq!(result, Ok(("", Url {
        scheme: "https",
        host: "example.com",
        port: None,
        path: "/path"
    })));
    
    let result = parse_url("http://localhost:8080/api/data");
    assert_eq!(result, Ok(("", Url {
        scheme: "http",
        host: "localhost",
        port: Some(8080),
        path: "/api/data"
    })));
}

URL parsing combines sequence (scheme >> host >> port >> path) and alternatives (optional components).

Comparison Summary

| Aspect | >> (Sequence) | | (Alternative) | |--------|-----------------|-------------------| | Behavior | Run parsers in order | Try parsers in order | | Success | All must succeed | First success wins | | Failure | Any failure fails all | All failures fails all | | Return | Second result (with preceded) | Result of successful alternative | | Use case | Required sequence | Optional/multiple formats | | Error | First failure reported | Last failure reported |

Synthesis

The >> and | operators in nom provide fundamental parser combination:

Sequence (>> / preceded / tuple):

Runs parsers in order
All must succeed for the combination to succeed
Discards intermediate results (with preceded) or keeps all (with tuple)
Used when multiple elements must appear in order
Example: tag("(") >> content >> tag(")") for parenthesized expressions

Alternative (| / alt):

Tries parsers in order
Returns first successful result
All must fail for the combination to fail
Used when multiple formats are acceptable
Example: number | string | boolean for value parsing

Key patterns:

Build complex parsers from simple ones
tuple collects all results; preceded keeps only the second
alt tries alternatives; order matters for overlapping patterns
Use map to transform results and unify types
Use context for better error messages

Key insight: Parser combinators work by building up complex parsers from simple, well-tested primitives. The >> operator creates sequences where each step depends on the previous; the | operator creates branches where the parser adapts to the input. Together, they form a powerful DSL for describing grammars directly in Rust code, with the type system ensuring that composed parsers have compatible input and output types.

Loading page…

When using nom, how do you combine parsers with >> vs | operators?

Basic Parser Setup

Sequence Combination with >>

The >> Operator Behavior

Alternative Combination with |

Combining >> and | Operators

Sequence Combinators in Detail

Alternative Combinators in Detail

Return Type Differences

Building Complex Parsers

Parsing Structured Data

Error Handling with Alternatives

The Parser Trait and >> Operator

Many0 and Many1 with Sequences

Real-World Example: URL Parser

Comparison Summary

Synthesis

When using nom, how do you combine parsers with >> vs | operators?

Basic Parser Setup

Sequence Combination with >>

The >> Operator Behavior

Alternative Combination with |

Combining >> and | Operators

Sequence Combinators in Detail

Alternative Combinators in Detail

Return Type Differences

Building Complex Parsers

Parsing Structured Data

Error Handling with Alternatives

The Parser Trait and >> Operator

Many0 and Many1 with Sequences

Real-World Example: URL Parser

Comparison Summary

Synthesis

When using `nom`, how do you combine parsers with `>>` vs `|` operators?

Sequence Combination with `>>`

Alternative Combination with `|`

When using `nom`, how do you combine parsers with `>>` vs `|` operators?

Sequence Combination with `>>`

Alternative Combination with `|`