Packages

  • package root

    This is the documentation for Parsley.

    This is the documentation for Parsley.

    Package structure

    The parsley package contains the Parsley class, as well as the Result, Success, and Failure types. In addition to these, it also contains the following packages and "modules" (a module is defined as being an object which mocks a package):

    • parsley.Parsley contains the bulk of the core "function-style" combinators.
    • parsley.combinator contains many helpful combinators that simplify some common parser patterns.
    • parsley.character contains the combinators needed to read characters and strings, as well as combinators to match specific sub-sets of characters.
    • parsley.debug contains debugging combinators, helpful for identifying faults in parsers.
    • parsley.expr contains the following sub modules:
      • parsley.expr.chain contains combinators used in expression parsing
      • parsley.expr.precedence is a builder for expression parsers built on a precedence table.
      • parsley.expr.infix contains combinators used in expression parsing, but with more permissive types than their equivalents in chain.
      • parsley.expr.mixed contains combinators that can be used for expression parsing, but where different fixities may be mixed on the same level: this is rare in practice.
    • parsley.syntax contains several implicits to add syntactic sugar to the combinators. These are sub-categorised into the following sub modules:
      • parsley.syntax.character contains implicits to allow you to use character and string literals as parsers.
      • parsley.syntax.lift enables postfix application of the lift combinator onto a function (or value).
      • parsley.syntax.zipped enables boths a reversed form of lift where the function appears on the right and is applied on a tuple (useful when type inference has failed) as well as a .zipped method for building tuples out of several combinators.
      • parsley.syntax.extension contains syntactic sugar combinators exposed as implicit classes.
    • parsley.errors contains modules to deal with error messages, their refinement and generation.
    • parsley.lift contains functions which lift functions that work on regular types to those which now combine the results of parsers returning those same types. these are ubiquitous.
    • parsley.ap contains functions which allow for the application of a parser returning a function to several parsers returning each of the argument types.
    • parsley.state contains combinators that interact with the context-sensitive functionality in the form of state.
    • parsley.token contains the Lexer class that provides a host of helpful lexing combinators when provided with the description of a language.
    • parsley.position contains parsers for extracting position information.
    • parsley.generic contains some basic implementations of the Parser Bridge pattern (see Design Patterns for Parser Combinators in Scala, or the parsley wiki): these can be used before more specialised generic bridge traits can be constructed.
    Definition Classes
    root
  • package parsley
    Definition Classes
    root
  • package errors

    This package contains various functionality relating to the generation and formatting of error messages.

    This package contains various functionality relating to the generation and formatting of error messages.

    In particular, it includes a collection of combinators for improving error messages within the parser, including labelling and providing additional information. It also contains combinators that can be used to valid data produced by a parser, to ensure it conforms to expected invariances, producing good quality error messages if this is not the case. Finally, this package contains ways of changing the formatting of error messages: this can either be changing how the default String-based errors are formatted, or by injectiing Parsley's errors into a custom error object.

    Definition Classes
    parsley
  • package tokenextractors

    This package contains implementations of token extractors that can be mixed into ErrorBuilder to decide how to extract unexpected tokens from the residual input left over from a parse error.

    This package contains implementations of token extractors that can be mixed into ErrorBuilder to decide how to extract unexpected tokens from the residual input left over from a parse error.

    These are common strategies, and something here is likely to be what is needed. They are all careful to handle unprintable characters and whitespace in a sensible way, and account for unicode codepoints that are wider than a single 16-bit character.

    Definition Classes
    errors
    Since

    4.0.0

  • DefaultErrorBuilder
  • ErrorBuilder
  • ErrorGen
  • SpecializedGen
  • Token
  • VanillaGen
  • combinator
  • patterns
o

parsley.errors

combinator

object 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.

Source
combinator.scala
Since

3.0.0

Linear Supertypes
AnyRef, Any
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. combinator
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Type Members

  1. implicit final class ErrorMethods[P, +A] extends AnyRef

    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.

    P

    the type of base value that this class is used on (the conversion to Parsley) is summoned automatically.

    Version

    3.0.0

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def amend[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be adjusted.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Example:

    1. 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.
   ^)
    Since

    3.1.0

  5. def amendThenDislodge[A](by: Int)(p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be amended unless its been entrenched.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Since

    4.4.0

    See also

    amend and dislodge

  6. def amendThenDislodge[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be amended unless its been entrenched.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Since

    4.2.0

    See also

    amend and dislodge

  7. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  8. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  9. def dislodge[A](by: Int)(p: Parsley[A]): Parsley[A]

    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.

    by

    the number of entrenchments to undo

    p

    a parser that should no longer be under the affect of an entrench combinator

    returns

    a parser that parses p and may allows its error messages to be amended if all entrenchments are undone

    Since

    4.4.0

  10. def dislodge[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser that should no longer be under the affect of an entrench combinator

    returns

    a parser that parses p and allows its error messages to be amended.

    Since

    4.2.0

  11. def entrench[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should not be adjusted by any surrounding amend.

    returns

    a parser that parses p but ensures any error messages are generated normally.

    Example:

    1. 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 an amend and entrench built into it.

    Since

    3.1.0

  12. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  14. def fail(caretWidth: Int, msg0: String, msgs: String*): Parsley[Nothing]

    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.

    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.

    returns

    a parser that fails producing an error message consisting of all the given messages.

    Example:

    1. val failing = fail("hello,", "this is an error message", "broken across multiple lines")
    Since

    4.0.0

  15. def fail(msg0: String, msgs: String*): Parsley[Nothing]

    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.

    msg0

    the first message in the error message.

    msgs

    the remaining messages that will make up the error message.

    returns

    a parser that fails producing an error message consisting of all the given messages.

    Example:

    1. val failing = fail("hello,", "this is an error message", "broken across multiple lines")
    Since

    3.0.0

  16. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  17. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  18. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  19. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  20. def markAsToken[A](p: Parsley[A]): Parsley[A]

    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.

    p

    the parser that serves as a token.

    returns

    a parser that parses p but ensures any error messages are marked as lexical errors.

    Since

    4.0.0

  21. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  22. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  23. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  24. def partialAmend[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be adjusted.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Example:

    1. 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.
   ^)
    Since

    4.4.0

  25. def partialAmendThenDislodge[A](by: Int)(p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be amended unless its been entrenched.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Since

    4.4.0

    See also

    partialAmend and dislodge

  26. def partialAmendThenDislodge[A](p: Parsley[A]): Parsley[A]

    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.

    p

    a parser whose error messages should be amended unless its been entrenched.

    returns

    a parser that parses p but ensures any errors generated occur as if no input were consumed.

    Since

    4.4.0

    See also

    partialAmend and dislodge

  27. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  28. def toString(): String
    Definition Classes
    AnyRef → Any
  29. def unexpected(caretWidth: Int, item: String): Parsley[Nothing]

    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.

    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.

    returns

    a parser that fails producing an error with item as the unexpected token.

    Since

    4.0.0

  30. def unexpected(item: String): Parsley[Nothing]

    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.

    item

    the unexpected message for the error generated.

    returns

    a parser that fails producing an error with item as the unexpected token.

    Since

    3.0.0

  31. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  32. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  33. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()

Inherited from AnyRef

Inherited from Any

Failure Combinators

These combinator immediately fail the parser, with a more bespoke message.

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.

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.

Ungrouped