jfun.parsec
Class Parser<Type>

java.lang.Object
  extended by jfun.parsec.Parser<Type>
All Implemented Interfaces:
java.io.Serializable

public abstract class Parser<Type>
extends java.lang.Object
implements java.io.Serializable

A parser runs either on character level or token level. It takes as input a CharSequence object or a Tok[] array, recognizes certain patterns and returns a value.

Author:
Ben Yu 2004-11-11
See Also:
Serialized Form

Method Summary
<T,R> Parser<R>
and(Parser<T> p, Map2<? super Type,? super T,R> m)
          it sequentially run this and p, and then transforms the two return values with m to a new return value.
<T,R> Parser<R>
and(java.lang.String name, Parser<T> p, Map2<? super Type,? super T,R> m)
          it sequentially run this and p, and then transforms the two return values with m to a new return value.
 Parser<Type> atomize()
          Make sure 'this' is atomic.
 Parser<Type> atomize(java.lang.String name)
          Make sure 'this' is atomic.
<To> Parser<To>
bind(java.lang.String name, ToParser<? super Type,To> tp)
          if this parser succeeds, the returned value gets passed on to tp.
<To> Parser<To>
bind(ToParser<? super Type,To> tp)
          if this parser succeeds, the returned value gets passed on to tp.
<R extends Type>
Parser<R>
cast()
          To cast the current Parser to a Parser object that returns a subtype of the current type.
<R extends Type>
Parser<R>
cast(java.lang.Class<R> type)
          To cast the current Parser to a Parser object that returns a subtype of the current type.
<R> Parser<R>
convert()
          To convert the current Parser to a Parser object that returns any target type.
<R> Parser<R>
convert(java.lang.Class<R> type)
          To convert the current Parser to a Parser object that returns any target type.
 Parser<Type> followedBy(Parser<?> sep)
          'this' and 'sep' are executed sequentially.
 Parser<Type> followedBy(java.lang.String name, Parser<?> sep)
          'this' and 'sep' are executed sequentially.
<R> Parser
ifelse(Parser<R> yes, Parser<? extends R> no)
          run yes if this succeeds, no if this fails without consuming input; fails otherwise.
<R> Parser<R>
ifelse(java.lang.String name, Parser<R> yes, Parser<R> no)
          run yes if this succeeds, no if this fails without consuming input; fails otherwise.
<R> Parser<R>
ifelse(java.lang.String name, ToParser<? super Type,R> yes, Parser<R> no)
          run yes if this succeeds, no if this fails without consuming input; fails otherwise.
