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 │
└───────────────────────────────────────────────────────────────────────┘
Attributes
- Err
The final result type of the error message
- Since:
3.0.0
- Companion:
- object
- Source:
- ErrorBuilder.scala
- Graph
- Supertypes
- Known subtypes
- class DefaultErrorBuilder