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.extension contains syntactic sugar combinators exposed as implicit classes.
    • parsley.io contains extension methods to run parsers with input sourced from IO sources.
    • 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.implicits contains several implicits to add syntactic sugar to the combinators. These are sub-categorised into the following sub modules:
      • parsley.implicits.character contains implicits to allow you to use character and string literals as parsers.
      • parsley.implicits.combinator contains implicits related to combinators, such as the ability to make any parser into a Parsley[Unit] automatically.
      • parsley.implicits.lift enables postfix application of the lift combinator onto a function (or value).
      • parsley.implicits.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.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.registers contains combinators that interact with the context-sensitive functionality in the form of registers.
    • parsley.token contains the Lexer class that provides a host of helpful lexing combinators when provided with the description of a language.
    • parsley.genericbridges 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
  • object combinator

    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.

    Definition Classes
    errors
    Since

    3.0.0

  • ErrorMethods

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

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.

Source
combinator.scala
Version

3.0.0

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

Instance Constructors

  1. new ErrorMethods(p: P)(implicit con: (P) => Parsley[A])

    This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.

    This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.

    p

    the value that this class is enabling methods on.

    con

    a conversion that allows values convertible to parsers to be used.

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 ?(item: String): Parsley[A]

    This combinator changes the expected component of any errors generated by this parser.

    This combinator changes the expected component of any errors generated by this parser.

    This is just an alias for the label combinator.

    Known as <?> in Haskell.

    Since

    3.0.0

    See also

    label

  5. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  6. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  7. def collectMsg[B](msggen: (A) => Seq[String])(pf: PartialFunction[A, B]): Parsley[B]

    This combinator applies a partial function pf to the result of this parser if its result is defined for pf, failing if it is not.

    This combinator applies a partial function pf to the result of this parser if its result is defined for pf, failing if it is not.

    First, parse this parser. If it succeeds, test whether its result x is in the domain of the partial function pf. If it is defined for pf, return pf(x). Otherwise, if the result was undefined then fail producing a specialised error message with msggen(x). Equivalent to a guardAgainst followed by a map.

    msggen

    a function that generates the error messages to use if the filtering fails.

    pf

    the partial function used to both filter the result of this parser and transform it.

    returns

    a parser which returns the result of this parser applied to pf, if possible.

    Example:

    1. A good example of this combinator in use is for handling overflow in numeric literals.

      val integer: Parsley[BigInt] = ...
// this should be amended/entrenched for best results
val int16: Parsley[Short] =
    integer.collectMsg(n => Seq(s"integer literal $n is not within the range -2^16 to +2^16-1")) {
        case x if x >= Short.MinValue
               && x <= Short.MaxValue => x.toShort
    }
    Since

    4.0.0

    Note

    when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the parse (as if amend had been used) and the caret will span the entire successful parse of this parser.

    See also

    collect, which is a basic version of this same combinator with no customised error message.

    guardAgainst, which is similar to collectMsg, except it does not transform the data.

  8. def collectMsg[B](msg0: String, msgs: String*)(pf: PartialFunction[A, B]): Parsley[B]

    This combinator applies a partial function pf to the result of this parser if its result is defined for pf, failing if it is not.

    This combinator applies a partial function pf to the result of this parser if its result is defined for pf, failing if it is not.

    First, parse this parser. If it succeeds, test whether its result x is in the domain of the partial function pf. If it is defined for pf, return pf(x). Otherwise, if the result was undefined then fail producing a specialised error message with msg. Equivalent to a guardAgainst (whose msggen ignores its argument) followed by a map.

    msg0

    the first error message to use if the filtering fails.

    msgs

    the remaining error messages to use if the filtering fails.

    pf

    the partial function used to both filter the result of this parser and transform it.

    returns

    a parser which returns the result of this parser applied to pf, if possible.

    Example:

    1. A good example of this combinator in use is for handling overflow in numeric literals.

      val integer: Parsley[BigInt] = ...
