Module nom_supreme::multi [−][src]
Expand description
Perfected looping parsers designed to behave more reliably and provide more useful parse errors.
The combinators in this module all generally follow the same pattern for
parsing in a loop. They parse an item; then, they attempt to parse a
terminator
. If the terminator
is found, the parse returns successfully;
otherwise, they attempt to parse a separator
. If they fail to parse either
a separator
or a terminator
, the parse fails; otherwise, it will continue
on to parse the next item. The parsed items are collected together into a final
value; each combinator does this in a slightly different way:
collect_separated_terminated
collects the parsed items into a collection withExtend
.parse_separated_terminated
combines the parsed items with a folding function.parse_separated_terminated_res
combines the parsed items with a fallible folding function; it may return early if the folding function returns anErr
.
These combinators always parse at least 1 item. If you want 0 or more things
to be parsed, use opt
or alt
to handle that case.
These combinators will stop as soon as they find a terminator
. If you wish
to have a terminator
parser that is the same as your separator
, you’ll need
to add some extra context to the terminator parser; perhaps a lookahead
with peek
.
These combinators exists to provide meaningful parse errors. By requiring a
terminator
, we can ensure that they don’t suffer from the normal folding
parser problem of unconditionally returning success because a subparser failure
is interpreted as the end of the loop. This ensures that potentially important
errors aren’t thrown away.
The combinators will attempt to smartly allow 0-length matches. It will allow subparsers to have 0-length matches, but if a full loop is made without any progress being made, we assume we’ve encountered an infinite loop and return a parse error.
Functions
Parse a series of 1 or more things, separated by separator
, terminated by
terminator
, and collect them into a collection using Extend
.
Parse a series of 1 or more things, separated by separator
, terminated by
terminator
, and fold them together using a folding function.
Parse a series of 1 or more things, separated by some separator
, terminated
by some terminator
, folding them all together with a fallible fold function.