<R> Parser<R>
ifelse(ToParser<? super Type,R> yes, Parser<R> no)
          run yes if this succeeds, no if this fails without consuming input; fails otherwise.
 Parser<Type> isReturn(ObjectPredicate<? super Type> op)
          Fails if the return value of this parser does not satisify the given predicate.
 Parser<Type> isReturn(ObjectPredicate<? super Type> op, java.lang.String expecting)
          Fails if the return value of this parser does not satisify the given predicate.
 Parser<Type> isReturn(java.lang.String name, ObjectPredicate<? super Type> op)
          Fails if the return value of this parser does not satisify the given predicate.
 Parser<Type> isReturn(java.lang.String name, ObjectPredicate<? super Type> op, java.lang.String expecting)
          Fails if the return value of this parser does not satisify the given predicate.
 Parser<Type> label(java.lang.String lbl)
          if fails and did not consume input, reports an expecting error with the given label.
 Parser<Type> label(java.lang.String name, java.lang.String lbl)
          if fails and did not consume input, reports an expecting error with the given label.
 Parser<Type> lookahead(int toknum)
          By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed and consumed some input.
 Parser<Type> lookahead(java.lang.String name, int toknum)
          By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed and consumed some input.
 Parser<_> many()
          p.many() is equivalent to p* in EBNF.
 Parser<Type[]> many(ArrayFactory<Type> af)
          p.many(af) is equivalent to p* in EBNF.
 Parser<Type[]> many(ArrayFactory<Type> af, int min)
          Runs this parser greedily for at least min times.
 Parser<Type[]> many(java.lang.Class<Type> elem_type)
          p.many(elem_type) is equivalent to p* in EBNF.
 Parser<Type[]> many(java.lang.Class<Type> elem_type, int min)
          Runs this parser greedily for at least min times.
 Parser<_> many(int min)
          Runs this parser greedily for at least min times.
 Parser<_> many(java.lang.String name)
          p.many(name) is equivalent to p* in EBNF.
 Parser<Type[]> many(java.lang.String name, ArrayFactory<Type> af)
          p.many(name, af) is equivalent to p* in EBNF.
 Parser<Type[]> many(java.lang.String name, ArrayFactory<Type> af, int min)
          Runs this parser greedily for at least min times.
 Parser<Type[]> many(java.lang.String name, java.lang.Class<Type> elem_type)
          p.many(name, elem_type) is equivalent to p* in EBNF.
 Parser<Type[]> many(java.lang.String name, java.lang.Class<Type> elem_type, int min)
          Runs this parser greedily for at least min times.
 Parser<_> many(java.lang.String name, int min)
          Runs this parser greedily for at least min times.
 Parser<_> many1()
          p.many1() is equivalent to p+ in EBNF.
 Parser<Type[]> many1(ArrayFactory<Type> af)
          p.many1(af) is equivalent to p+ in EBNF.
 Parser<Type[]> many1(java.lang.Class<Type> elem_type)
          p.many1(elem_type) is equivalent to p+ in EBNF.
 Parser<_> many1(java.lang.String name)
          p.many1(name) is equivalent to p+ in EBNF.
 Parser<Type[]> many1(java.lang.String name, ArrayFactory<Type> af)
          p.many1(name, af) is equivalent to p+ in EBNF.
 Parser<Type[]> many1(java.lang.String name, java.lang.Class<Type> elem_type)
          p.many1(name, elem_type) is equivalent to p+ in EBNF.
<R> Parser<R>
map(Map<? super Type,R> m)
          if this succeeds, the returned value is transformed with m to a new return value.
<R> Parser<R>
map(java.lang.String name, Map<? super Type,R> m)
          if this succeeds, the returned value is transformed with m to a new return value.
 Parser<?> not()
          fails if 'this' succeeds.
 Parser<?> not(java.lang.String err)
          fails if 'this' succeeds.
 Parser<?> not(java.lang.String name, java.lang.String err)
          fails if 'this' succeeds.
 Parser<Type> option(java.lang.String name, Type def)
          If this fails with no input consumed, the default value is returned.
 Parser<Type> option(Type def)
          If this fails with no input consumed, the default value is returned.
 Parser<Type> optional()
          p.optional() is equivalent to p? in EBNF.
 Parser<Type> optional(java.lang.String name)
          p.optional(name) is equivalent to p? in EBNF.
 Type parse(java.lang.CharSequence source)
          To parse a source string.
 Type parse(java.lang.CharSequence source, java.lang.String moduleName)
          To parse a source string.
 Parser<Type> peek()
          this is a look-ahead operation.
 Parser<Type> peek(java.lang.String name)
          this is a look-ahead operation.
 Parser<Type> printError(java.lang.String id)
          Create a Parser object that traces the parsing error of this parser when it fails.
 Parser<Type> printError(java.lang.String id, int min_steps)
          Create a Parser object that traces the parsing error of this parser when it fails.
 Parser<Type> printResult(java.lang.String id)
          Create a Parser object that traces the parsing result of this parser when it succeeds.
 Parser<Type> printTrace(java.lang.String id)
          Create a Parser object that traces the parsing result of this parser when it terminates.
 Parser<Type[]> repeat(ArrayFactory<Type> af, int n)
          Run Parser 'this' for n times, collect the return values in an array created by the ArrayFactory object.
 Parser<Type[]> repeat(java.lang.Class<Type> etype, int n)
          Run Parser 'this' for n times, collect the return values in an array whose element type is etype.
 Parser<_> repeat(int n)
          Run Parser 'this' for n times.
 Parser<Type[]> repeat(java.lang.String name, ArrayFactory<Type> af, int n)
          Run Parser 'this' for n times, collect the return values in an array created by the ArrayFactory object.
 Parser<Type[]> repeat(java.lang.String name, java.lang.Class<Type> etype, int n)
          Run Parser 'this' for n times, collect the return values in an array whose element type is etype.
 Parser<_> repeat(java.lang.String name, int n)
          Run Parser 'this' for n times.
