the-sett/parser-recoverable - version: 1.0.0

for more information visit the package's GitHub page

Package contains the following modules:

Contacts for Support - @rupertlssmith on https://elmlang.slack.com - @rupert on https://discourse.elm-lang.org

parser-recoverable

the-sett/parser-recoverable is an extension to elm/parser that helps recovering from parsing errors. It is designed as a drop-in replacement for elm/parser by following its API closely, except for a few minor changes. The aim is to help create parsers that will tolerate syntax errors and get back on track and allow parsing to continue. In this case a parser may still produce a result, but may also produce some errors.

Parsers that produce Result and Errors

The type signature of the Parser and its run function are:

type alias Parser context problem value =
    Parser.Advanced.Parser context problem (Outcome context problem value)

run : Parser c x a -> String -> Outcome c x a

type Outcome context problem value
    = Success value
    | Partial (List (DeadEnd context problem)) value
    | Failure (List (DeadEnd context problem))

Outcome describes the possible outcomes from running a parser:

Recovery Tactics

Parser.Recoverable.Tactics provides some simple recovery tactics that can be manually added to parsing code.

The aim is to get a parser back into a position where it can continue running, not to attempt to correct individual tokens. For example, if the parser was expecting an integer but did not get one, recovering by inserting a default value such as 0 could work, but it will likely be better if the parser skips ahead until it finds some place it can safely restart from, such as the next ;, and report the whole expression with the missing integer value as an error.

Recovery tactics are always associated with Parsers, not tokens. Often a recovery tactic will be associated with a larger piece of parsing logic, and not just an individual Parser building block such as symbol or keyword.

The available recovery tactics are:

Recoverable Sequences

Parser.Recoverable.Sequence provides a recoverable version of sequence, that will allow errors in the sequence items, and will fast forward to the next separator or end token to recover.

The examples/src/ArrayOfInts.elm example demonstrates this, and lets you experiment with what happens with different options for the trailing separator token (Forbidden, Optional or Mandatory).

Use Cases

A recoverable parser can be useful for a compiler parser, as it may allow more errors to be found in source code than might otherwise be found; the error reporting could be more complete. Normally, code with syntax errors should be rejected by a compiler as correct syntax is a quality gateway on the code.

A more appropriate use case might be for writing an interactive editor. When code is in the act of being edited it will pass through many states where the syntax is not correct. Source code analysis could still be run, and such an editor might be able to make auto complete suggestions, even when the code is not syntactically complete.

Discussion on Elm Discourse

Relevant discussion on Elm Discourse is here:

https://discourse.elm-lang.org/t/parsers-with-error-recovery/6262

Thanks to Matthew Griffith for supplying some tolerant parsing code, which I took as a starting point for developing this package.