// this should be amended/entrenched for best results
val int16: Parsley[Short] =
    integer.collectMsg("integer literal should within the range -2^16 to +2^16-1") {
        case x if x >= Short.MinValue
               && x <= Short.MaxValue => x.toShort
    }
    Since

    3.0.0

    Note

    when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the parse (as if amend had been used) and the caret will span the entire successful parse of this parser.

    See also

    collect, which is a basic version of this same combinator with no customised error message.

    guardAgainst, which is similar to collectMsg, except it does not transform the data.

  9. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  10. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  11. def explain(reason: String): Parsley[A]

    This combinator adds a reason to error messages generated by this parser.

    This combinator adds a reason to error messages generated by this parser.

    When this parser fails having not observably* consumed input, this combinator adds reason to the error message, which should justify why the error occured. Unlike error labels, which may persist if more progress is made having not consumed input, reasons are not carried forward in the error message, and are lost.

    *a parser is said to observably consume input when error messages generated by a parser p occur at a deeper offset than p originally started at. While this sounds like it is the same as "having consumed input" for the purposes of backtracking, they are disjoint concepts:

    1. in attempt(p), p can observably consume input even though the wider parser does not consume input due to the attempt.
    2. in amend(p), p can consume input and may not backtrack even though the consumption is not observable in the error message due to the amend.
    reason

    the reason why a parser failed.

    returns

    a parser that produces the given reason for failure if it fails.

    Since

    3.0.0

  12. def filterOut(pred: PartialFunction[A, String]): Parsley[A]

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    First, parse this parser. If it succeeds then take its result x and test if pred.isDefinedAt(x) is true. If it is false, the parser succeeds, returning x. Otherwise, pred(x) will yield a reason reason and the parser will fail with reason provided to the generated error message à la explain.

    This is useful for performing data validation, but where a definitive reason can be given for the failure. In this instance, the rest of the error message is generated as normal, with the expected and unexpected components still given, along with any other generated reasons.

    pred

    the predicate that is tested against the parser result, which also generates errors.

    returns

    a parser that returns the result of this parser if it fails the predicate.

    Example:

    1. scala> import parsley.character.letter
scala> val keywords = Set("if", "then", "else")
scala> val ident = stringOfSome(letter).filterOut {
    case v if keywords.contains(v) => s"keyword $v cannot be an identifier"
}
scala> ident.parse("hello")
val res0 = Success("hello")
scala> ident.parse("if")
val res1 = Failure(..)
    Since

    3.0.0

    Note

    when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the parse (as if amend had been used) and the caret will span the entire successful parse of this parser.

    See also

    filterNot, which is a basic version of this same combinator with no customised reason.

    guardAgainst, which is similar to filterOut, except it generates a specialised error as opposed to just a reason.

  13. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  14. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  15. def guardAgainst(pred: PartialFunction[A, Seq[String]]): Parsley[A]

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    First, parse this parser. If it succeeds then take its result x and test of pred.isDefinedAt(x) is true. If it is false, the parser succeeds, returning x. Otherwise pred(x) will yield an error message msg and the parser will fail, producing a specialised error only consisting of the message msg à la fail.

    This is useful for performing data validation, but where failure is not tied to the grammar but some other property of the results. For instance, with the identifier example given for filterOut, it is reasonable to suggest that an identifier was expected, and a keyword is not a valid identifier: i.e. these components still make sense. Where guardAgainst shines, however, is in scenarios where the expected alternatives, or the unexpected component itself distract from the cause of the error, or are irrelevant in some way. This might be because guardAgainst is checking some property of the data that is possible to encode in the grammar, but otherwise impractical, either because it is hard to maintain or generates poor error messages for the user.

    pred

    the predicate that is tested against the parser result, which also generates errors.

    returns

    a parser that returns the result of this parser if it fails the predicate.

    Example:

    1. Suppose we are parsing a data-format for graphs, and a restriction has been placed that ensures that the numeric identifiers of each declared node must be ordered. This has, for whatever reason, been specified as a syntactic property of the data. This is possible to encode using context-sensitive parsing (since each new node can only be parsed according to the previous one), but is fairly difficult and impractical. Instead, when all the declarations have been read, a guardAgainst can be used to prevent mis-ordering:

      val node = integer
