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.position contains parsers for extracting position information.
    • 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
  • package expr

    This package contains various functionality relating to the parsing of expressions..

    This package contains various functionality relating to the parsing of expressions..

    This includes the "chain" combinators, which tackle the left-recursion problem and allow for the parsing and combining of operators with values. It also includes functionality for constructing larger precedence tables, which may even vary the type of each layer in the table, allowing for strongly-typed expression parsing.

    Definition Classes
    parsley
  • package implicits

    This package contains various functionality that involve Scala's implicits mechanism.

    This package contains various functionality that involve Scala's implicits mechanism.

    This includes conversions from scala literals into parsers, as well as enabling new syntax on regular Scala values (such as Parsley's lift or zipped syntax). Automatic conversion to Parsley[Unit] is also supported within this package.

    Definition Classes
    parsley
  • package token

    This package provides a wealth of functionality for performing common lexing tasks.

    This package provides a wealth of functionality for performing common lexing tasks.

    It is organised as follows:

    • the main parsing functionality is accessed via Lexer, which provides implementations for the combinators found in the sub-packages given a LexicalDesc.
    • the descriptions sub-package is how a lexical structure can be described, providing the configuration that alters the behaviour of the parsers produced by the Lexer.
    • the other sub-packages contain the high-level interfaces that the Lexer exposes, which can be used to pass whitespace-aware and non-whitespace-aware combinators around in a uniform way.
    • the predicate module contains functionality to help define boolean predicates on characters or unicode codepoints.
    Definition Classes
    parsley
  • Failure
  • Parsley
  • Result
  • Success
  • ap
  • character
  • combinator
  • debug
  • extension
  • genericbridges
  • io
  • lift
  • position
  • registers

object Parsley

This object contains the core "function-style" combinators: all parsers will likely require something from within!

In particular, it contains combinators for: controlling how input is consumed; injecting values into the parser, or failing; extracting position information from the parser; conditional execution of parsers; and more.

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

Type Members

  1. implicit final class LazyParsley[A] extends AnyRef

    This class enables the prefix ~ combinator, which allows a parser in an otherwise strict position to be made lazy.

    This class enables the prefix ~ combinator, which allows a parser in an otherwise strict position to be made lazy.

    Since

    4.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. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def attempt[A](p: Parsley[A]): Parsley[A]

    This combinator parses its argument p, but rolls back any consumed input on failure.

    This combinator parses its argument p, but rolls back any consumed input on failure.

    If the parser p succeeds, then attempt(p) has no effect. However, if p failed, then any input that it consumed is rolled back. This has two uses: it ensures that the parser p is all-or-nothing when consuming input (atomic), and it allows for parsers that consume input to backtrack when they fail (with <|>). It should be used for the latter purpose sparingly, however, since excessive backtracking in a parser can result in much lower efficiency.

    p

    the parser to execute, if it fails, it will not have consumed input.

    returns

    a parser that tries p, but never consumes input if it fails.

    Example:

    1. scala> import parsley.character.string, parsley.Parsley.attempt
scala> (string("abc") <|> string("abd")).parse("abd")
val res0 = Failure(..) // first parser consumed a, so no backtrack
scala> (attempt(string("abc")) <|> string("abd")).parse("abd")
val res1 = Success("abd") // first parser does not consume input on failure now
  6. def branch[A, B, C](either: Parsley[Either[A, B]], left: => Parsley[(A) => C], right: => Parsley[(B) => C]): Parsley[C]

    This combinator parses its first argument either, and then parses either left or right depending on its result.

    This combinator parses its first argument either, and then parses either left or right depending on its result.

    First, branch(either, left, right) parses either, which, if successful, will produce either a Left(x) or a Right(y). If a Left(x) is produced, the parser left is executed to produce a function f, and f(x) is returned. Otherwise, if a Right(y) is produced, the parser right is executed to produce a function g, and g(y) is returned. If either of the two executed parsers fail, the entire combinator fails.

    First introduced in Selective Applicative Functors (Mokhov et al. 2019).

    either

    the first parser to execute, its result decides which parser to execute next.

    left

    a parser to execute if either returns a Left.

    right

    a parser to execute if either returns a Right.

    returns

    a parser that will parse one of left or right depending on either's result.

    Example:

    1. def ifP[A](b: Parsley[Boolean], t: =>Parsley[A], e: =>Parsley[A]): Parsley[A] = {
    val cond = b.map {
        case true => Left(())
        case false => Right(())
    }
    branch(cond, t.map[Unit => A](x => _ => x), e.map[Unit => A](x => _ => x))
}
  7. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  8. val empty: Parsley[Nothing]

    This parser fails immediately, with an unknown parse error.

    This parser fails immediately, with an unknown parse error.

    returns

    a parser that fails.

    Example:

    1. scala> import parsley.Parsley.empty
scala> empty.parse("")
val res0 = Failure(..)
  9. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  10. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  11. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  12. def fresh[A](x: => A): Parsley[A]

    This combinator produces a new value everytime it is parsed without having any other effect.

    This combinator produces a new value everytime it is parsed without having any other effect.

    When this combinator is ran, no input is required, nor consumed, and a new instance of the given value will always be successfully returned. It has no other effect on the state of the parser.

    This is useful primarily if mutable data is being threaded around a parser: this should not be needed for the vast majority of parsers.

    x

    the value to be returned.

    returns

    a parser which consumes no input and produces a value x.

    Example:

    1. scala> import parsley.Parsley.{pure, fresh}
scala> val p = pure(new Object)
scala> p.parse("")
val res0 = Success(java.lang.Object@44a3ec6b)
scala> p.parse("")
val res1 = Success(java.lang.Object@44a3ec6b)
scala> val q = fresh(new Object)
scala> q.parse("")
val res2 = Success(java.lang.Object@71623278)
scala> q.parse("")
val res3 = Success(java.lang.Object@768b970c)
    Since

    4.0.0

  13. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  14. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  15. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  16. def join[A](p: Parsley[Parsley[A]]): Parsley[A]

    This combinator collapses two layers of parsing structure into one.

    This combinator collapses two layers of parsing structure into one.

    Just an alias for _.flatten, providing a namesake to Haskell.

    See also

    flatten for details and examples.

  17. def lookAhead[A](p: Parsley[A]): Parsley[A]

    This combinator parses its argument p, but does not consume input if it succeeds.

    This combinator parses its argument p, but does not consume input if it succeeds.

    If the parser p succeeds, then lookAhead(p) will roll back any input consumed whilst parsing p. If p fails, however, then the whole combinator fails and any input consumed remains consumed. If this behaviour is not desirable, consider pairing lookAhead with attempt.

    p

    the parser to execute, if it succeeds, it will not have consumed input.

    returns

    a parser that parses p and never consumes input if it succeeds.

    Example:

    1. scala> import parsley.Parsley.lookAhead, parsley.character.string
scala> (lookAhead(string("aaa")) *> string("aaa")).parse("aaa")
val res0 = Success("aaa")
scala> (lookAhead(string("abc")) <|> string("abd")).parse("abd")
val res1 = Failure(..) // lookAhead does not roll back input consumed on failure
  18. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  19. def notFollowedBy(p: Parsley[_]): Parsley[Unit]

    This combinator parses its argument p, and succeeds when p fails and vice-versa, never consuming input.

    This combinator parses its argument p, and succeeds when p fails and vice-versa, never consuming input.

    If the parser p succeeds, then notFollowedBy(p) will fail, consuming no input. Otherwise, should p fail, then notFollowedBy(p) will succeed, consuming no input and returning ().

    p

    the parser to execute, it should fail in order for this combinator to succeed.

    returns

    a parser which fails when p succeeds and succeeds otherwise, never consuming input.

    Example:

    1. one use for this combinator is to allow for "longest-match" behaviour. For instance, keywords are normally only considered keywords if they are not part of some larger valid identifier (i.e. the keyword "if" should not parse successfully given "ifp"). This can be accomplished as follows:

      import parsley.character.{string, letterOrDigit}
import parsley.Parsley.notFollowedBy
def keyword(kw: String): Parsley[Unit] = attempt {
    string(kw) *> notFollowedBy(letterOrDigit)
}
  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  22. def pure[A](x: A): Parsley[A]

    This combinator produces a value without having any other effect.

    This combinator produces a value without having any other effect.

    When this combinator is ran, no input is required, nor consumed, and the given value will always be successfully returned. It has no other effect on the state of the parser.

    x

    the value to be returned.

    returns

    a parser which consumes no input and produces a value x.

    Example:

    1. scala> import parsley.Parsley.pure
scala> pure(7).parse("")
val res0 = Success(7)
scala> pure("hello!").parse("a")
val res1 = Success("hello!")
  23. def select[A, B](p: Parsley[Either[A, B]], q: => Parsley[(A) => B]): Parsley[B]

    This combinator parses its first argument p, then parses q only if p returns a Left.

    This combinator parses its first argument p, then parses q only if p returns a Left.

    First, select(p, q) parses p, which, if successful, will produce either a Left(x) or a Right(y). If a Left(x) is produced, then the parser q is executed to produce a function f, and f(x) is returned. Otherwise, if a Right(y) is produced, y is returned unmodified and q is not parsed. If either p or q fails, the entire combinator fails. This is a special case of branch where the right branch is pure(identity[B]).

    First introduced in Selective Applicative Functors (Mokhov et al. 2019).

    p

    the first parser to execute, its result decides whether q is executed or not.

    q

    a parser to execute when p returns a Left.

    returns

    a parser that will parse p then possibly parse q to transform p's result into a B.

    Example:

    1. def filter(pred: A => Boolean): Parsley[A] = {
    val p = this.map(x => if (pred(x)) Right(x) else Left(()))
    select(p, empty)
}
  24. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  25. def toString(): String
    Definition Classes
    AnyRef → Any
  26. val unit: Parsley[Unit]

    This combinator produces () without having any other effect.

    This combinator produces () without having any other effect.

    When this combinator is ran, no input is required, nor consumed, and the given value will always be successfully returned. It has no other effect on the state of the parser.

    returns

    a parser which consumes no input and produces ().

    Example:

    1. scala> import parsley.Parsley.unit
scala> unit.parse("")
val res0 = Success(())
scala> unit.parse("a")
val res0 = Success(())
    Note

    defined as pure(()) as a simple convenience.

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

Deprecated Value Members

  1. def col: Parsley[Int]

    This parser returns the current column number of the input without having any other effect.

    This parser returns the current column number of the input without having any other effect.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) Position parsing functionality was moved to parsley.position; use position.col instead as this will be removed in 5.0.0

    Note

    in the presence of wide unicode characters, the column value returned may be inaccurate.

  2. def line: Parsley[Int]

    This parser returns the current line number of the input without having any other effect.

    This parser returns the current line number of the input without having any other effect.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) Position parsing functionality was moved to parsley.position; use position.line instead as this will be removed in 5.0.0

  3. def pos: Parsley[(Int, Int)]

    This parser returns the current line and column numbers of the input without having any other effect.

    This parser returns the current line and column numbers of the input without having any other effect.

    Annotations
    @deprecated
    Deprecated

    (Since version 4.2.0) Position parsing functionality was moved to parsley.position; use position.pos instead as this will be removed in 5.0.0

    Note

    in the presence of wide unicode characters, the column value returned may be inaccurate.

Inherited from AnyRef

Inherited from Any

Primitive Combinators

These combinators are specific to parser combinators. In one way or another, they influence how a parser consumes input, or under what conditions a parser does or does not fail. These are really important for most practical parsing considerations, although lookAhead is much less well used.

Consumptionless Parsers

These combinators and parsers do not consume input: they are the most primitive ways of producing successes and failures with the minimal possible effect on the parse. They are, however, reasonably useful; in particular, pure and unit can be put to good use in injecting results into a parser without needing to consume anything, or mapping another parser.

Conditional Combinators

These combinators will decide which branch to take next based on the result of another parser. This differs from combinators like <|> which make decisions based on the success/failure of a parser: here the result of a successful parse will direct which option is done. These are sometimes known as "selective" combinators.

Expensive Sequencing Combinators

These combinators can sequence two parsers, where the first parser's result influences the structure of the second one. This may be because the second parser is generated from the result of the first, or that the first parser returns the second parser. Either way, the second parser cannot be known until runtime, when the first parser has been executed: this means that Parsley is forced to compile the second parser during parse-time, which is very expensive to do repeatedly. These combinators are only needed in exceptional circumstances, and should be avoided otherwise.

Ungrouped