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 PlatformSpecific

class Object

trait Matchable

class Any
Self type: Parsley.type

Members list

Grouped members

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

Value parameters

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

Attributes

Returns

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

Since

4.4.0

Example

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

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

Value parameters

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

Attributes

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

Value parameters

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

Attributes

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] = atomic {
   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 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.

Value parameters

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

Attributes

Returns: a parser that fails.
Since: 4.4.0
Source: Parsley.scala

This parser fails immediately, with an unknown parse error.

Attributes

Returns

a parser that fails.

Note

equivalent to empty(0)

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.

Value parameters

x: the value to be returned.

Attributes

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.

Value parameters

x: the value to be returned.

Attributes

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

Value parameters

x: the value to be returned.

Attributes

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

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.

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.

Value parameters

p: the parser to execute multiple times.

Attributes

Returns

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

Since

4.5.0

Example

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

Source

Parsley.scala

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.

Value parameters

p: the parser to execute multiple times.

Attributes

Returns

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

Since

4.5.0

Example

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

Source

Parsley.scala

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.

This parser only succeeds at the end of the input.

Equivalent to notFollowedBy(item).

Attributes

Since

4.5.0

Example

scala> import parsley.combinator.eof
scala> eof.parse("a")
val res0 = Failure(..)
scala> eof.parse("")
val res1 = 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).

Value parameters

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.

Attributes

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

Value parameters

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.

Attributes

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

Type members

Classlikes

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

Value parameters

p: the parser that ~ is enabled on.

Attributes

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
Supertypes: class Object

trait Matchable

class Any

Inherited classlikes

This class exposes a method of running parsers from a file.

This extension class operates on values that are convertible to parsers. It enables the use of an alternative parseFile method, which can be used to run a parser on the contents of a file.

Value parameters

p: the value that this class is enabling methods on.

Attributes

Constructor: This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
Version: 4.5.0
Inherited from:: PlatformSpecific
Source: PlatformSpecific.scala
Supertypes: class Object

trait Matchable

class Any

Implicits

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

Value parameters

p: the parser that ~ is enabled on.

Attributes

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

Inherited implicits

This class exposes a method of running parsers from a file.

This extension class operates on values that are convertible to parsers. It enables the use of an alternative parseFile method, which can be used to run a parser on the contents of a file.

Value parameters

p: the value that this class is enabling methods on.

Attributes

Constructor: This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
Version: 4.5.0
Inherited from:: PlatformSpecific
Source: PlatformSpecific.scala

In this article

Generated with