val nodes = many(node).guardAgainst {
    case ns if ns.nonEmpty
            && ns.zip(ns.tail).exists { case (x, y) => x == y } =>
        val Some((x, _)) = ns.zip(ns.tail).find { case (x, y) => x == y }
        Seq(s"node $x has been declared twice")
    case ns if ns.nonEmpty
            && ns.zip(ns.tail).exists { case (x, y) => x > y } =>
        val Some((x, y)) = ns.zip(ns.tail).find { case (x, y) => x > y }
        Seq(s"nodes $x and $y are declared in the wrong order", "all nodes should be ordered")
}
    Since

    4.0.0

    Note

    when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the parse (as if amend had been used) and the caret will span the entire successful parse of this parser.

    See also

    filterNot, which is a basic version of this same combinator with no customised error message.

    filterOut, which is similar to guardAgainst, except it generates a reason for failure and not a specialised error.

    collectMsg, which is similar to guardAgainst, but can also transform the data on success.

  16. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. def hide: Parsley[A]

    This combinator hides the expected component of errors generated by this parser.

    This combinator hides the expected component of errors generated by this parser.

    When this parser fails having not observably* consumed input, this combinator hides any error labels assigned to the expected item by any label combinators, or indeed the base raw labels produced by the input consuming combinators themselves.

    This can be useful, say, for hiding whitespace labels, which are not normally useful information to include in an error message for whitespace insensitive grammars.

    *a parser is said to observably consume input when error messages generated by a parser p occur at a deeper offset than p originally started at. While this sounds like it is the same as "having consumed input" for the purposes of backtracking, they are disjoint concepts:

    1. in attempt(p), p can observably consume input even though the wider parser does not consume input due to the attempt.
    2. in amend(p), p can consume input and may not backtrack even though the consumption is not observable in the error message due to the amend.
    returns

    a parser that does not produce an expected component on failure.

    Since

    3.0.0

    See also

    label

  18. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  19. def label(item: String): Parsley[A]

    This combinator changes the expected component of any errors generated by this parser.

    This combinator changes the expected component of any errors generated by this parser.

    When this parser fails having not observably* consumed input, the expected component of the generated error message is set to be the given item.

    *a parser is said to observably consume input when error messages generated by a parser p occur at a deeper offset than p originally started at. While this sounds like it is the same as "having consumed input" for the purposes of backtracking, they are disjoint concepts:

    1. in attempt(p), p can observably consume input even though the wider parser does not consume input due to the attempt.
    2. in amend(p), p can consume input and may not backtrack even though the consumption is not observable in the error message due to the amend.
    item

    the name to give to the expected component of any qualifying errors.

    returns

    a parser that expects item on failure.

    Since

    3.0.0

  20. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  21. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  22. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  23. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  24. def toString(): String
    Definition Classes
    AnyRef → Any
  25. def unexpectedWhen(pred: PartialFunction[A, String]): Parsley[A]

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    This combinator filters the result of this parser using the given partial-predicate, succeeding only when the predicate is undefined.

    First, parse this parser. If it succeeds then take its result x and test if pred.isDefinedAt(x) is true. If it is false, the parser succeeds, returning x. Otherwise, pred(x) will yield a unexpected label and the parser will fail using unexpected and that label.

    This is useful for performing data validation, but where a the failure results in the entire token being unexpected. In this instance, the rest of the error message is generated as normal, with the expected components still given, along with any generated reasons.

    pred

    the predicate that is tested against the parser result, which also generates errors.

    returns

    a parser that returns the result of this parser if it fails the predicate.

    Example:

    1. scala> import parsley.character.letter
