Parser0
Parser0[A]
attempts to extract an
potentially moving its offset forward in the process.
A
value from the given input,potentially moving its offset forward in the process.
When calling
parse
, one of three outcomes occurs:-
Success: The parser consumes zero-or-more characters of input
and successfully extracts a value. The input offset will be
moved forward by the number of characters consumed. -
Epsilon failure: The parser fails to extract a value without
consuming any characters of input. The input offset will not be
changed. -
Arresting failure: The parser fails to extract a value but does
consume one-or-more characters of input. The input offset will
be moved forward by the number of characters consumed and all
parsing will stop (unless a higher-level parser backtracks).
Operations such as
an arresting failure. Arresting failures can be "rewound" using
methods such as
from
rewind successful parses by
failures for
x.orElse(y)
will only consider parser y
ifx
returns an epsilon failure; these methods cannot recover froman arresting failure. Arresting failures can be "rewound" using
methods such as
x.backtrack
(which converts arresting failuresfrom
x
into epsilon failures), or softProduct(x, y)
(which canrewind successful parses by
x
that are followed by epsilonfailures for
y
).Rewinding tends to make error reporting more difficult and can lead
to exponential parser behavior it is not the default behavior.
to exponential parser behavior it is not the default behavior.
- Companion
- object
Value members
Methods
Attempt to parse an
A
value out of str
.This method will either return a failure, or else the remaining
string and the parsed value.
string and the parsed value.
To require the entire input to be consumed, see
parseAll
.Attempt to parse all of the input
str
into an A
value.This method will return a failure unless all of
during parsing.
str
is consumedduring parsing.
p.parseAll(s)
is equivalent to (p <* Parser.end).parse(s).map(_._2)
.Convert epsilon failures into None values.
Normally if a parser fails to consume any input it fails with an
epsilon failure. The
None values (and wraps other values in
epsilon failure. The
?
method converts these failures intoNone values (and wraps other values in
Some(_)
).If the underlying parser failed with other errors, this parser
will still fail.
will still fail.
If this parser fails to parse its input with an epsilon error,
try the given parser instead.
try the given parser instead.
If this parser fails with an arresting error, the next parser
won't be tried.
won't be tried.
Backtracking may be used on the left parser to allow the right
one to pick up after any error, resetting any state that was
modified by the left parser.
one to pick up after any error, resetting any state that was
modified by the left parser.
This method is similar to Parser#orElse but returns Either.
Parse without capturing values.
Calling
it allows the parser to avoid allocating results to return.
void
on a parser can be a significant optimization --it allows the parser to avoid allocating results to return.
Other methods like
discard allocations, since they will ignore the original parsed
result.
as
, *>
, and <*
use void
internally todiscard allocations, since they will ignore the original parsed
result.
Return the string matched by this parser.
When parsing an input string that the underlying parser matches,
this parser will return the matched substring instead of any
value that the underlying parser would have returned. It will
still match exactly the same inputs as the original parser.
this parser will return the matched substring instead of any
value that the underlying parser would have returned. It will
still match exactly the same inputs as the original parser.
This method is very efficient: similarly to
allocating results to return.
void
, we can avoidallocating results to return.
If this parser fails to match, rewind the offset to the starting
point before moving on to other parser.
point before moving on to other parser.
This method converts arresting failures into epsilon failures,
which includes rewinding the offset to that used before parsing
began.
which includes rewinding the offset to that used before parsing
began.
This method will most often be used before calling methods such
as
picking up where this one left off.
as
orElse
, ~
, or flatMap
which involve a subsequent parserpicking up where this one left off.
Sequence another parser after this one, combining both results
into a tuple.
into a tuple.
This combinator returns a product of parsers. If this parser
successfully produces an
the remaining input to try to produce a
successfully produces an
A
value, the other parser is run onthe remaining input to try to produce a
B
value.If either parser produces an error the result is an error.
Otherwise both extracted values are combined into a tuple.
Otherwise both extracted values are combined into a tuple.
Compose two parsers, ignoring the values extracted by the
left-hand parser.
left-hand parser.
x *> y
is equivalent to (x.void ~ y).map(_._2)
.Compose two parsers, ignoring the values extracted by the
right-hand parser.
right-hand parser.
x <* y
is equivalent to (x ~ y.void).map(_._1)
.If this parser fails to parse its input with an epsilon error,
try the given parser instead.
try the given parser instead.
If this parser fails with an arresting error, the next parser
won't be tried.
won't be tried.
Backtracking may be used on the left parser to allow the right
one to pick up after any error, resetting any state that was
modified by the left parser.
one to pick up after any error, resetting any state that was
modified by the left parser.
Transform parsed values using the given function.
This parser will match the same inputs as the underlying parser,
using the given function
underlying parser produces.
using the given function
f
to transform the values theunderlying parser produces.
If the underlying value is ignored (e.g.
map(_ => ...)
) callingvoid
before map
will improve the efficiency of the parser.Transform parsed values using the given function, or fail on None
When the function return None, this parser fails
This is implemented with select, which makes it more efficient
than using flatMap
This is implemented with select, which makes it more efficient
than using flatMap
Transform parsed values using the given function, or fail when not defined
When the function is not defined, this parser fails
This is implemented with select, which makes it more efficient
than using flatMap
This is implemented with select, which makes it more efficient
than using flatMap
If the predicate is not true, fail
you may want .filter(fn).backtrack so if the filter fn
fails you can fall through in an oneOf0 or orElse
you may want .filter(fn).backtrack so if the filter fn
fails you can fall through in an oneOf0 or orElse
Without the backtrack, a failure of the function will
be an arresting failure.
be an arresting failure.
Dynamically construct the next parser based on the previously
parsed value.
parsed value.
Using
prefer to use methods such as
since these are much more efficient.
flatMap
is very expensive. When possible, you shouldprefer to use methods such as
~
, *>
, or <*
when possible,since these are much more efficient.
Wrap this parser in a helper class, enabling better composition
with
with
Parser
values.For example, with
p: Parser0[Int]
and p1: Parser0[Double]
:val a1: Parser0[(Int, Double)]
= p ~ p1
val a2: Parser[(Int, Double)] = p.with1 ~ p1
val a2: Parser[(Int, Double)] = p.with1 ~ p1
val b1: Parser0[Double]
= p *> p1
val b2: Parser[Double] = p.with1 *> p1
val b2: Parser[Double] = p.with1 *> p1
val c1: Parser0[Int]
= p <* p1
val c2: Parser[Int] = p.with1 <* p1
val c2: Parser[Int] = p.with1 <* p1
Without using
since they are not known to return
with1
, these methods will return Parser0
valuessince they are not known to return
Parser
values instead.Wrap this parser in a helper class, to enable backtracking during
composition.
composition.
This wrapper changes the behavior of
no backtracking occurs. Using
enable backtracking if the right-hand side returns an epsilon
failure (but not in any other case).
~
, <*
and *>
. Normallyno backtracking occurs. Using
soft
on the left-hand side willenable backtracking if the right-hand side returns an epsilon
failure (but not in any other case).
For example,
failure, the parser will "rewind" to the point before
(x ~ y)
will never backtrack. But with (x.soft ~
y)
, if x
parses successfully, and y
returns an epsilonfailure, the parser will "rewind" to the point before
x
began.Return a parser that succeeds (consuming nothing, and extracting
nothing) if the current parser would fail.
nothing) if the current parser would fail.
This parser expects the underlying parser to fail, and will
unconditionally backtrack after running it.
unconditionally backtrack after running it.
Return a parser that succeeds (consuming nothing and extracting
nothing) if the current parser would also succeed.
nothing) if the current parser would also succeed.
This parser expects the underlying parser to succeed, and will
unconditionally backtrack after running it.
unconditionally backtrack after running it.
Use this parser to parse between values.
Parses
Returns only the values extracted by
b
followed by this
and c
.Returns only the values extracted by
this
parser.