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
- Grouped
- Alphabetic
- By Inheritance
- Parsley
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Type Members
- 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
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- 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, thenattempt(p)
has no effect. However, ifp
failed, then any input that it consumed is rolled back. This has two uses: it ensures that the parserp
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.
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
Example: - 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 eitherleft
orright
depending on its result.This combinator parses its first argument
either
, and then parses eitherleft
orright
depending on its result.First,
branch(either, left, right)
parseseither
, which, if successful, will produce either aLeft(x)
or aRight(y)
. If aLeft(x)
is produced, the parserleft
is executed to produce a functionf
, andf(x)
is returned. Otherwise, if aRight(y)
is produced, the parserright
is executed to produce a functiong
, andg(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 aLeft
.- right
a parser to execute if
either
returns aRight
.- returns
a parser that will parse one of
left
orright
depending oneither
's result.
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)) }
Example: - def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- 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.
When this combinator is ran, no input is required, nor consumed, and the current column number will always be successfully returned. It has no other effect on the state of the parser.
- returns
a parser that returns the column number the parser is currently at.
scala> import parsley.Parsley.col, parsley.character.char scala> col.parse("") val res0 = Success(1) scala> (char('a') *> col).parse("a") val res0 = Success(2) scala> (char('\n') *> col).parse("\n") val res0 = Success(1)
- Note
in the presence of wide unicode characters, the value returned may be inaccurate.
Example: - 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.
scala> import parsley.Parsley.empty scala> empty.parse("") val res0 = Failure(..)
Example: - final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- 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
.
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
Example: - final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- 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.
- 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.
When this combinator is ran, no input is required, nor consumed, and the current line number will always be successfully returned. It has no other effect on the state of the parser.
- returns
a parser that returns the line number the parser is currently at.
scala> import parsley.Parsley.line, parsley.character.char scala> line.parse("") val res0 = Success(1) scala> (char('a') *> line).parse("a") val res0 = Success(1) scala> (char('\n') *> line).parse("\n") val res0 = Success(2)
Example: - 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, thenlookAhead(p)
will roll back any input consumed whilst parsingp
. Ifp
fails, however, then the whole combinator fails and any input consumed remains consumed. If this behaviour is not desirable, consider pairinglookAhead
withattempt
.- 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.
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
Example: - final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def notFollowedBy(p: Parsley[_]): Parsley[Unit]
This combinator parses its argument
p
, and succeeds whenp
fails and vice-versa, never consuming input.This combinator parses its argument
p
, and succeeds whenp
fails and vice-versa, never consuming input.If the parser
p
succeeds, thennotFollowedBy(p)
will fail, consuming no input. Otherwise, shouldp
fail, thennotFollowedBy(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.
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) }
Example: - final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- 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.
When this combinator is ran, no input is required, nor consumed, and the current line and column number will always be successfully returned. It has no other effect on the state of the parser.
- returns
a parser that returns the line and column number the parser is currently at.
scala> import parsley.Parsley.pos, parsley.character.char scala> pos.parse("") val res0 = Success((1, 1)) scala> (char('a') *> pos).parse("a") val res0 = Success((1, 2)) scala> (char('\n') *> pos).parse("\n") val res0 = Success((2, 1))
- Note
in the presence of wide unicode characters, the column value returned may be inaccurate.
Example: - 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
.
scala> import parsley.Parsley.pure scala> pure(7).parse("") val res0 = Success(7) scala> pure("hello!").parse("a") val res1 = Success("hello!")
Example: - def select[A, B](p: Parsley[Either[A, B]], q: => Parsley[(A) => B]): Parsley[B]
This combinator parses its first argument
p
, then parsesq
only ifp
returns aLeft
.This combinator parses its first argument
p
, then parsesq
only ifp
returns aLeft
.First,
select(p, q)
parsesp
, which, if successful, will produce either aLeft(x)
or aRight(y)
. If aLeft(x)
is produced, then the parserq
is executed to produce a functionf
, andf(x)
is returned. Otherwise, if aRight(y)
is produced,y
is returned unmodified andq
is not parsed. If eitherp
orq
fails, the entire combinator fails. This is a special case ofbranch
where the right branch ispure(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 aLeft
.- returns
a parser that will parse
p
then possibly parseq
to transformp
's result into aB
.
def filter(pred: A => Boolean): Parsley[A] = { val p = this.map(x => if (pred(x)) Right(x) else Left(())) select(p, empty) }
Example: - final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- 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
()
.
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.
Example: - final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
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.
Position-Tracking Parsers
These parsers provide a way to extract position information during a parse. This can be important for when the final result of the parser needs to encode position information for later consumption: this is particularly useful for abstract syntax trees.
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.