<R> Parser<R>
seq(Parser<R> p)
          if this parser succeeds, the returned value is discarded and the next parser is excuted.
<R> Parser<R>
seq(java.lang.String name, Parser<R> p)
          if this parser succeeds, the returned value is discarded and the next parser is excuted.
 Parser<Type[]> some(ArrayFactory<Type> af, int max)
          Runs this for up to max times.
 Parser<Type[]> some(ArrayFactory<Type> af, int min, int max)
          Runs this for at least min times and at most max times.
 Parser<Type[]> some(java.lang.Class<Type> etype, int max)
          Runs this for up to max times.
 Parser<Type[]> some(java.lang.Class<Type> elem_type, int min, int max)
          Runs this for at least min times and at most max times.
 Parser<_> some(int max)
          Runs this for up to max times.
 Parser<_> some(int min, int max)
          Runs this for at least min times and at most max times.
 Parser<Type[]> some(java.lang.String name, ArrayFactory<Type> af, int max)
          Runs this for up to max times.
 Parser<Type[]> some(java.lang.String name, ArrayFactory<Type> af, int min, int max)
          Runs this for at least min times and at most max times.
 Parser<Type[]> some(java.lang.String name, java.lang.Class<Type> etype, int max)
          Runs this for up to max times.
 Parser<Type[]> some(java.lang.String name, java.lang.Class<Type> elem_type, int min, int max)
          Runs this for at least min times and at most max times.
 Parser<_> some(java.lang.String name, int max)
          Runs this for up to max times.
 Parser<_> some(java.lang.String name, int min, int max)
          Runs this for at least min times and at most max times.
 Parser<Type> step()
          lookahead looks at logical steps.
 Parser<Type> step(int n)
          lookahead looks at logical steps.
 Parser<Type> step(java.lang.String name)
          lookahead looks at logical steps.
 Parser<Type> step(java.lang.String name, int n)
          lookahead looks at logical steps.
 java.lang.String toString()
           
 Parser<Type> trace(Trace<? super Type> trc)
          Create a Parser object that traces the parsing result of this parser.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

trace

public final Parser<Type> trace(Trace<? super Type> trc)
Create a Parser object that traces the parsing result of this parser. Only effective when Parsers.isDebugEnabled() returns true.

Parameters:
trc - the Trace object.
Returns:
the new Parser object.
Since:
version 1.1

printError

public final Parser<Type> printError(java.lang.String id,
                                     int min_steps)
Create a Parser object that traces the parsing error of this parser when it fails. Only effective when Parsers.isDebugEnabled() returns true.

Parameters:
id - the identifier of the parser object in the trace message.
min_steps - the minimal logical steps consumed to trigger the trace message.
Returns:
the new Parser object.
Since:
version 1.1

printError

public final Parser<Type> printError(java.lang.String id)
Create a Parser object that traces the parsing error of this parser when it fails. Only effective when Parsers.isDebugEnabled() returns true. The trace message is triggered only when 1 or more logical steps are consumed.

Parameters:
id - the identifier of the parser object in the trace message.
Returns:
the new Parser object.
Since:
version 1.1

printResult

public final Parser<Type> printResult(java.lang.String id)
Create a Parser object that traces the parsing result of this parser when it succeeds. Only effective when Parsers.isDebugEnabled() returns true.

Parameters:
id - the identifier of the parser object in the trace message.
Returns:
the new Parser object.
Since:
version 1.1

printTrace

public final Parser<Type> printTrace(java.lang.String id)
Create a Parser object that traces the parsing result of this parser when it terminates. Only effective when Parsers.isDebugEnabled() returns true.

