parsley.errors
Members list
Packages
Grouped members
formatting
This class us used to build Parsley's default error messages.
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 fromparsley.errors.tokenextractors. - Companion
- object
- Source
- DefaultErrorBuilder.scala
- Supertypes
Helper functions used to build the DefaultErrorBuilder error messages.
Helper functions used to build the DefaultErrorBuilder error messages.
Attributes
- Since
-
4.3.0
- Companion
- class
- Source
- DefaultErrorBuilder.scala
- Supertypes
- Self type
-
DefaultErrorBuilder.type
This typeclass specifies how to format an error from a parser as a specified 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: 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
- Supertypes
- Known subtypes
-
class DefaultErrorBuilder
Contains the default instance for the ErrorBuilder typeclass, which will be automatically available without import.
Contains the default instance for the ErrorBuilder typeclass, which will be automatically available without import.
Attributes
- Companion
- trait
- Source
- ErrorBuilder.scala
- Supertypes
- Self type
-
ErrorBuilder.type
token
This class represents an extracted token returned by unexpectedToken in ErrorBuilder.
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
- Known subtypes
This object contains the sub-types of Token.
This object contains the sub-types of Token.
Attributes
- Since
-
4.0.0
- Companion
- class
- Source
- Token.scala
- Supertypes
- Self type
-
Token.type
This class and its subtypes are used to describe how big a token should be (and therefore the size of the corresponding error caret).
This class and its subtypes are used to describe how big a token should be (and therefore the size of the corresponding error caret). This is provided to Token.Named and is therefore used in the creation of Tokens for lexical extractors.
Attributes
- Since
-
4.0.0
- Companion
- object
- Source
- TokenSpan.scala
- Supertypes
- Known subtypes
This object contains the sub-types of TokenSpan.
This object contains the sub-types of TokenSpan.
Attributes
- Since
-
4.0.0
- Companion
- class
- Source
- TokenSpan.scala
- Supertypes
- Self type
-
TokenSpan.type
combinators
This module contains combinators that can be used to directly influence error messages of parsers.
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
- Self type
-
combinator.type
This module contains combinators that help facilitate the error message generational patterns Verified Errors and Preventative Errors.
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
- Self type
-
patterns.type