Text.Gigaparsec.Errors.ErrorBuilder

This typeclass 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.

How an Error is Structured

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.

Vanilla Errors

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                                           │
└───────────────────────────────────────────────────────────────────────┘

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 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                                           │
└───────────────────────────────────────────────────────────────────────┘

Since: 0.2.0.0

Documentation

class Ord (Item err) => ErrorBuilder err where

This class describes how to construct an error message generated by a parser in a represention the parser writer desires.

Associated Types

type Position err

The representation type of position information within the generated message.

type Source err

The representation of the file information.

type ErrorInfoLines err

The representation type of the main body within the error message.

type ExpectedItems err

The representation of all the different possible tokens that could have prevented an error.

type Messages err

The representation of the combined reasons or failure messages from the parser.

type UnexpectedLine err

The representation of the information regarding the problematic token.

type ExpectedLine err

The representation of the information regarding the solving tokens.

type Message err

The representation of a reason or a message generated by the parser.

type LineInfo err

The representation of the line of input where the error occurred.

type Item err

The type that represents the individual items within the error. It must be orderable, as it is used within Set.

Methods

build

Arguments

:: Position err

the representation of the position of the error in the input (see the pos method).

-> Source err

the representation of the filename, if it exists (see the source method).

-> ErrorInfoLines err

the main body of the error message (see vanillaError or specialisedError methods).

-> err

the final error message

This is the top level function, which finally compiles all the built sub-parts into a finished value of type err.

pos

Arguments

:: Word

the line the error occurred at.

-> Word

the column the error occurred at.

-> Position err

a representation of the position.

Converts a position into the representation type given by Position.

source

Arguments

:: Maybe FilePath

the source name of the file, if any.

-> Source err

Converts the name of the file parsed from, if it exists, into the type given by Source.

vanillaError

Arguments

:: UnexpectedLine err

information about which token(s) caused the error (see the unexpected method).

-> ExpectedLine err

information about which token(s) would have avoided the error (see the expected method).

-> Messages err

additional information about why the error occured (see the combineMessages method).

-> LineInfo err

representation of the line of input that this error occured on (see the lineInfo method).

-> ErrorInfoLines err

Vanilla errors are those produced such that they have information about both expected and unexpected tokens. These are usually the default, and are not produced by fail (or any derivative) combinators.

specialisedError

Arguments

:: Messages err

information detailing the error (see the combineMessages method).

-> LineInfo err

representation of the line of input that this error occured on (see the lineInfo method).

-> ErrorInfoLines err

Specialised errors are triggered by fail and any combinators that are implemented in terms of fail. These errors take precedence over the vanilla errors, and contain less, more specialised, information.

combineExpectedItems

Arguments

:: Set (Item err)

the possible items that fix the error.

-> ExpectedItems err

Details how to combine the various expected items into a single representation.

combineMessages

Arguments

:: [Message err]

the messages to combine (see the message or reason methods).

-> Messages err

Details how to combine any reasons or messages generated within a single error. Reasons are used by vanilla messages and messages are used by specialised messages.

unexpected

Arguments

:: Maybe (Item err)

the Item that caused this error.

-> UnexpectedLine err

Describes how to handle the (potentially missing) information about what token(s) caused the error.

expected

Arguments

:: ExpectedItems err

the tokens that could have prevented the error (see combineExpectedItems).

-> ExpectedLine err

Describes how to handle the information about the tokens that could have avoided the error.

reason

Arguments

:: String

the reason produced by the parser.

-> Message err

Describes how to represent the reasons behind a parser fail. These reasons originate from the explain combinator.

message

Arguments

:: String

the message produced by the parser.

-> Message err

Describes how to represent the messages produced by the fail combinator (or any that are implemented using it).

lineInfo

Arguments

:: String

the full line of input that produced this error message.

-> [String]

the lines of input from just before the one that produced this message (up to numLinesBefore).

-> [String]

the lines of input from just after the one that produced this message (up to numLinesAfter).

-> Word

the line number of the error message

-> Word

the offset into the line that the error points at.

-> Word

how wide the caret in the message should be.

-> LineInfo err

Describes how to process the information about the line that the error occured on, and its surrounding context.

numLinesBefore :: Int

The number of lines of input to request before an error occured.

numLinesAfter :: Int

The number of lines of input to request after an error occured.

raw

Arguments

:: String

the raw, unprocessed input.

-> Item err

Converts a raw item generated by either the input string or a input reading combinator without a label.

named

Arguments

:: String

the name given to the label.

-> Item err

Converts a named item generated by a label.

endOfInput :: Item err

Value that represents the end of the input in the error message.

unexpectedToken

Arguments

:: NonEmpty Char

the remaining input, cs, at point of failure.

-> Word

the input the parser tried to read when it failed (this is not guaranteed to be smaller than the length of cs, but is guaranteed to be greater than 0).

-> Bool

was this error generated as part of "lexing", or in a wider parser (see markAsToken).