Parameters:
id - the identifier of the parser object in the trace message.
Returns:
the new Parser object.
Since:
version 1.1

bind

public final <To> Parser<To> bind(ToParser<? super Type,To> tp)
if this parser succeeds, the returned value gets passed on to tp. The monadic bind (product) operation.

Parameters:
tp - the next step.
Returns:
the new Parser.

bind

public final <To> Parser<To> bind(java.lang.String name,
                                  ToParser<? super Type,To> tp)
if this parser succeeds, the returned value gets passed on to tp. The monadic bind (product or >>=) operation.

Parameters:
name - the name of the new parser.
tp - the next step.
Returns:
the new Parser.

seq

public final <R> Parser<R> seq(Parser<R> p)
if this parser succeeds, the returned value is discarded and the next parser is excuted. The monadic seq (>>) operation.

Parameters:
p - the next parser.
Returns:
the new Parser.

seq

public final <R> Parser<R> seq(java.lang.String name,
                               Parser<R> p)
if this parser succeeds, the returned value is discarded and the next parser is excuted. The monadic seq (>>) operation.

Parameters:
name - the name of the new parser.
p - the next parser.
Returns:
the new Parser.

repeat

public final Parser<_> repeat(int n)
Run Parser 'this' for n times. The return values are discarded.

Parameters:
n - the number of times to run.
Returns:
the new Parser object.

repeat

public final Parser<Type[]> repeat(java.lang.Class<Type> etype,
                                   int n)
Run Parser 'this' for n times, collect the return values in an array whose element type is etype.

Parameters:
etype - the array element type.
n - the number of times to run.
Returns:
the new Parser object.

repeat

public final Parser<Type[]> repeat(ArrayFactory<Type> af,
                                   int n)
Run Parser 'this' for n times, collect the return values in an array created by the ArrayFactory object.

Parameters:
af - the ArrayFactory object.
n - the number of times to run.
Returns:
the new Parser object.

repeat

public final Parser<_> repeat(java.lang.String name,
                              int n)
Run Parser 'this' for n times. The return values are discarded.

Parameters:
name - the name of the new Parser object.
n - the number of times to run.
Returns:
the new Parser object.

repeat

public final Parser<Type[]> repeat(java.lang.String name,
                                   java.lang.Class<Type> etype,
                                   int n)
Run Parser 'this' for n times, collect the return values in an array whose element type is etype.

Parameters:
name - the name of the new Parser object.
etype - the array element type.
n - the number of times to run.
Returns:
the new Parser object.

repeat

public final Parser<Type[]> repeat(java.lang.String name,
                                   ArrayFactory<Type> af,
                                   int n)
Run Parser 'this' for n times, collect the return values in an array created by the ArrayFactory object.

Parameters:
name - the name of the new Parser object.
af - the ArrayFactory object.
n - the number of times to run.
Returns:
the new Parser object.

many

public final Parser<Type[]> many(ArrayFactory<Type> af)
p.many(af) is equivalent to p* in EBNF. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
af - the ArrayFactory.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.String name,
                                 ArrayFactory<Type> af)
p.many(name, af) is equivalent to p* in EBNF. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
name - the name of the new parser.
af - the ArrayFactory.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.Class<Type> elem_type)
p.many(elem_type) is equivalent to p* in EBNF. The return values are collected and returned in an array.

Parameters:
elem_type - the element type of the result array.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.String name,
                                 java.lang.Class<Type> elem_type)
p.many(name, elem_type) is equivalent to p* in EBNF. The return values are collected and returned in an array.

Parameters:
name - the name of the new parser.
elem_type - the element type of the result array.
Returns:
the new Parser.

many

public final Parser<_> many()
p.many() is equivalent to p* in EBNF. The return values are discarded.

Returns:
the new Parser.

many

public final Parser<_> many(java.lang.String name)
p.many(name) is equivalent to p* in EBNF. The return values are discarded.

Parameters:
name - the name of the new parser.
Returns:
the new Parser.

many

public final Parser<Type[]> many(ArrayFactory<Type> af,
                                 int min)
