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 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 syntax

    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
  • PlatformSpecific
  • Result
  • Success
  • ap
  • character
  • combinator
  • debug
  • generic
  • lift
  • position
  • state
  • unicode

object Parsley extends PlatformSpecific

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
PlatformSpecific, AnyRef, Any
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. Parsley
  2. PlatformSpecific
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

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 atomic[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 atomic(p) has no effect. However, if p failed, then any input that it consumed is rolled back. This ensures that the parser p is all-or-nothing when consuming input. While there are many legimate uses for all-or-nothing behaviour, one notable, if discouraged, use is to allow the <|> combinator to backtrack -- recall it can only parse its alternative if the first failed without consuming input. This is discouraged, however, as it can affect the complexity of the parser and harm error messages.

    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.atomic
scala> (string("abc") <|> string("abd")).parse("abd")
val res0 = Failure(..) // first parser consumed a, so no backtrack
scala> (atomic(string("abc")) <|> string("abd")).parse("abd")
val res1 = Success("abd") // first parser does not consume input on failure now
    Since

    4.4.0

  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( ... ) @native()
  8. def empty(caretWidth: Int): Parsley[Nothing]

    This combinator fails immediately, with a caret of the given width and no other information.

    This combinator fails immediately, with a caret of the given width and no other information.

    By producing basically no information, this combinator is principally for adjusting the caret-width of another error, rather than the value empty, which is used to fail with no effect on error content.

    caretWidth

    the width of the caret for the error produced by this combinator.

    returns

    a parser that fails.

    Since

    4.4.0

  9. 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(..)
    Note

    equivalent to empty(0)

  10. val eof: Parsley[Unit]

    This parser only succeeds at the end of the input.

    This parser only succeeds at the end of the input.

    Equivalent to notFollowedBy(item).

    Example: 

    1. scala> import parsley.combinator.eof
scala> eof.parse("a")
val res0 = Failure(..)
scala> eof.parse("")
val res1 = Success(())
    Since

    4.5.0

  11. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  12. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  13. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  14. 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

  15. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  16. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  18. 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 atomic.

    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
  19. def many[A](p: Parsley[A]): Parsley[List[A]]

    This combinator repeatedly parses a given parser zero or more times, collecting the results into a list.

    This combinator repeatedly parses a given parser zero or more times, collecting the results into a list.

    Parses a given parser, p, repeatedly until it fails. If p failed having consumed input, this combinator fails. Otherwise when p fails without consuming input, this combinator will return all of the results, x1 through xn (with n >= 0), in a list: List(x1, .., xn). If p was never successful, the empty list is returned.

    p

    the parser to execute multiple times.

    returns

    a parser that parses p until it fails, returning the list of all the successful results.

    Example: 

    1. scala> import parsley.character.string
scala> import parsley.Parsley.many
scala> val p = many(string("ab"))
scala> p.parse("")
val res0 = Success(Nil)
scala> p.parse("ab")
val res1 = Success(List("ab"))
scala> p.parse("abababab")
val res2 = Success(List("ab", "ab", "ab", "ab"))
scala> p.parse("aba")
val res3 = Failure(..)
    Since

    4.5.0

  20. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  21. 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] = atomic {
    string(kw) *> notFollowedBy(letterOrDigit)
}
  22. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  23. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  24. 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!")
  25. 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)
}
  26. def some[A](p: Parsley[A]): Parsley[List[A]]

    This combinator repeatedly parses a given parser one or more times, collecting the results into a list.

    This combinator repeatedly parses a given parser one or more times, collecting the results into a list.

    Parses a given parser, p, repeatedly until it fails. If p failed having consumed input, this combinator fails. Otherwise when p fails without consuming input, this combinator will return all of the results, x1 through xn (with n >= 1), in a list: List(x1, .., xn). If p was not successful at least one time, this combinator fails.

    p

    the parser to execute multiple times.

    returns

    a parser that parses p until it fails, returning the list of all the successful results.

    Example: 

    1. scala> import parsley.character.string
scala> import parsley.Parsley.some
scala> val p = some(string("ab"))
scala> p.parse("")
val res0 = Failure(..)
scala> p.parse("ab")
val res1 = Success(List("ab"))
scala> p.parse("abababab")
val res2 = Success(List("ab", "ab", "ab", "ab"))
scala> p.parse("aba")
val res3 = Failure(..)
    Since

    4.5.0

  27. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  28. def toString(): String
    Definition Classes
    AnyRef → Any
  29. val unit: Parsley[Unit]

    This parser produces () without having any other effect.

    This parser produces () without having any other effect.

    When this parser 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.

  30. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  31. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  32. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... ) @native()

Inherited from PlatformSpecific

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.

Iterative Combinators

These combinators all execute a given parser an unbounded number of times, until either it fails, or another parser succeeds, depending on the combinator. All of the results produced by the repeated execution of the parser are returned in a List. These are almost essential for any practical parsing task.

Input Query Combinators

These combinators do not consume input, but they allow for querying of the input stream - specifically checking whether or not there is more input that can be consumed or not. In particular, most parsers should be making use of eof to ensure that the parser consumes all the input available at the end of the parse.

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.

Ungrouped