Module nom

Expand description

Parser combinator library for building zero-copy parsers.

nom is a parser combinator library that enables building parsers by combining small, reusable parsing functions.

Rather than using separate grammar definition tools or generating code, nom parsers are written directly in Rust as composable functions. Each parser function takes an input slice and returns either the remaining input with the parsed value, or an error. These small parsers can be combined using combinator functions to build complex parsers that match the structure of your grammar.

Parser combinators have tradeoffs vs. other parser architectures, but it is nice to have one at hand when you need it, and nom is well-tested and well-maintained. And it is fast.

Key features include:

Zero-copy parsing that works with input slices directly
Streaming support for incomplete input (useful for network protocols)
Both byte-oriented and character-oriented parsing
Rich set of built-in parsers and combinators
Strong type safety with compile-time validation

§Examples

Parsing a simple numeric value:

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::digit1,
};

fn parse_number(input: &str) -> IResult<&str, &str> {
    digit1(input)
}

let result = parse_number("123abc");
assert_eq!(result, Ok(("abc", "123")));

Combining parsers with sequence operations:

use nom::{
    IResult,
    bytes::complete::tag,
    character::complete::digit1,
    sequence::tuple,
};

fn parse_date(input: &str) -> IResult<&str, (&str, &str, &str)> {
    tuple((
        digit1,
        tag("-"),
        digit1,
        tag("-"),
        digit1,
    ))(input)
    .map(|(rest, (year, _, month, _, day))| (rest, (year, month, day)))
}

let result = parse_date("2023-12-25 text");
assert_eq!(result, Ok((" text", ("2023", "12", "25"))));

Modules§

bits: Bit level parsers
branch: Choice combinators
bytes: Parsers recognizing bytes streams
character: Character specific parsers and combinators
combinator: General purpose combinators
error: Error management
lib: Lib module to re-export everything needed from std or core/alloc. This is how serde does it, albeit there it is not public.
multi: Combinators applying their child parser multiple times
number: Parsers recognizing numbers
sequence: Combinators applying parsers in sequence

Macros§

error_node_position: Creates a parse error from a nom::ErrorKind, the position in the input and the next error in the parsing tree
error_position: Creates a parse error from a nom::ErrorKind and the position in the input

Structs§

And: Implementation of Parser::and
AndThen: Implementation of Parser::and_then
Check: Applies the parser, but do not a produce a value
Complete: Indicates that the input data is complete: no more data may be added later
Emit: Produces a value. This is the default behaviour for parsers
FlatMap: Implementation of Parser::flat_map
Into: Implementation of Parser::into
Map: Implementation of Parser::map
MapOpt: Implementation of Parser::map_opt
MapRes: Implementation of Parser::map_res
Or: Implementation of Parser::or
OutputM: Holds the parser execution modifiers: output Mode, error Mode and streaming behaviour for input data
SaturatingIterator: A saturating iterator for usize.
Streaming: Indicates that the input data is streaming: more data may be available later

Enums§

CompareResult: Indicates whether a comparison was successful, an error, or if more data was needed
Err: The Err enum indicates the parser was not successful
Needed: Contains information on needed data if a parser returned Incomplete

Traits§

AsBytes: Helper trait for types that can be viewed as a byte slice
AsChar: Transforms common types to a char for basic token parsing
Compare: Abstracts comparison operations
ErrorConvert: Equivalent From implementation to avoid orphan rules in bits parsers
ExtendInto: Abstracts something which can extend an Extend. Used to build modified input slices in escaped_transform
FindSubstring: Look for a substring in self
FindToken: Look for a token in self
Finish: Helper trait to convert a parser’s result to a more manageable type
HexDisplay: Helper trait to show a byte slice as a hex dump
Input: Parser input types must implement this trait
IsStreaming: Specifies the behaviour when a parser encounters an error that could be due to partial ata
Mode: Parser mode: influences how combinators build values
NomRange: Abstractions for range-like types.
Offset: Useful functions to calculate the offset between slices and show a hexdump of a slice
OutputMode: Trait Defining the parser’s execution
ParseTo: Used to integrate str’s parse() method
Parser: All nom parsers implement this trait
ToUsize: Helper trait to convert numbers to usize.

Type Aliases§

IResult: Holds the result of parsing functions
PResult: Parser result type

Module nomCopy item path