This module defines the ErrorBuilder typeclass, which specifies how to generate an error from a parser as a specified type.

An instance of this typeclass is required when calling parse (or similar). By default, gigaparsec defines its own instance for ErrorBuilder String found in this module.

To implement ErrorBuilder, 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, use the methods found in Text.Gigaparsec.Errors.DefaultErrorBuilder.

Since: 0.2.0.0

There are two kinds of error messages that are generated by gigaparsec: 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 Text.Gigaparsec.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.

There are three kinds of content line found in a Vanilla error:

1. Unexpected info: this contains information about the kind of token that caused the error.
2. Expected info: this contains the information about what kinds of token could have avoided the error.
3. 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                                           │
└───────────────────────────────────────────────────────────────────────┘

There is only one kind of content found in a Specialised error: a message. These are completely free-form, and are generated by the failWide 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                                           │
└───────────────────────────────────────────────────────────────────────┘

These methods help assemble the final products of the error messages. The build method will return the desired err types, whereas specialisedError and vanillaError both assemble an ErrorInfoLines that the build method can consume.

• ErrorInfoLines
• build
• specialisedError
• vanillaError

These methods control the construction of the preamble of an error message, consisting of the position and source info. These are then consumed by build itself.

• Position
• Source
• pos
• source

These methods control how many lines of input surrounding the error are requested, and direct how these should be put together to form a LineInfo.

• LineInfo
• lineInfo
• numLinesAfter
• numLinesBefore

These methods control any components or structure shared by both types of messages. In particular, the representation of reasons and messages is shared, as well as how they are combined together to form a unified block of content lines.

• Message
• Messages
• combineMessages

These methods control the Specialized-specific components, namely the construction of a bespoke error message.

• message

These methods control the Vanilla-specific error components, namely how expected error items should be combined, how to represent the unexpected line, and how to represent reasons generated from explain.

• ExpectedItems
• ExpectedLine
• UnexpectedLine
• combineExpectedItems
• expected
• reason
• unexpected

These methods control how error items within Vanilla errors are constructed. These are either the end of input, a named label generated by the label combinator, or a raw piece of input intrinsically associated with a combinator. * Item * endOfInput * named * raw * unexpectedToken