Parsley

parsley.Parsley$

See theParsley companion class

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.

Attributes

Companion:: class
Source:: Parsley.scala
Graph
Supertypes: class Object
trait Matchable
class Any
Self type: Parsley.type

Members list

Concise view

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.

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.

Attributes

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:

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

Source:

Parsley.scala

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.

Attributes

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:

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

Source:

Parsley.scala

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

Attributes

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:

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)
}

Source:

Parsley.scala

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.

This parser fails immediately, with an unknown parse error.

Attributes

Returns:

a parser that fails.

Example:

scala> import parsley.Parsley.empty
scala> empty.parse("")
val res0 = Failure(..)

Source:

Parsley.scala

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.

Attributes

x

the value to be returned.

Returns:

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

Since:

4.0.0

Example:

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)

Source:

Parsley.scala

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.

Attributes

x

the value to be returned.

Returns:

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

Example:

scala> import parsley.Parsley.pure
scala> pure(7).parse("")
val res0 = Success(7)
scala> pure("hello!").parse("a")
val res1 = Success("hello!")

Source:

Parsley.scala

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.

Attributes

x

the value to be returned.

Returns:

a parser which consumes no input and produces ().

Note:

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

Example:

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

Source:

Parsley.scala

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.

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

Attributes

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:

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))
}

Source:

Parsley.scala

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

Attributes

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:

def filter(pred: A => Boolean): Parsley[A] = {
   val p = this.map(x => if (pred(x)) Right(x) else Left(()))
   select(p, empty)
}

Source:

Parsley.scala

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.

This combinator collapses two layers of parsing structure into one.

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

Attributes

See also:: flatten for details and examples.
Source:: Parsley.scala

Type members

Classlikes

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

Attributes

p: the parser that ~ is enabled on.
Constructor:: This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
Since:: 4.0.0
Source:: Parsley.scala
Graph
Supertypes: class Object
trait Matchable
class Any

Value members

Deprecated methods

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

Attributes

Note:: in the presence of wide unicode characters, the column value returned may be inaccurate.
Deprecated: Moved to position.col, due for removal in 5.0.0
Source:: Parsley.scala

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

Attributes

Deprecated: Moved to position.line, due for removal in 5.0.0
Source:: Parsley.scala

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

Attributes

Note:: in the presence of wide unicode characters, the column value returned may be inaccurate.
Deprecated: Moved to position.pos, due for removal in 5.0.0
Source:: Parsley.scala

Implicits

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

Attributes

p: the parser that ~ is enabled on.
Constructor:: This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
Since:: 4.0.0
Source:: Parsley.scala

Generated with