parsley.errors

Members list

Packages

Grouped members

formatting

This class us used to build Parsley's default error messages.

While it compiles with the ErrorBuilder typeclass, it should not be considered a stable contract: the formatting can be changed at any time and without notice. The API, however, will remain stable.

Attributes

Since: 3.0.0
Note: this class is abstract as it does not implement unexpectedToken: when creating an instance mix-in an appropriate token extractor from parsley.errors.tokenextractors.
Companion: object
Source: DefaultErrorBuilder.scala
Supertypes: trait ErrorBuilder[String]

class Object

trait Matchable

class Any

Helper functions used to build the DefaultErrorBuilder error messages.

Attributes

Since: 4.3.0
Companion: class
Source: DefaultErrorBuilder.scala
Supertypes: class Object

trait Matchable

class Any
Self type: DefaultErrorBuilder.type

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

Specialized Errors

There is only one kind of content found in a Specialized 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 Specialized error.

The overall structure of a Specialized error is given in the following diagram:

┌───────────────────────────────────────────────────────────────────────┐
│   Specialized 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
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class DefaultErrorBuilder

Contains the default instance for the ErrorBuilder typeclass, which will be automatically available without import.

Attributes

Companion: trait
Source: ErrorBuilder.scala
Supertypes: class Object

trait Matchable

class Any
Self type: ErrorBuilder.type

token

This class represents an extracted token returned by unexpectedToken in ErrorBuilder.

There is deliberately no analogue for EndOfInput because we guarantee that non-empty residual input is provided to token extraction.

Attributes

Since: 4.0.0
Companion: object
Source: Token.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class Named

class Raw

This object contains the sub-types of Token.

Attributes

Since: 4.0.0
Companion: class
Source: Token.scala
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: Token.type

combinators

This module contains combinators that can be used to directly influence error messages of parsers.

Error messages are, by default, not particularly descriptive. However, the combinators in this module can be used to improve the generation of error messages by providing labels for expected items, explanations for why things went wrong, custom error messages, custom unexpected error messages, as well as correcting the offsets that error messages actually occurred at.

Attributes

Since: 3.0.0
Source: combinator.scala
Supertypes: class Object

trait Matchable

class Any
Self type: combinator.type

This module contains combinators that help facilitate the error message generational patterns Verified Errors and Preventative Errors.

In particular, exposes an extension class VerifiedErrors that facilitates creating verified errors in many different formats.

Attributes

Since: 4.2.0
Source: patterns.scala
Supertypes: class Object

trait Matchable

class Any
Self type: patterns.type

Type members

Classlikes

This class can be used to generate hand-tuned error messages without using flatMap.

This class, and its subclasses, describe special primitives that can use the results of a previous parser to form an error message and then raise it. This is not something that is normally possible with raw combinators, without using flatMap, which is expensive.

Primarily, these are designed to be used with filterWith/verifiedWith/preventWith but can be used in other parsers as well. See the methods of the class for information.

Attributes

Since: 4.4.0
Source: ErrorGen.scala
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class SpecializedGen[A]

class VanillaGen[A]

An error generate for Specialized errors, which can tune the freeform messages of the error.

Attributes

Since: 4.4.0
Source: ErrorGen.scala
Supertypes: class ErrorGen[A]

class Object

trait Matchable

class Any

An error generator for Vanilla errors, which can tune the unexpected message and a generated reason.

Attributes

Since: 4.4.0
Companion: object
Source: ErrorGen.scala
Supertypes: class ErrorGen[A]

class Object

trait Matchable

class Any

This object contain the UnexpectedItem classes, needed to define the unexpected component of VanillaGen.

Attributes

Since: 4.4.0
Companion: class
Source: ErrorGen.scala
Supertypes: class Object

trait Matchable

class Any
Self type: VanillaGen.type

In this article

Generated with