combinator
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
- Graph
-
- Supertypes
- Self type
-
combinator.type
Members list
Grouped members
Failure Combinators
These combinator immediately fail the parser, with a more bespoke message.
This combinator consumes no input and fails immediately with the given error messages.
This combinator consumes no input and fails immediately with the given error messages.
Produces a specialised error message where all the lines of the error are the given msgs
in order of appearance.
Value parameters
- msg0
-
the first message in the error message.
- msgs
-
the remaining messages that will make up the error message.
Attributes
- Returns
-
a parser that fails producing an error message consisting of all the given messages.
- Since
-
3.0.0
- Example
-
val failing = fail("hello,", "this is an error message", "broken across multiple lines")
- Source
- combinator.scala
This combinator consumes no input and fails immediately with the given error messages.
This combinator consumes no input and fails immediately with the given error messages.
Produces a specialised error message where all the lines of the error are the given msgs
in order of appearance.
Value parameters
- caretWidth
-
the size of the caret for this error: should ideally match the width of the cause of the error.
- msg0
-
the first message in the error message.
- msgs
-
the remaining messages that will make up the error message.
Attributes
- Returns
-
a parser that fails producing an error message consisting of all the given messages.
- Since
-
4.0.0
- Example
-
val failing = fail("hello,", "this is an error message", "broken across multiple lines")
- Source
- combinator.scala
This combinator consumes no input and fails immediately, setting the unexpected component to the given item.
This combinator consumes no input and fails immediately, setting the unexpected component to the given item.
Produces a trivial error message where the unexpected component of the error is replaced with the given item item
.
Value parameters
- item
-
the unexpected message for the error generated.
Attributes
- Returns
-
a parser that fails producing an error with
item
as the unexpected token. - Since
-
3.0.0
- Source
- combinator.scala
This combinator consumes no input and fails immediately, setting the unexpected component to the given item.
This combinator consumes no input and fails immediately, setting the unexpected component to the given item.
Produces a trivial error message where the unexpected component of the error is replaced with the given item item
.
Value parameters
- caretWidth
-
the size of the caret for this error: should ideally match the width of the cause of the error (the unexpected item).
- item
-
the unexpected message for the error generated.
Attributes
- Returns
-
a parser that fails producing an error with
item
as the unexpected token. - Since
-
4.0.0
- Source
- combinator.scala
Error Extension Combinators
These are implicit classes that, when in scope, enable additional combinators on parsers that interact with the error system in some way.
This class exposes helpful combinators that are specialised for generating more helpful errors messages.
This class exposes helpful combinators that are specialised for generating more helpful errors messages.
This extension class operates on values that are convertible to parsers. It enables the use of error combinators, which can be used for data validation, error annotation, or immediate failing.
Type parameters
- P
-
the type of base value that this class is used on (the conversion to
Parsley
) is summoned automatically.
Value parameters
- con
-
a conversion that allows values convertible to parsers to be used.
- p
-
the value that this class is enabling methods on.
Attributes
- Constructor
-
This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
- Version
-
3.0.0
- Source
- combinator.scala
- Supertypes
This class exposes helpful combinators that are specialised for generating more helpful errors messages.
This class exposes helpful combinators that are specialised for generating more helpful errors messages.
This extension class operates on values that are convertible to parsers. It enables the use of error combinators, which can be used for data validation, error annotation, or immediate failing.
Type parameters
- P
-
the type of base value that this class is used on (the conversion to
Parsley
) is summoned automatically.
Value parameters
- con
-
a conversion that allows values convertible to parsers to be used.
- p
-
the value that this class is enabling methods on.
Attributes
- Constructor
-
This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
- Version
-
3.0.0
- Source
- combinator.scala
Error Adjustment Combinators
These combinators can affect at what position an error is caused at. They are opposites: where amend
will ensure an error message is said to have generated at the position on entry to the combinator, entrench
will resist these changes.
This combinator adjusts any error messages generated by the given parser so that they occur at the position recorded on entry to this combinator (effectively as if no input were consumed).
This combinator adjusts any error messages generated by the given parser so that they occur at the position recorded on entry to this combinator (effectively as if no input were consumed).
This is useful if validation work is done on the output of a parser that may render it invalid, but the error should point to the beginning of the structure. This combinators effect can be cancelled with entrench
.
Value parameters
- p
-
a parser whose error messages should be adjusted.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - Since
-
3.1.0
- Example
-
scala> val greeting = string("hello world") <* char('!') scala> greeting.label("greeting").parse("hello world.") val res0 = Failure((line 1, column 12): unexpected "." expected "!" >hello world. ^) scala> amend(greeting).label("greeting").parse("hello world.") val res1 = Failure((line 1, column 1): unexpected "h" expected greeting >hello world. ^)
- Source
- combinator.scala
This combinator first tries to amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it instead.
This combinator first tries to amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it instead.
Value parameters
- p
-
a parser whose error messages should be amended unless its been entrenched.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - See also
- Since
-
4.2.0
- Source
- combinator.scala
This combinator first tries to amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it by
many times instead.
This combinator first tries to amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it by
many times instead.
Value parameters
- p
-
a parser whose error messages should be amended unless its been entrenched.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - See also
- Since
-
4.4.0
- Source
- combinator.scala
This combinator undoes the action of any entrench
combinators on the given parser.
This combinator undoes the action of any entrench
combinators on the given parser.
Entrenchment is important for preventing the incorrect amendment of certain parts of sub-errors for a parser, but it may be then undesireable to block further amendments from elsewhere in the parser. This combinator can be used to cancel all entrenchment after the critical section has passed.
Value parameters
- p
-
a parser that should no longer be under the affect of an
entrench
combinator
Attributes
- Returns
-
a parser that parses
p
and allows its error messages to be amended. - Since
-
4.2.0
- Source
- combinator.scala
This combinator undoes the action of by
many entrench
combinators on the given parser.
This combinator undoes the action of by
many entrench
combinators on the given parser.
Entrenchment is important for preventing the incorrect amendment of certain parts of sub-errors for a parser, but it may be then undesireable to block further amendments from elsewhere in the parser. This combinator can be used to cancel several, but potentially not all entrenchments after the critical section has passed.
Value parameters
- by
-
the number of entrenchments to undo
- p
-
a parser that should no longer be under the affect of an
entrench
combinator
Attributes
- Returns
-
a parser that parses
p
and may allows its error messages to be amended if all entrenchments are undone - Since
-
4.4.0
- Source
- combinator.scala
This combinator prevents the action of any enclosing amend
on the errors generated by the given parser.
This combinator prevents the action of any enclosing amend
on the errors generated by the given parser.
Sometimes, the error adjustments performed by amend
should only affect errors generated within a certain part of a parser and not the whole thing; in this case, entrench
can be used to protect sub-parsers from having their errors adjusted, providing a much more fine-grained scope for error adjustment.
Value parameters
- p
-
a parser whose error messages should not be adjusted by any surrounding
amend
.
Attributes
- Returns
-
a parser that parses
p
but ensures any error messages are generated normally. - Since
-
3.1.0
- Example
-
In this example, the
ident
parser should not allow keywords, and these error messages should be generated from the start of the identifier, not the end. However any errors generated within the identifier itself should remain at their regular offsets.val ident = amend { entrench(stringOfSome(letter)).filterOut { case v if keywords.contains(v) => s"keyword $v cannot be an identifier" } }
In reality though,
filterOut
has anamend
andentrench
built into it. - Source
- combinator.scala
This combinator marks any errors within the given parser as being lexical errors.
This combinator marks any errors within the given parser as being lexical errors.
When an error is marked as a lexical error, it sets a flag within the error that is passed to ErrorBuilder.unexpectedToken
: this should be used to prevent Lexer
-based token extraction from being performed on an error, since lexing errors cannot be the result of unexpected tokens.
Value parameters
- p
-
the parser that serves as a token.
Attributes
- Returns
-
a parser that parses
p
but ensures any error messages are marked as lexical errors. - Since
-
4.0.0
- Source
- combinator.scala
This combinator adjusts any error messages generated by the given parser so that they occur at the position recorded on entry to this combinator, but retains the original offset.
This combinator adjusts any error messages generated by the given parser so that they occur at the position recorded on entry to this combinator, but retains the original offset.
Similar to amend
, but retains the original offset the error occurred at. This is known as its underlying offset as opposed to the visual presentation offset. To the reader, the error messages appears as if no input was consumed, but for the purposes of error message merging the error is still deeper. A key thing to note is that two errors can only merge if they are at the same presentation and underlying offsets: if they are not the deeper of the two dominates.
The ability for an error to still dominate others after partial amendment can be useful for allowing it to avoid being lost when merging with errors that are deeper than the presentation offset but shallower than the underlying.
Value parameters
- p
-
a parser whose error messages should be adjusted.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - Since
-
4.4.0
- Example
-
scala> val greeting = string("hello world") <* char('!') scala> val shortGreeting = string("h") <* (char('i') | string("ey")) <* char('!') // here, the shortGreeting, despite not getting as far into the input is dominating the amended long greeting scala> (amend(atomic(greeting)).label("hello world!") | shortGreeting).parse("hello world.") val res0 = Failure((line 1, column 2): unexpected "el" expected "ey" or "i" >hello world. ^^) // here it appears to start at the `h` point, but notably dominates the short greeting scala> (amend(atomic(greeting)).label("hello world!") | shortGreeting).parse("hello world.") val res1= Failure((line 1, column 1): unexpected "h" expected hello world! >hello world. ^)
- Source
- combinator.scala
This combinator first tries to partially amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it instead.
This combinator first tries to partially amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it instead.
Value parameters
- p
-
a parser whose error messages should be amended unless its been entrenched.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - See also
-
partialAmend
anddislodge
- Since
-
4.4.0
- Source
- combinator.scala
This combinator first tries to partially amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it by
many times instead.
This combinator first tries to partially amend the position of any error generated by the given parser, and if the error was entrenched will dislodge it by
many times instead.
Value parameters
- p
-
a parser whose error messages should be amended unless its been entrenched.
Attributes
- Returns
-
a parser that parses
p
but ensures any errors generated occur as if no input were consumed. - See also
-
partialAmend
anddislodge
- Since
-
4.4.0
- Source
- combinator.scala