Runs this parser greedily for at least min times. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
af - the ArrayFactory.
min - the minimal number of times to run this parser.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.String name,
                                 ArrayFactory<Type> af,
                                 int min)
Runs this parser greedily for at least min times. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
name - the name of the new parser.
af - the ArrayFactory.
min - the minimal number of times to run this parser.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.Class<Type> elem_type,
                                 int min)
Runs this parser greedily for at least min times. The return values are collected and returned in an array.

Parameters:
elem_type - the element type of the result array.
min - the minimal number of times to run this parser.
Returns:
the new Parser.

many

public final Parser<Type[]> many(java.lang.String name,
                                 java.lang.Class<Type> elem_type,
                                 int min)
Runs this parser greedily for at least min times. The return values are collected and returned in an array.

Parameters:
name - the name of the new parser.
elem_type - the element type of the result array.
min - the minimal number of times to run this parser.
Returns:
the new Parser.

many

public final Parser<_> many(int min)
Runs this parser greedily for at least min times. The return values are discarded.

Returns:
the new Parser.

many

public final Parser<_> many(java.lang.String name,
                            int min)
Runs this parser greedily for at least min times. The return values are discarded.

Parameters:
name - the name of the new parser.
min - the minimal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<Type[]> some(ArrayFactory<Type> af,
                                 int min,
                                 int max)
Runs this for at least min times and at most max times. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
af - the ArrayFactory.
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.String name,
                                 ArrayFactory<Type> af,
                                 int min,
                                 int max)
Runs this for at least min times and at most max times. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
name - the name of the new parser.
af - the ArrayFactory.
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.Class<Type> elem_type,
                                 int min,
                                 int max)
Runs this for at least min times and at most max times. The return values are collected and returned in an array whose element type is elem_type.

Parameters:
elem_type - the element type of the result array.
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.String name,
                                 java.lang.Class<Type> elem_type,
                                 int min,
                                 int max)
Runs this for at least min times and at most max times. The return values are collected and returned in an array whose element type is elem_type.

Parameters:
elem_type - the element type of the result array.
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<_> some(int min,
                            int max)
Runs this for at least min times and at most max times. The return values are discarded.

Parameters:
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<_> some(java.lang.String name,
                            int min,
                            int max)
Runs this for at least min times and at most max times. The return values are discarded.

Parameters:
name - the name of the new parser.
min - the minimal number of times to run this parser.
max - the maximal number of times to run this parser.
Returns:
the new Parser.

some

public final Parser<_> some(int max)
Runs this for up to max times. The return values are discarded.

Parameters:
max - the maximal number of times to run.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.Class<Type> etype,
                                 int max)
Runs this for up to max times. The return values are collected and returned in an array whose element type is etype.

Parameters:
etype - the element type of the result array.
max - the maximal number times to run.
Returns:
the new Parser.

some

public final Parser<Type[]> some(ArrayFactory<Type> af,
                                 int max)
Runs this for up to max times. The return values are collected and returned in an array created by af.

Parameters:
max - the maximal number of times to run.
Returns:
the new Parser.

some

public final Parser<_> some(java.lang.String name,
                            int max)
Runs this for up to max times. The return values are discarded.

Parameters:
name - the name of the new parser.
max - the maximal number times to run.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.String name,
                                 java.lang.Class<Type> etype,
                                 int max)
Runs this for up to max times. The return values are collected and returned in an array whose element type is etype.

Parameters:
name - the name of the new parser.
etype - the element type of the result array.
max - the maximal number of times to run.
Returns:
the new Parser.

some

public final Parser<Type[]> some(java.lang.String name,
                                 ArrayFactory<Type> af,
                                 int max)
Runs this for up to max times. The return values are collected and returned in an array created by af.

Parameters:
name - the name of the new parser.
af - the ArrayFactory object.
max - the maximal number of times to run.
Returns:
the new Parser.

many1

public final Parser<Type[]> many1(java.lang.Class<Type> elem_type)
p.many1(elem_type) is equivalent to p+ in EBNF. The return values are collected and returned in an array whose element type is elem_type.

