Module multi

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 with Extend.
• 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 an Err.

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

• collect_separated_terminated
  Parse a series of 1 or more things, separated by separator, terminated by terminator, and collect them into a collection using Extend.
• parse_separated_terminated
  Parse a series of 1 or more things, separated by separator, terminated by terminator, and fold them together using a folding function.
• parse_separated_terminated_res
  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.