object combinator
This module contains a huge number of pre-made combinators that are very useful for a variety of purposes.
In particular, it contains combinators for: performing a parser iteratively, collecting all the results; querying whether or not any input is left; optionally performing parsers; parsing delimited constructions; handling multiple possible alternatives or parsers to sequence; handling more complex conditional execution; and more.
- Source
- combinator.scala
- Since
2.2.0
- Grouped
- Alphabetic
- By Inheritance
- combinator
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
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 choice[A](ps: Parsley[A]*): Parsley[A]
This combinator tries to parse each of the parsers
ps
in order, until one of them succeeds.This combinator tries to parse each of the parsers
ps
in order, until one of them succeeds.Finds the first parser in
ps
which succeeds, returning its result. If none of the parsers succeed, then this combinator fails. If a parser fails having consumed input, this combinator fails immediately.- ps
the parsers to try, in order.
- returns
a parser that tries to parse one of
ps
.
scala> import parsley.combinator.choice scala> import parsley.character.string scala> val p = choice(string("abc"), string("ab"), string("bc"), string("d")) scala> p.parse("abc") val res0 = Success("abc") scala> p.parse("ab") val res1 = Failure(..) scala> p.parse("bc") val res2 = Success("bc") scala> p.parse("x") val res3 = Failure(..)
- See also
Example: - def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- def count(min: Int, max: Int)(p: Parsley[_]): Parsley[Int]
This combinator parses between
min
andmax
occurrences ofp
, returning the number of successes.This combinator parses between
min
andmax
occurrences ofp
, returning the number of successes.Parses
p
repeatedly a minimum ofmin
times and up tomax
times both inclusive. Ifp
fails beforemin
is reached, then this combinator fails. It is not required forp
to fail after themax
th parse. The results are discarded and the number of successful parses ofp
,n
, is returned instead, such thatmin <= n <= max
.- min
the minimum number of times to repeat
p
, inclusive.- max
the maximum number of times to repeat
p
, inclusive.- p
the parser to repeat.
- returns
the number of times
p
parsed successfully.
scala> import parsley.character.item scala> import parsley.combinator.count scala> val p = count(min=3, max=5)(item) scala> p.parse("ab") val res0 = Failure(..) scala> p.parse("abc") val res1 = Success(3) scala> p.parse("abcd") val res2 = Success(4) scala> p.parse("abcde") val res2 = Success(5) scala> p.parse("abcdef") val res2 = Success(5)
- Since
4.4.0
Example: - def countMany(p: Parsley[_]): Parsley[Int]
This combinator repeatedly parses a given parser zero or more times, returning how many times it succeeded.
This combinator repeatedly parses a given parser zero or more times, returning how many times it succeeded.
Parses a given parser,
p
, repeatedly until it fails. Ifp
failed having consumed input, this combinator fails. Otherwise whenp
fails without consuming input, this combinator will succeed. The number of timesp
succeeded is returned as the result.- p
the parser to execute multiple times.
- returns
the number of times
p
successfully parses
scala> import parsley.character.string scala> import parsley.combinator.countMany scala> val p = countMany(string("ab")) scala> p.parse("") val res0 = Success(0) scala> p.parse("ab") val res1 = Success(1) scala> p.parse("abababab") val res2 = Success(4) scala> p.parse("aba") val res3 = Failure(..)
- Since
4.5.0
Example: - def countSome(p: Parsley[_]): Parsley[Int]
This combinator repeatedly parses a given parser one or more times, returning how many times it succeeded.
This combinator repeatedly parses a given parser one or more times, returning how many times it succeeded.
Parses a given parser,
p
, repeatedly until it fails. Ifp
failed having consumed input, this combinator fails. Otherwise whenp
fails without consuming input, this combinator will succeed. The parserp
must succeed at least once. The number of timesp
succeeded is returned as the result.- p
the parser to execute multiple times.
- returns
the number of times
p
successfully parses
scala> import parsley.character.string scala> import parsley.combinator.countSome scala> val p = countSome(string("ab")) scala> p.parse("") val res0 = Failure(..) scala> p.parse("ab") val res1 = Success(1) scala> p.parse("abababab") val res2 = Success(4) scala> p.parse("aba") val res3 = Failure(..)
- Since
4.5.0
Example: - def decide[A](p: Parsley[Option[A]], q: => Parsley[A]): Parsley[A]
This combinator parses
q
depending only ifp
returns aNone
.This combinator parses
q
depending only ifp
returns aNone
.First parses
p
. Ifp
returnedSome(x)
, thenx
is returned. Otherwise, ifp
returnedNone
thenq
is parsed, producingy
, andy
is returned. Ifp
orq
fails, the combinator fails.- p
the first parser, which returns an
Option
to eliminate.- q
a parser to execute when
p
returnsNone
, to provide a value of typeA
.- returns
a parser that either just parses
p
or bothp
andq
in order to return anA
.
decide(option(p), q) = p <|> q
Example: - def decide[A](p: Parsley[Option[A]]): Parsley[A]
This combinator can eliminate an
Option
from the result of the parserp
.This combinator can eliminate an
Option
from the result of the parserp
.First parse
p
, if it succeeds returningSome(x)
, then returnx
. However, ifp
fails, or returnedNone
, then this combinator fails.- p
the parser to parse and extract the result from.
- returns
a parser that tries to extract the result from
p
.
decide(option(p)) = p
Example: - def endBy[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses zero or more occurrences of
p
, separated and ended bysep
.This combinator parses zero or more occurrences of
p
, separated and ended bysep
.Behaves just like
endBy1
, except does not require an initialp
andsep
, returning the empty list instead.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = endBy(int, string(";\n")) scala> args.parse("7;\n3;\n2") val res0 = Failure(..) scala> args.parse("") val res1 = Success(Nil) scala> args.parse("1;\n") val res2 = Success(List(1)) scala> args.parse("1;\n2;\n") val res3 = Success(List(1, 2))
Example: - def endBy1[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses one or more occurrences of
p
, separated and ended bysep
.This combinator parses one or more occurrences of
p
, separated and ended bysep
.Parses
p
followed bysep
one or more times. The results of thep
's,x1
throughxn
, are returned asList(x1, .., xn)
. Ifp
orsep
fails having consumed input, the whole parser fails.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = endBy1(int, string(";\n")) scala> args.parse("7;\n3;\n2") val res0 = Failure(..) scala> args.parse("") val res1 = Failure(..) scala> args.parse("1;\n") val res2 = Success(List(1)) scala> args.parse("1;\n2;\n") val res3 = Success(List(1, 2))
Example: - final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def exactly[A](n: Int, p: Parsley[A]): Parsley[List[A]]
This combinator parses exactly
n
occurrences ofp
, returning thesen
results in a list.This combinator parses exactly
n
occurrences ofp
, returning thesen
results in a list.Parses
p
repeatedly up ton
times. Ifp
fails beforen
is reached, then this combinator fails. It is not required forp
to fail after then
th parse. The results produced byp
,x1
throughxn
, are returned asList(x1, .., xn)
.- n
the number of times to repeat
p
.- p
the parser to repeat.
- returns
a parser that parses
p
exactlyn
times, returning a list of the results.
scala> import parsley.character.item scala> import parsley.combinator.exactly scala> val p = exactly(3, item) scala> p.parse("ab") val res0 = Failure(..) scala> p.parse("abc") val res1 = Success(List('a', 'b', 'c')) scala> p.parse("abcd") val res2 = Success(List('a', 'b', 'c'))
- Since
4.0.0
Example: - def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def guardS(p: Parsley[Boolean]): Parsley[Unit]
This combinator verfies that the given parser returns
true
, or else fails.This combinator verfies that the given parser returns
true
, or else fails.First, parse
p
; if it succeeds then, so long at returnstrue
, thisguard(p)
succeeds. Otherwise, ifp
either fails, or returnsfalse
,guard(p)
will fail.- p
the parser that yields the condition value.
guard(pure(true)) == unit guard(pure(false)) == empty when(p.map(!_), empty) == guardS(p)
Example: - def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def ifS[A](condP: Parsley[Boolean], thenP: => Parsley[A], elseP: => Parsley[A]): Parsley[A]
This combinator parses one of
thenP
orelseP
depending on the result of parsingcondP
.This combinator parses one of
thenP
orelseP
depending on the result of parsingcondP
.This is a lifted
if
-statement. First, parsecondP
: if it is successful and returnstrue
, then parsethenP
; else, if it returnedfalse
, parseelseP
; or, ifcondP
failed then fail. If either ofthenP
orelseP
fail, then this combinator also fails.Most useful in conjunction with Registers, as this allows for decisions to be made based on state.
- condP
the parser that yields the condition value.
- thenP
the parser to execute if the condition is
true
.- elseP
the parser to execute if the condition is
false.
- returns
a parser that conditionally parses
thenP
orelseP
aftercondP
.
ifS(pure(true), p, _) == p ifS(pure(false), _, p) == p
- Since
4.5.0
Example: - final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def manyN[A](n: Int, p: Parsley[A]): Parsley[List[A]]
This combinator repeatedly parses a given parser
n
or more times, collecting the results into a list.This combinator repeatedly parses a given parser
n
or more times, collecting the results into a list.Parses a given parser,
p
, repeatedly until it fails. Ifp
failed having consumed input, this combinator fails. Otherwise whenp
fails without consuming input, this combinator will return all of the results,x1
throughxm
(withm >= n
), in a list:List(x1, .., xm)
. Ifp
was not successful at leastn
times, this combinator fails.- n
the minimum number of
p
s required.- p
the parser to execute multiple times.
- returns
a parser that parses
p
until it fails, returning the list of all the successful results.
scala> import parsley.character.string scala> import parsley.combinator.manyN scala> val p = manyN(2, string("ab")) scala> p.parse("") val res0 = Failure(..) scala> p.parse("ab") val res1 = Failure(..) scala> p.parse("abababab") val res2 = Success(List("ab", "ab", "ab", "ab")) scala> p.parse("aba") val res3 = Failure(..)
- Note
many(p) == many(0, p)
andsome(p) == many(1, p)
.
Example: - def manyTill[A](p: Parsley[A], end: Parsley[_]): Parsley[List[A]]
This combinator repeatedly parses a given parser zero or more times, until the
end
parser succeeds, collecting the results into a list.This combinator repeatedly parses a given parser zero or more times, until the
end
parser succeeds, collecting the results into a list.First tries to parse
end
, if it fails without consuming input, then parsesp
, which must succeed. This repeats untilend
succeeds. Whenend
does succeed, this combinator will return all of the results generated byp
,x1
throughxn
(withn >= 0
), in a list:List(x1, .., xn)
. Ifend
could be parsed immediately, the empty list is returned.- p
the parser to execute multiple times.
- end
the parser that stops the parsing of
p
.- returns
a parser that parses
p
untilend
succeeds, returning the list of all the successful results.
This can be useful for scanning comments:
scala> import parsley.character.{string, item, endOfLine} scala> import parsley.combinator.manyTill scala> val comment = string("//") *> manyTill(item, endOfLine) scala> p.parse("//hello world") val res0 = Failure(..) scala> p.parse("//hello world\n") val res1 = Success(List('h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd')) scala> p.parse("//\n") val res2 = Success(Nil)
- Since
4.5.0
Example: - final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- def option[A](p: Parsley[A]): Parsley[Option[A]]
This combinator tries to parse
p
, wrapping its result in aSome
if it succeeds, or returnsNone
if it fails.This combinator tries to parse
p
, wrapping its result in aSome
if it succeeds, or returnsNone
if it fails.Tries to parse
p
. Ifp
succeeded, producingx
, thenSome(x)
is returned. Otherwise, ifp
failed without consuming input, thenNone
is returned instead.- p
the parser to try to parse.
- returns
a parser that tries to parse
p
, but can still succeed withNone
if that was not possible.
scala> import parsley.combinator.option scala> import parsley.character.string scala> val p = option(string("abc")) scala> p.parse("") val res0 = Success(None) scala> p.parse("abc") val res1 = Success(Some("abc")) scala> p.parse("ab") val res2 = Failure(..)
Example: - def optional(p: Parsley[_]): Parsley[Unit]
This combinator will parse
p
if possible, otherwise will do nothing.This combinator will parse
p
if possible, otherwise will do nothing.Tries to parse
p
. Ifp
succeeds, or fails without consuming input then this combinator is successful. Otherwise, ifp
failed having consumed input, this combinator fails.- p
the parser to try to parse.
- returns
a parser that tries to parse
p
.
scala> import parsley.combinator.optional scala> import parsley.character.string scala> val p = optional(string("abc")) scala> p.parse("") val res0 = Success(()) scala> p.parse("abc") val res1 = Success(()) scala> p.parse("ab") val res2 = Failure(..)
- Note
equivalent to
optionalAs(p, ())
.
Example: - def optionalAs[A](p: Parsley[_], x: A): Parsley[A]
This combinator will parse
p
if possible, otherwise will do nothing.This combinator will parse
p
if possible, otherwise will do nothing.Tries to parse
p
. Ifp
succeeds, or fails without consuming input then this combinator is successful and returnsx
. Otherwise, ifp
failed having consumed input, this combinator fails.- p
the parser to try to parse.
- x
the value to return regardless of how
p
performs.- returns
a parser that tries to parse
p
, returningx
regardless of success or failure.
scala> import parsley.combinator.optionalAs scala> import parsley.character.string scala> val p = optionalAs(string("abc"), 7) scala> p.parse("") val res0 = Success(7) scala> p.parse("abc") val res1 = Success(7) scala> p.parse("ab") val res2 = Failure(..)
Example: - def range[A](min: Int, max: Int)(p: Parsley[A]): Parsley[List[A]]
This combinator parses between
min
andmax
occurrences ofp
, returning thesen
results in a list.This combinator parses between
min
andmax
occurrences ofp
, returning thesen
results in a list.Parses
p
repeatedly a minimum ofmin
times and up tomax
times both inclusive. Ifp
fails beforemin
is reached, then this combinator fails. It is not required forp
to fail after themax
th parse. The results produced byp
,xmin
throughxmax
, are returned asList(xmin, .., xmax)
.- min
the minimum number of times to repeat
p
, inclusive.- max
the maximum number of times to repeat
p
, inclusive.- p
the parser to repeat.
- returns
the results of the successful parses of
p
.
scala> import parsley.character.item scala> import parsley.combinator.range scala> val p = range(min=3, max=5)(item) scala> p.parse("ab") val res0 = Failure(..) scala> p.parse("abc") val res1 = Success(List('a', 'b', 'c')) scala> p.parse("abcd") val res2 = Success(List('a', 'b', 'c', 'd')) scala> p.parse("abcde") val res2 = Success(List('a', 'b', 'c', 'd', 'e')) scala> p.parse("abcdef") val res2 = Success(List('a', 'b', 'c', 'd', 'e'))
- Since
4.4.0
Example: - def sepBy[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses zero or more occurrences of
p
, separated bysep
.This combinator parses zero or more occurrences of
p
, separated bysep
.Behaves just like
sepBy1
, except does not require an initialp
, returning the empty list instead.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = sepBy(int, string(", ")) scala> args.parse("7, 3, 2") val res0 = Success(List(7, 3, 2)) scala> args.parse("") val res1 = Success(Nil) scala> args.parse("1") val res2 = Success(List(1)) scala> args.parse("1, 2, ") val res3 = Failure(..) // no trailing comma allowed
Example: - def sepBy1[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses one or more occurrences of
p
, separated bysep
.This combinator parses one or more occurrences of
p
, separated bysep
.First parses a
p
. Then parsessep
followed byp
until there are no moresep
s. The results of thep
's,x1
throughxn
, are returned asList(x1, .., xn)
. Ifp
orsep
fails having consumed input, the whole parser fails. Requires at least onep
to have been parsed.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = sepBy1(int, string(", ")) scala> args.parse("7, 3, 2") val res0 = Success(List(7, 3, 2)) scala> args.parse("") val res1 = Failure(..) scala> args.parse("1") val res2 = Success(List(1)) scala> args.parse("1, 2, ") val res3 = Failure(..) // no trailing comma allowed
Example: - def sepEndBy[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses zero or more occurrences of
p
, separated and optionally ended bysep
.This combinator parses zero or more occurrences of
p
, separated and optionally ended bysep
.Behaves just like
sepEndBy1
, except does not require an initialp
, returning the empty list instead.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = sepEndBy(int, string(";\n")) scala> args.parse("7;\n3;\n2") val res0 = Success(List(7, 3, 2)) scala> args.parse("") val res1 = Success(Nil) scala> args.parse("1") val res2 = Success(List(1)) scala> args.parse("1;\n2;\n") val res3 = Success(List(1, 2))
Example: - def sepEndBy1[A](p: Parsley[A], sep: => Parsley[_]): Parsley[List[A]]
This combinator parses one or more occurrences of
p
, separated and optionally ended bysep
.This combinator parses one or more occurrences of
p
, separated and optionally ended bysep
.First parses a
p
. Then parsessep
followed byp
until there are no more: if a finalsep
exists, this is parsed. The results of thep
's,x1
throughxn
, are returned asList(x1, .., xn)
. Ifp
orsep
fails having consumed input, the whole parser fails. Requires at least onep
to have been parsed.- p
the parser whose results are collected into a list.
- sep
the delimiter that must be parsed between every
p
.- returns
a parser that parses
p
delimited bysep
, returning the list ofp
's results.
scala> ... scala> val args = sepEndBy1(int, string(";\n")) scala> args.parse("7;\n3;\n2") val res0 = Success(List(7, 3, 2)) scala> args.parse("") val res1 = Failure(..) scala> args.parse("1") val res2 = Success(List(1)) scala> args.parse("1;\n2;\n") val res3 = Success(List(1, 2))
Example: - def sequence[A](p0: Parsley[A], ps: Parsley[A]*): Parsley[List[A]]
This combinator will parse each of
ps
in order, collecting the results.This combinator will parse each of
ps
in order, collecting the results.Given the parsers
ps
, consisting ofp1
throughpn
, parses each in order. If they all succeed, producing the resultsx1
throughxn
, thenList(x1, .., xn)
is returned. If any of the parsers fail, then the whole combinator fails.- p0
the first parser to be sequenced
- ps
parsers to be sequenced.
- returns
a parser that parses each of
ps
, returning the results in a list
scala> import parsley.combinator.sequence scala> import parsley.character.{char, item} scala> val p = sequence(char('a'), item, char('c')) scala> p.parse("abc") val res0 = Success(List('a', 'b', 'c')) scala> p.parse("ab") val res1 = Failure(..)
- Since
4.0.0
- Note
be aware that all of the arguments to this combinator are in strict positions.
- See also
Example: - def someTill[A](p: Parsley[A], end: Parsley[_]): Parsley[List[A]]
This combinator repeatedly parses a given parser one or more times, until the
end
parser succeeds, collecting the results into a list.This combinator repeatedly parses a given parser one or more times, until the
end
parser succeeds, collecting the results into a list.First ensures that trying to parse
end
fails, then tries to parsep
. If it succeed then it will repeatedly: try to parseend
, if it fails without consuming input, then parsesp
, which must succeed. Whenend
does succeed, this combinator will return all of the results generated byp
,x1
throughxn
(withn >= 1
), in a list:List(x1, .., xn)
. The parserp
must succeed at least once beforeend
succeeds.- p
the parser to execute multiple times.
- end
the parser that stops the parsing of
p
.- returns
a parser that parses
p
untilend
succeeds, returning the list of all the successful results.
This can be useful for scanning comments:
scala> import parsley.character.{string, item, endOfLine} scala> import parsley.combinator.someUntil scala> val comment = string("//") *> someUntil(item, endOfLine) scala> p.parse("//hello world") val res0 = Failure(..) scala> p.parse("//hello world\n") val res1 = Success(List('h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd')) scala> p.parse("//\n") val res2 = Failure(..) scala> p.parse("//a\n") val res3 = Success(List('a'))
- Since
4.5.0
Example: - final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- def traverse[A, B](x0: A, xs: A*)(f: (A) => Parsley[B]): Parsley[List[B]]
This combinator will parse each of the parsers generated by applying
f
toxs
, in order, collecting the results.This combinator will parse each of the parsers generated by applying
f
toxs
, in order, collecting the results.Given the values
xs
, consisting ofx1
throughxn
, first creates the parsesf(x1)
throughf(xn)
and then calledsequence
on them.- x0
the first value to turn into a parser and sequence.
- xs
the values to turn into parsers and sequence.
- f
the function used to generate parsers for each values
- returns
a parser that sequences the parsers generated from applying
f
to each ofxs
.
// this is an OK implementation for `string`, which is common in Haskell. def string(str: String) = { traverse(str: _*)(char).span }
- Since
4.0.0
- Note
be aware that all of the arguments to this combinator are in strict positions.
- See also
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()
- def whenS(condP: Parsley[Boolean])(thenP: => Parsley[Unit]): Parsley[Unit]
This combinator conditionally parses
thenP
depending on the result of parsingcondP
.This combinator conditionally parses
thenP
depending on the result of parsingcondP
.This is a lifted
if
-statement. First, parsecondP
: if it is successful and returnstrue
, then parsethenP
; else, if it returnedfalse
do nothing; or, ifcondP
failed then fail. IfthenP
fails, then this combinator also fails.Most useful in conjunction with Registers, as this allows for decisions to be made based on state.
- condP
the parser that yields the condition value.
- thenP
the parser to execute if the condition is
true
.- returns
a parser that conditionally parses
thenP
aftercondP
.
whenS(pure(true), p) == p whenS(pure(false), _) == unit
Example: - def whileS(p: Parsley[Boolean]): Parsley[Unit]
This combinator repeatedly parses
p
so long as it returnstrue
.This combinator repeatedly parses
p
so long as it returnstrue
.This is a lifted
while
-loop. First, parsep
: if it is successful and returnstrue
, then repeat; else if it returnedfalse
stop; or, if it failed then this combinator fails.Most useful in conjunction with Registers, as this allows for decisions to be made based on state. In particular, this can be used to define the
forP
combinator.- p
the parser to repeatedly parse.
- returns
a parser that continues to parse
p
until it returnsfalse
.
def forP[A](init: Parsley[A], cond: =>Parsley[A => Boolean], step: =>Parsley[A => A])(body: =>Parsley[_]): Parsley[Unit] = { val reg = Reg.make[A] lazy val _cond = reg.gets(cond) lazy val _step = reg.modify(step) reg.put(init) *> whenS(_cond, whileS(body *> _step *> _cond)) }
Example:
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. Depending on the combinator, all of the results produced by the
repeated execution of the parser may be returned in a List
. These are almost essential for any practical parsing
task.
Optional Parsing Combinators
These combinators allow for the possible parsing of some parser. If the parser succeeds, that is ok
so long as it did not consume input. Be aware that the result of the success may be replaced with
these combinators, with the exception of option
, which still preserves the result.
Separated Values Combinators
These combinators are concerned with delimited parsing, where one parser is repeated but delimited by another one.
In each of these cases p
is the parser of interest and sep
is the delimeter. These combinators mainly differ
in either the number of p
s they require, or exactly where the delimeters are allowed (only between, always
trailing, or either). In all cases, they return the list of results generated by the repeated parses of p
.
Multiple Branching/Sequencing Combinators
These combinators allow for testing or sequencing a large number of parsers in one go. Be careful, however, these are
variadic combinators and are necessarily (for compatibility with Scala 2) not lazy.
In such a case where laziness is desired without resorting to the other lazier combinators, there
is a neat trick: unroll the first iteration of the combinator, and use the corresponding regular combinator
to do that (i.e. <::>
or *>
): since these will have a lazy
right-hand side, the remaining variadic arguments will be kept lazily suspended until later. Alternatively,
it is possible to use the prefix ~
combinator to make any individual
arguments lazy as required, for example skip(p, ~q, r)
.
Range Combinators
These combinators allow for the parsing of a specific parser either a specific number of times, or between a certain amount of times.
This is the documentation for Parsley.
Package structure
The parsley package contains the
Parsley
class, as well as theResult
,Success
, andFailure
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 parsingparsley.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 inchain
.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.errors.combinator
provides combinators that can be used to either produce more detailed errors as well as refine existing errors.parsley.errors.tokenextractors
provides mixins for common token extraction strategies during error message generation: these can be used to avoid implementingunexpectedToken
in theErrorBuilder
.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 theLexer
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.