Parameters:
elem_type - the element type of the result array.
Returns:
the new Parser.

many1

public final Parser<Type[]> many1(java.lang.String name,
                                  java.lang.Class<Type> elem_type)
p.many1(name, elem_type) is equivalent to p+ in EBNF. The return values are collected and returned in an array whose element type is elem_type.

Parameters:
name - the name of the new parser.
elem_type - the element type of the result array.
Returns:
the new Parser.

many1

public final Parser<Type[]> many1(ArrayFactory<Type> af)
p.many1(af) is equivalent to p+ in EBNF. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
af - the ArrayFactory.
Returns:
the new Parser.

many1

public final Parser<Type[]> many1(java.lang.String name,
                                  ArrayFactory<Type> af)
p.many1(name, af) is equivalent to p+ in EBNF. The return values are collected and returned in an array created by the ArrayFactory object.

Parameters:
name - the name of the new parser.
af - the ArrayFactory.
Returns:
the new Parser.

many1

public final Parser<_> many1()
p.many1() is equivalent to p+ in EBNF. The return values are discarded.

Returns:
the new Parser.

many1

public final Parser<_> many1(java.lang.String name)
p.many1(name) is equivalent to p+ in EBNF. The return values are discarded.

Parameters:
name - the name of the new parser.
Returns:
the new Parser.

optional

public final Parser<Type> optional()
p.optional() is equivalent to p? in EBNF. null is the result when p fails.

Returns:
the new Parser.

optional

public final Parser<Type> optional(java.lang.String name)
p.optional(name) is equivalent to p? in EBNF. null is the result when p fails.

Parameters:
name - the name of the new Parser.
Returns:
the new Parser.

option

public final Parser<Type> option(Type def)
If this fails with no input consumed, the default value is returned. p.option(name, def) = p | retn(def).

Parameters:
def - the default value.
Returns:
the new Parser.

option

public final Parser<Type> option(java.lang.String name,
                                 Type def)
If this fails with no input consumed, the default value is returned. p.option(name, def) = p | retn(def).

Parameters:
name - the name of the new Parser.
def - the default value.
Returns:
the new Parser.

not

public final Parser<?> not()
fails if 'this' succeeds. Input consumption is undone.

Returns:
the new Parser.

not

public final Parser<?> not(java.lang.String err)
fails if 'this' succeeds. Input consumption is undone.

Parameters:
err - the error message if fails.
Returns:
the new Parser.

not

public final Parser<?> not(java.lang.String name,
                           java.lang.String err)
fails if 'this' succeeds. Input consumption is undone.

Parameters:
name - the name of the new Parser.
err - the error message if fails.
Returns:
the new Parser.

peek

public final Parser<Type> peek()
this is a look-ahead operation. Succeed or not, the input consumption is undone.

Returns:
the new Parser.

peek

public final Parser<Type> peek(java.lang.String name)
this is a look-ahead operation. Succeed or not, the input consumption is undone.

Parameters:
name - the name of the new Parser
Returns:
the new Parser

map

public final <R> Parser<R> map(Map<? super Type,R> m)
if this succeeds, the returned value is transformed with m to a new return value.

Parameters:
m - the map object to transform return value.
Returns:
the new Parser.

map

public final <R> Parser<R> map(java.lang.String name,
                               Map<? super Type,R> m)
if this succeeds, the returned value is transformed with m to a new return value.

Parameters:
name - the name of the new Parser.
m - the map object to transform return value.
Returns:
the new Parser.

and

public final <T,R> Parser<R> and(Parser<T> p,
                                 Map2<? super Type,? super T,R> m)
it sequentially run this and p, and then transforms the two return values with m to a new return value.

Parameters:
p - the next parser to run.
m - the transformation.
Returns:
the new Parser object.

and

public final <T,R> Parser<R> and(java.lang.String name,
                                 Parser<T> p,
                                 Map2<? super Type,? super T,R> m)
it sequentially run this and p, and then transforms the two return values with m to a new return value.

Parameters:
name - the name of the new parser.
p - the next parser to run.
m - the transformation.
Returns:
the new Parser object.