-> Token

a token extracted from cs that will be used as part of the unexpected message.

Extracts an unexpected token from the remaining input.

When a parser fails, by default an error reports an unexpected token of a specific width. This works well for some parsers, but often it is nice to have the illusion of a dedicated lexing pass: instead of reporting the next few characters as unexpected, an unexpected token can be reported instead. This can take many forms, for instance trimming the token to the next whitespace, only taking one character, or even trying to lex a token out of the stream.

This method can be easily implemented by using an appropriate token extractor from Text.Gigaparsec.Errors.TokenExtractors.

Instances

ErrorBuilder Void

This builder denotes that failure of a parser is impossible, as its errors are uninhabited.

Defined in Text.Gigaparsec.Errors.ErrorBuilder

Associated Types

type Position Void

type Source Void

type ErrorInfoLines Void

type ExpectedItems Void

type Messages Void

type UnexpectedLine Void

type ExpectedLine Void

type Message Void

type LineInfo Void

type Item Void

Methods

build :: Position Void -> Source Void -> ErrorInfoLines Void -> Void

pos :: Word -> Word -> Position Void

source :: Maybe FilePath -> Source Void

vanillaError :: UnexpectedLine Void -> ExpectedLine Void -> Messages Void -> LineInfo Void -> ErrorInfoLines Void

specialisedError :: Messages Void -> LineInfo Void -> ErrorInfoLines Void

combineExpectedItems :: Set (Item Void) -> ExpectedItems Void

combineMessages :: [Message Void] -> Messages Void

unexpected :: Maybe (Item Void) -> UnexpectedLine Void

expected :: ExpectedItems Void -> ExpectedLine Void

reason :: String -> Message Void

message :: String -> Message Void

lineInfo :: String -> [String] -> [String] -> Word -> Word -> Word -> LineInfo Void

numLinesBefore :: Int

numLinesAfter :: Int

raw :: String -> Item Void

named :: String -> Item Void

endOfInput :: Item Void

unexpectedToken :: NonEmpty Char -> Word -> Bool -> Token

ErrorBuilder String

Builds error messages as String, using the functions found in Text.Gigaparsec.Errors.DefaultErrorBuilder.

Defined in Text.Gigaparsec.Errors.ErrorBuilder

Associated Types

type Position String

type Source String

type ErrorInfoLines String

type ExpectedItems String

type Messages String

type UnexpectedLine String

type ExpectedLine String

type Message String

type LineInfo String

type Item String

Methods

build :: Position String -> Source String -> ErrorInfoLines String -> String

pos :: Word -> Word -> Position String

source :: Maybe FilePath -> Source String

vanillaError :: UnexpectedLine String -> ExpectedLine String -> Messages String -> LineInfo String -> ErrorInfoLines String

specialisedError :: Messages String -> LineInfo String -> ErrorInfoLines String

combineExpectedItems :: Set (Item String) -> ExpectedItems String

combineMessages :: [Message String] -> Messages String

unexpected :: Maybe (Item String) -> UnexpectedLine String

expected :: ExpectedItems String -> ExpectedLine String

reason :: String -> Message String

message :: String -> Message String

lineInfo :: String -> [String] -> [String] -> Word -> Word -> Word -> LineInfo String

numLinesBefore :: Int

numLinesAfter :: Int

raw :: String -> Item String

named :: String -> Item String

endOfInput :: Item String

unexpectedToken :: NonEmpty Char -> Word -> Bool -> Token

ErrorBuilder ()

Can be used to ignore error messages, by just returning a ().

Defined in Text.Gigaparsec.Errors.ErrorBuilder

Associated Types

type Position ()

type Source ()

type ErrorInfoLines ()

type ExpectedItems ()

type Messages ()

type UnexpectedLine ()

type ExpectedLine ()

type Message ()

type LineInfo ()

type Item ()

Methods

build :: Position () -> Source () -> ErrorInfoLines () -> ()

pos :: Word -> Word -> Position ()

source :: Maybe FilePath -> Source ()

vanillaError :: UnexpectedLine () -> ExpectedLine () -> Messages () -> LineInfo () -> ErrorInfoLines ()

specialisedError :: Messages () -> LineInfo () -> ErrorInfoLines ()

combineExpectedItems :: Set (Item ()) -> ExpectedItems ()

combineMessages :: [Message ()] -> Messages ()

unexpected :: Maybe (Item ()) -> UnexpectedLine ()

expected :: ExpectedItems () -> ExpectedLine ()

reason :: String -> Message ()

message :: String -> Message ()

lineInfo :: String -> [String] -> [String] -> Word -> Word -> Word -> LineInfo ()

numLinesBefore :: Int

numLinesAfter :: Int

raw :: String -> Item ()

named :: String -> Item ()

endOfInput :: Item ()

unexpectedToken :: NonEmpty Char -> Word -> Bool -> Token

data Token

Constructors

Raw !String

Named !String !Word