This typeclass specifies how to format an error from a parser as a specified type.
An instance of this trait is required when calling parse
(or similar). By default, Parsley defines its own instance for ErrorBuilder[String]
found in the ErrorBuilder
companion object.
To implement this trait, a number of methods must be defined, as well the representation types for a variety of different components; the relation between the various methods is closely linked to the types that they both produce and consume. To only change the basics of formatting without having to define the entire instance, inherit from DefaultErrorBuilder
: this will mean, however, that the representation types cannot be overriden.
How an Error is Structured
There are two kinds of error messages that are generated by Parsley: Specialised and Vanilla. These are produced by different combinators and can be merged with other errors of the same type if both errors appear at the same offset. However, Specialised errors will take precedence over Vanilla errors if they appear at the same offset. The most common form of error is the Vanilla variant, which is generated by most combinators, except for some in errors.combinator
.
Both types of error share some common structure, namely:
The error preamble, which has the file and the position.
The content lines, the specifics of which differ between the two types of error.
The context lines, which has the surrounding lines of input for contextualisation.
Vanilla Errors
There are three kinds of content line found in a Vanilla error:
Unexpected info: this contains information about the kind of token that caused the error.
Expected info: this contains the information about what kinds of token could have avoided the error.
Reasons: these are the bespoke reasons that an error has occurred (as generated by
explain
).
There can be at most one unexpected line, at most one expected line, and zero or more reasons. Both of the unexpected and expected info are built up of error items, which are either: the end of input, a named token, raw input taken from the parser definition. These can all be formatted separately.
The overall structure of a Vanilla error is given in the following diagram:
┌───────────────────────────────────────────────────────────────────────┐
│ Vanilla Error │
│ ┌────────────────┐◄──────── position │
│ source │ │ │
│ │ │ line col│ │
│ ▼ │ │ ││ │
│ ┌─────┐ │ ▼ ▼│ end of input │
│ In foo.txt (line 1, column 5): │ │
│ ┌─────────────────────┐ │ │
│unexpected ─────►│ │ │ ┌───── expected │
│ │ ┌──────────┐ ◄──────────┘ │ │
│ unexpected end of input ▼ │
│ ┌──────────────────────────────────────┐ │
│ expected "(", "negate", digit, or letter │
│ │ └──────┘ └───┘ └────┘ ◄────── named│
│ │ ▲ └──────────┘ │ │
│ │ │ │ │
│ │ raw │ │
│ └─────────────────┬───────────┘ │
│ '-' is a binary operator │ │
│ └──────────────────────┘ │ │
│ ┌──────┐ ▲ │ │
│ │>3+4- │ │ expected items │
│ │ ^│ │ │
│ └──────┘ └───────────────── reason │
│ ▲ │
│ │ │
│ line info │
└───────────────────────────────────────────────────────────────────────┘
Specialised Errors
There is only one kind of content found in a Specialised error: a message. These are completely free-form, and are generated by the fail
combinator, as well as its derived combinators. There can be one or more messages in a Specialised error.
The overall structure of a Specialised error is given in the following diagram:
┌───────────────────────────────────────────────────────────────────────┐
│ Specialised Error │
│ ┌────────────────┐◄──────── position │
│ source │ │ │
│ │ │ line col │
│ ▼ │ │ │ │
│ ┌─────┐ │ ▼ ▼ │
│ In foo.txt (line 1, column 5): │
│ │
│ ┌───► something went wrong │
│ │ │
│ message ──┼───► it looks like a binary operator has no argument │
│ │ │
│ └───► '-' is a binary operator │
│ ┌──────┐ │
│ │>3+4- │ │
│ │ ^│ │
│ └──────┘ │
│ ▲ │
│ │ │
│ line info │
└───────────────────────────────────────────────────────────────────────┘
Type parameters
- Err
-
The final result type of the error message
Attributes
- Since
-
3.0.0
- Companion
- object
- Source
- ErrorBuilder.scala
- Graph
-
- Supertypes
- Known subtypes
-
class DefaultErrorBuilder