followedBy

public final Parser<Type> followedBy(Parser<?> sep)
'this' and 'sep' are executed sequentially. The return value of 'this' is returned.

Parameters:
sep - the following parser.
Returns:
the new Parser.

followedBy

public final Parser<Type> followedBy(java.lang.String name,
                                     Parser<?> sep)
'this' and 'sep' are executed sequentially. The return value of 'this' is returned.

Parameters:
name - the name of the new Parser.
sep - the following parser.
Returns:
the new Parser.

atomize

public final Parser<Type> atomize(java.lang.String name)
Make sure 'this' is atomic. When fails, no input is consumed. For lookahead, a successful atomized operation is considered at most one logical step.

Parameters:
name - the name of the new Parser.
Returns:
the new Parser.

atomize

public final Parser<Type> atomize()
Make sure 'this' is atomic. When fails, no input is consumed. For lookahead, a successful atomized operation is considered at most one logical step.

Returns:
the new Parser.

ifelse

public final <R> Parser ifelse(Parser<R> yes,
                               Parser<? extends R> no)
run yes if this succeeds, no if this fails without consuming input; fails otherwise.

Parameters:
yes - the true branch.
no - the false branch.
Returns:
the new Parser object.

ifelse

public final <R> Parser<R> ifelse(java.lang.String name,
                                  Parser<R> yes,
                                  Parser<R> no)
run yes if this succeeds, no if this fails without consuming input; fails otherwise.

Parameters:
name - the name of the new Parser object.
yes - the true branch.
no - the false branch.
Returns:
the new Parser object.

ifelse

public final <R> Parser<R> ifelse(ToParser<? super Type,R> yes,
                                  Parser<R> no)
run yes if this succeeds, no if this fails without consuming input; fails otherwise.

Parameters:
yes - the true branch.
no - the false branch.
Returns:
the new Parser object.

ifelse

public final <R> Parser<R> ifelse(java.lang.String name,
                                  ToParser<? super Type,R> yes,
                                  Parser<R> no)
run yes if this succeeds, no if this fails without consuming input; fails otherwise.

Parameters:
name - the name of the new Parser object.
yes - the true branch.
no - the false branch.
Returns:
the new Parser object.

lookahead

public final Parser<Type> lookahead(java.lang.String name,
                                    int toknum)
By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed and consumed some input. this is because the default look-ahead token is 1.
by using lookahead, this default behavior can be altered. Parsers.plus(p1, p2).lookahead(3) will still try p2 even if p1 fails and consumes one or two inputs.

lookahead only affects one nesting level. Parsers.plus(p1,p2).ifelse(yes,no).lookahead(3) will not affect the Parsers.plus(p1,p2) nested within ifelse.

lookahead directly on top of lookahead will override the previous lookahead. Parsers.plus(p1,p2).lookahead(3).lookahead(1) is equivalent as Parsers.plus(p1, p2).lookahead(1).
lookahead looks at logical step. by default, each terminal is one logical step. atomize() combinator ensures at most 1 logical step for a parser. Use step() combinator to fine control logical steps.

Parameters:
name - the name of the new Parser object.
toknum - the number of tokens to look ahead.
Returns:
the new Parser object.

lookahead

public final Parser<Type> lookahead(int toknum)
By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed and consumed some input. this is because the default look-ahead token is 1.
by using lookahead, this default behavior can be altered. Parsers.plus(p1, p2).lookahead(3) will still try p2 even if p1 fails and consumes one or two inputs.

lookahead only affects one nesting level. Parsers.plus(p1,p2).ifelse(yes,no).lookahead(3) will not affect the Parsers.plus(p1,p2) nested within ifelse.

lookahead directly on top of lookahead will override the previous lookahead. Parsers.plus(p1,p2).lookahead(3).lookahead(1) is equivalent as Parsers.plus(p1, p2).lookahead(1).
lookahead looks at logical step. by default, each terminal is one logical step. atomize() combinator ensures at most 1 logical step for a parser. Use step() combinator to fine control logical steps.

Parameters:
toknum - the number of tokens to look ahead.
Returns:
the new Parser object.

