Module winnow::combinator

source ·
Expand description

List of parsers and combinators

Note: this list is meant to provide a nicer way to find a parser than reading through the documentation on docs.rs. Function combinators are organized in module so they are a bit easier to find.

Basic elements

Those are used to recognize the lowest level elements of your grammar, like, “here is a dot”, or “here is an big endian integer”.

combinatorusageinputoutputcomment
one_ofone_of("abc")"abc"Ok(("bc", 'a'))Matches one of the provided characters (works with non ASCII characters too)
none_ofnone_of("abc")"xyab"Ok(("yab", 'x'))Matches anything but the provided characters
tagtag("hello")"hello world"Ok((" world", "hello"))Recognizes a specific suite of characters or bytes
tag_no_casetag_no_case("hello")"HeLLo World"Ok((" World", "HeLLo"))Case insensitive comparison. Note that case insensitive comparison is not well defined for unicode, and that you might have bad surprises
taketake(4)"hello"Ok(("o", "hell"))Takes a specific number of bytes or characters
take_while0take_while0(is_alphabetic)"abc123"Ok(("123", "abc"))Returns the longest list of bytes for which the provided pattern matches. take_while1 does the same, but must return at least one character
take_till0take_till0(is_alphabetic)"123abc"Ok(("abc", "123"))Returns the longest list of bytes or characters until the provided pattern matches. take_till1 does the same, but must return at least one character. This is the reverse behaviour from take_while0: take_till(f) is equivalent to take_while0(\|c\| !f(c))
take_until0take_until0("world")"Hello world"Ok(("world", "Hello "))Returns the longest list of bytes or characters until the provided tag is found. take_until1 does the same, but must return at least one character

Choice combinators