scala> val keywords = Set("if", "then", "else")
scala> val ident = stringOfSome(letter).unexpectedWhen {
    case v if keywords.contains(v) => s"keyword $v"
}
scala> ident.parse("hello")
val res0 = Success("hello")
scala> ident.parse("if")
val res1 = Failure(..)
    Since

    3.0.0

    Note

    when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the parse (as if amend had been used) and the caret will span the entire successful parse of this parser.

    See also

    filterNot, which is a basic version of this same combinator with no unexpected message.

    filterOut, which is a variant that produces a reason for failure as opposed to an unexpected message.

    guardAgainst, which is similar to unexpectedWhen, except it generates a specialised error as opposed to just a reason.

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

Deprecated Value Members

  1. def !(msggen: (A) => String): Parsley[Nothing]

    This combinator parses this parser and then fails, using the result of this parser to customise the error message.

    This combinator parses this parser and then fails, using the result of this parser to customise the error message.

    Similar to fail, but first parses this parser: if it succeeded, then its result x is used to form the error message for the fail combinator by calling msggen(x). If this parser fails, however, its error message will be generated instead.

    msggen

    the generator function for error message, creating a message based on the result of this parser.

    returns

    a parser that always fails, with the given generator used to produce the error message if this parser succeeded.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) This combinator will be removed in 5.0.0, without direct replacement

    Note

    this combinator will generate error messages rooted at the start of the previously successful parse of this parser, but only in terms of their position: the actual error is generated at the end of the parse, which means it takes priority over sibling errors. This is because the error concerns the whole parse (for caret) and morally starts where this parser started (as it caused the failure), however, if it had full amend-like behaviour these errors would often disappear.

  2. def unexpected(msggen: (A) => String): Parsley[Nothing]

    This combinator parses this parser and then fails, using the result of this parser to customise the unexpected component of the error message.

    This combinator parses this parser and then fails, using the result of this parser to customise the unexpected component of the error message.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) This combinator will be binary removed in 5.0.0 and source removed in 4.3.0, use unexpectedLegacy until 5.0.0

    See also

    unexpectedLegacy

  3. def unexpectedLegacy(msggen: (A) => String): Parsley[Nothing]

    This combinator parses this parser and then fails, using the result of this parser to customise the unexpected component of the error message.

    This combinator parses this parser and then fails, using the result of this parser to customise the unexpected component of the error message.

    Similar to unexpected, but first parses this parser: if it succeeded, then its result x is used to form the unexpected component of the generated error by calling msggen(x). If this parser fails, however, its error message will be returned untouched.

    msggen

    the generator function for error message, creating a message based on the result of this parser.

    returns

    a parser that always fails, with the given generator used to produce an unexpected message if this parser succeeded.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) This combinator will be removed in 5.0.0

    Since

    4.2.0

    Note

    this combinator will generate error messages rooted at the start of the previously successful parse of this parser, but only in terms of their position: the actual error is generated at the end of the parse, which means it takes priority over sibling errors. This is because the error concerns the whole parse (for caret) and morally starts where this parser started (as it caused the failure), however, if it had full amend-like behaviour these errors would often disappear.

Inherited from AnyRef

Inherited from Any

Error Enrichment Combinators

These combinators add additional information - or refine the existing information within - to an error message that has been generated within the scope of the parser they have been called on. These are a very basic, but effective, way of improving the quality of error messages generated by Parsley.

Filtering Combinators

These combinators perform filtering on a parser, with particular emphasis on generating meaningful error messages if the filtering fails. This is particularly useful for data validation within the parser, as very instructive error messages describing what went wrong can be generated. These combinators often filter using a PartialFunction: this may be because they combine filtering with mapping (in which case, the error message is provided separately), or the function may produce a String. In these cases, the partial function is producing the error messages: if the input to the function is defined, this means that it is invalid and the filtering will fail using the message obtained from the succesful partial function invocation.

Failure Combinators

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

Ungrouped