label

public final Parser<Type> label(java.lang.String lbl)
if fails and did not consume input, reports an expecting error with the given label.

Parameters:
lbl - the label text.
Returns:
the new Parser object.

label

public final Parser<Type> label(java.lang.String name,
                                java.lang.String lbl)
if fails and did not consume input, reports an expecting error with the given label.

Parameters:
name - the name of the new Parser object.
lbl - the label text.
Returns:
the new Parser object.

isReturn

public final Parser<Type> isReturn(java.lang.String name,
                                   ObjectPredicate<? super Type> op)
Fails if the return value of this parser does not satisify the given predicate. No-op otherwise.

Parameters:
name - the name of the new Parser object.
op - the predicate object.
Returns:
the new Parser object.

isReturn

public final Parser<Type> isReturn(ObjectPredicate<? super Type> op)
Fails if the return value of this parser does not satisify the given predicate. No-op otherwise.

Parameters:
op - the predicate object.
Returns:
the new Parser object.

isReturn

public final Parser<Type> isReturn(java.lang.String name,
                                   ObjectPredicate<? super Type> op,
                                   java.lang.String expecting)
Fails if the return value of this parser does not satisify the given predicate. No-op otherwise. When fails, an "expecting" error will be generated.

Parameters:
name - the name of the new Parser object.
op - the predicate object.
expecting - the expected string.
Returns:
the new Parser object.

isReturn

public final Parser<Type> isReturn(ObjectPredicate<? super Type> op,
                                   java.lang.String expecting)
Fails if the return value of this parser does not satisify the given predicate. No-op otherwise. When fails, an "expecting" error will be generated.

Parameters:
op - the predicate object.
expecting - the expected string.
Returns:
the new Parser object.

step

public final Parser<Type> step(java.lang.String name,
                               int n)
lookahead looks at logical steps. step(int) runs this parser and sets the number of logical steps.

Parameters:
name - the name of the new Parser object.
n - the number logical steps. n>=0 has to be true.
Returns:
the new Parser object.

step

public final Parser<Type> step(java.lang.String name)
lookahead looks at logical steps. step() runs this parser and sets 1 logical step.

Parameters:
name - the name of the new Parser object.
Returns:
the new Parser object.

step

public final Parser<Type> step(int n)
lookahead looks at logical steps. step(int) runs this parser and sets the number of logical steps.

Parameters:
n - the number logical steps. n>=0 has to be true.
Returns:
the new Parser object.

step

public final Parser<Type> step()
lookahead looks at logical steps. step() runs this parser and sets 1 logical step.

Returns:
the new Parser object.

cast

public final <R extends Type> Parser<R> cast()
To cast the current Parser to a Parser object that returns a subtype of the current type.

Type Parameters:
R - the target return type.
Returns:
the Parser object that returns the expected type.
Since:
version 1.0

cast

public final <R extends Type> Parser<R> cast(java.lang.Class<R> type)
To cast the current Parser to a Parser object that returns a subtype of the current type.

Type Parameters:
R - the target return type.
Parameters:
type - the class literal for the target type.
Returns:
the Parser object that returns the expected type.
Since:
version 1.0

convert

public final <R> Parser<R> convert()
To convert the current Parser to a Parser object that returns any target type.

Type Parameters:
R - the target return type.
Returns:
the Parser object that returns the expected type.
Since:
version 1.0

convert

public final <R> Parser<R> convert(java.lang.Class<R> type)
To convert the current Parser to a Parser object that returns any target type.

Type Parameters:
R - the target return type.
Parameters:
type - the class literal for the target type.
Returns:
the Parser object that returns the expected type.
Since:
version 1.0

parse

public final Type parse(java.lang.CharSequence source,
                        java.lang.String moduleName)
To parse a source string.

Parameters:
source - the source string.
moduleName - the name of the module, this name appears in error message.
Returns:
the result.
Since:
v1.2

parse

public final Type parse(java.lang.CharSequence source)
To parse a source string.

Parameters:
source - the source string.
Returns:
the result.
Since:
v1.2