combinatorusageinputoutputcomment
altalt((tag("ab"), tag("cd")))"cdef"Ok(("ef", "cd"))Try a list of parsers and return the result of the first successful one
dispatch---match for parsers
permutationpermutation((tag("ab"), tag("cd"), tag("12")))"cd12abc"Ok(("c", ("ab", "cd", "12"))Succeeds when all its child parser have succeeded, whatever the order

Sequence combinators

combinatorusageinputoutputcomment
delimiteddelimited(char('('), take(2), char(')'))"(ab)cd"Ok(("cd", "ab"))
precededpreceded(tag("ab"), tag("XY"))"abXYZ"Ok(("Z", "XY"))
terminatedterminated(tag("ab"), tag("XY"))"abXYZ"Ok(("Z", "ab"))
separated_pairseparated_pair(tag("hello"), char(','), tag("world"))"hello,world!"Ok(("!", ("hello", "world")))
(...) (tuples)(tag("ab"), tag("XY"), take(1))"abXYZ!"Ok(("!", ("ab", "XY", "Z")))Chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple

Applying a parser multiple times

combinatorusageinputoutputcomment
countcount(take(2), 3)"abcdefgh"Ok(("gh", vec!["ab", "cd", "ef"]))Applies the child parser a specified number of times
many0many0(tag("ab"))"abababc"Ok(("c", vec!["ab", "ab", "ab"]))Applies the parser 0 or more times and returns the list of results in a Vec. many1 does the same operation but must return at least one element
many_m_nmany_m_n(1, 3, tag("ab"))"ababc"Ok(("c", vec!["ab", "ab"]))Applies the parser between m and n times (n included) and returns the list of results in a Vec
many_till0many_till0(tag( "ab" ), tag( "ef" ))"ababefg"Ok(("g", (vec!["ab", "ab"], "ef")))Applies the first parser until the second applies. Returns a tuple containing the list of results from the first in a Vec and the result of the second
separated0separated0(tag("ab"), tag(","))"ab,ab,ab."Ok((".", vec!["ab", "ab", "ab"]))separated1 works like separated0 but must returns at least one element
fold_many0fold_many0(be_u8, \|\| 0, \|acc, item\| acc + item)[1, 2, 3]Ok(([], 6))Applies the parser 0 or more times and folds the list of return values. The fold_many1 version must apply the child parser at least one time
fold_many_m_nfold_many_m_n(1, 2, be_u8, \|\| 0, \|acc, item\| acc + item)[1, 2, 3]Ok(([3], 3))Applies the parser between m and n times (n included) and folds the list of return value
length_countlength_count(number, tag("ab"))"2ababab"Ok(("ab", vec!["ab", "ab"]))Gets a number from the first parser, then applies the second parser that many times
  • eof: Returns its input if it is at the end of input data
  • Parser::complete_err: Replaces an Incomplete returned by the child parser with an Backtrack

Modifiers

  • cond: Conditional combinator. Wraps another parser and calls it if the condition is met
  • Parser::flat_map: method to map a new parser from the output of the first parser, then apply that parser over the rest of the input
  • Parser::value: method to replace the result of a parser
  • Parser::map: method to map a function on the result of a parser
  • Parser::and_then: Applies a second parser over the output of the first one
  • Parser::verify_map: Maps a function returning an Option on the output of a parser
  • Parser::map_res: Maps a function returning a Result on the output of a parser
  • Parser::parse_to: Apply std::str::FromStr to the output of the parser
  • not: Returns a result only if the embedded parser returns Backtrack or Incomplete. Does not consume the input
  • opt: Make the underlying parser optional
  • peek: Returns a result without consuming the input
  • Parser::recognize: If the child parser was successful, return the consumed input as the produced value
  • Parser::with_recognized: If the child parser was successful, return a tuple of the consumed input and the produced output.
  • Parser::span: If the child parser was successful, return the location of the consumed input as the produced value
  • Parser::with_span: If the child parser was successful, return a tuple of the location of the consumed input and the produced output.
  • Parser::verify: Returns the result of the child parser if it satisfies a verification function

Error management and debugging

  • cut_err: Commit the parse result, disallowing alternative parsers from being attempted
  • backtrack_err: Attemmpts a parse, allowing alternative parsers to be attempted despite use of cut_err
  • Parser::context: Add context to the error if the parser fails
  • trace: Print the parse state with the debug feature flag
  • todo(): Placeholder parser

Remaining combinators

  • success: Returns a value without consuming any input, always succeeds
  • fail: Inversion of success. Always fails.
  • Parser::by_ref: Allow moving &mut impl Parser into other parsers

Text parsing

  • any: Matches one token

  • tab: Matches a tab character \t

  • crlf: Recognizes the string \r\n

  • line_ending: Recognizes an end of line (both \n and \r\n)

  • newline: Matches a newline character \n

  • not_line_ending: Recognizes a string of any char except \r or \n

  • rest: Return the remaining input

  • alpha0: Recognizes zero or more lowercase and uppercase alphabetic characters: [a-zA-Z]. alpha1 does the same but returns at least one character

  • alphanumeric0: Recognizes zero or more numerical and alphabetic characters: [0-9a-zA-Z]. alphanumeric1 does the same but returns at least one character

  • space0: Recognizes zero or more spaces and tabs. space1 does the same but returns at least one character

  • multispace0: Recognizes zero or more spaces, tabs, carriage returns and line feeds. multispace1 does the same but returns at least one character

  • digit0: Recognizes zero or more numerical characters: [0-9]. digit1 does the same but returns at least one character

  • hex_digit0: Recognizes zero or more hexadecimal numerical characters: [0-9A-Fa-f]. hex_digit1 does the same but returns at least one character

  • oct_digit0: Recognizes zero or more octal characters: [0-7]. oct_digit1 does the same but returns at least one character

  • float: Parse a floating point number in a byte string

  • dec_int: Decode a variable-width, decimal signed integer

  • dec_uint: Decode a variable-width, decimal unsigned integer

  • hex_uint: Decode a variable-width, hexadecimal integer

  • escaped: Matches a byte string with escaped characters

  • escaped_transform: Matches a byte string with escaped characters, and returns a new string with the escaped characters replaced

Character test functions

Use these functions with a combinator like take_while0:

Binary format parsing

  • length_data: Gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslice
  • length_value: Gets a number from the first parser, takes a subslice of the input of that size, then applies the second parser on that subslice. If the second parser returns Incomplete, length_value will return an error

Integers

Parsing integers from binary formats can be done in two ways: With parser functions, or combinators with configurable endianness.

Bit stream parsing

  • bits: Transforms the current input type (byte slice &[u8]) to a bit stream on which bit specific parsers and more general combinators can be applied
  • bytes: Transforms its bits stream input back into a byte slice for the underlying parser
  • take: Take a set number of its
  • tag: Check if a set number of bis matches a pattern
  • bool: Match any one bit

Structs

Functions