Parsers


1   /*****************************************************************************
2    * Copyright (C) Zephyr Business Solutions Corp. All rights reserved.            *
3    * ------------------------------------------------------------------------- *
4    * The software in this package is published under the terms of the BSD      *
5    * style license a copy of which has been included with this distribution in *
6    * the LICENSE.txt file.                                                     *
7    *****************************************************************************/
8   /*
9    * Created on 2004-11-11
10   *
11   * Author Ben Yu
12   */
13  package jfun.parsec;
14  
15  
16  /**
17   * <p>
18   * This class provides general parser combinators that work on both character
19   * level and token level.
20   * </p>
21   * <p>
22   * A parser can work on character level or token level.
23   * <ul>
24   * <li>A character level parser that returns a token object is called a lexer.
25   * </li>
26   * <li>A character level parser that does not return a token object is called a
27   * scanner. </li>
28   * </ul>
29   * A token level parser is called a "parser".
30   * </p>
31   * <p>
32   * For each Parser combinator, we write the signature in a haskellish sytax.
33   * <ul>
34   * <li>A parser that returns an object of type a is denoted as: Parser a. </li>
35   * <li>A value of any type is denoted as * (null is an example, exceptions,
36   * errors are all type *). We use the lower case "x", "y", "z" variables as type parameter for such cases.</li>
37   * <li>A no-value type is denoted as _. </li>
38   * <li>An unknown type is denoted as ?. </li>
39   * <li>A parser transformer that maps a Parser a to Parser b is denoted as:
40   * Parser a -> Parser b. </li>
41   * <li>A parser combinator that accepts object of type a and returns a Parser b
42   * is denoted as: a -> Parser b. </li>
43   * <li>Interface Map is denoted as a -> b. this is because Map will be changed
44   * to Map<A,B> once we have generics. </li>
45   * <li>Map2 is denoted as a->b->r, Map3 is a->b->c->r, etc. </li>
46   * <li>ToParser is denoted as a -> Parser b. </li>
47   * </ul>
48   * </p>
49   * <p>
50   * A Parser object is safely covariant about the type parameter. Jparsec
51   * tries its best to support covariance in the API since java 5 generics has no covariance support.
52   * It is always safe to use the convert() method to explicitly force covariance whenever necessary.
53   * </p>
54   * <p>
55   * A parser has a user state that can be set and retrieved. Only setState,
56   * getState, transformState combinators are user state related.
57   * </p>
58   * <p>
59   * We denote a user state concerned parser as Parser u a, where u is the user
60   * state type and a is the return type.
61   * </p>
62   * <p>
63   * An array of element type t, is denoted as [t].
64   * </p>
65   * 
66   * @author Ben Yu
67   * 
68   * 2004-11-11
69   */
70  public final class Parsers {
71    private static boolean debugged = true;
72    /**
73     * Is debugging enabled?
74     * @since version 1.1
75     */
76    public synchronized static boolean isDebugEnabled() {
77      return debugged;
78    }
79    /**
80     * enable or disable debugging.
81     * @param debugged true if debugging is enabled, false otherwise.
82     * @since version 1.1
83     */
84    public synchronized static void setDebug(boolean debugged) {
85      Parsers.debugged = debugged;
86    }
87    /**
88     * Runs a character level parser with a CharSequence input.
89     * 
90     * @param src
91     *          the input source.
92     * @param p
93     *          the parser object to run.
94     * @param pmap
95     *          the PositionMap object used to map a character index to
96     *          line/column number.
97     * @param module
98     *          the module name. Use any name that's meaningful.
99     * @return the result object.
100    */
101   public static <R> R runParser(final CharSequence   src, final Parser<R> p,
102       final PositionMap pmap, final String   module) {
103     final ScannerState ctxt = new ScannerState(src, 0, module, pmap, null);
104     return ParserInternals.runParser(ctxt, p, pmap);
105   }
106 
107   /**
108    * Runs a character level parser with a CharSequence input.
109    * The {@link Parser#parse(CharSequence, String)} is equivalent
110    * to this call and is more convenient.
111    * @param src the input source.
112    * @param p the parser object to run.
113    * @param module the module name. This name apears in error message.
114    * @return the result object.
115    */
116   public static <R> R runParser(final CharSequence   src, final Parser<R> p,
117       final String   module) {
118     return runParser(src, p, new DefaultPositionMap(src, 1, 1), module);
119   }
120 
121   /**
122    * Runs a token level Parser object with an array of tokens.
123    * <p>
124    * [Tok] -> int -> Parser a -> ShowToken -> String -> PositionMap ->
125    * a
126    * 
127    * @param toks
128    *          the input tokens
129    * @param end_index
130    *          the index after the last character in the source.
131    * @param p
132    *          the parser object.
133    * @param show
134    *          the object to show the tokens.
135    * @param eof_title
136    *          the name of "end of file".
137    * @param module
138    *          the module name. Use any name that's meaningful. This value will
139    *          be shown in any EOF related messages.
140    * @param pmap
141    *          the PositionMap object to map a character index to the line/column
142    *          number.
143    * @return the return value of the Parser object. (returned by retn()
144    *         function)
145    * @throws ParserException
146    *           when parsing fails.
147    */
148   public static <R> R runParser(final Tok[] toks,
149       final int end_index, final Parser<R> p, final ShowToken show,
150       final String   eof_title, final PositionMap pmap, final String   module)
151       throws ParserException {
152     final ParserState s0 = new ParserState(null, toks, 0, module, pmap,
153         end_index, eof_title, show);
154     return ParserInternals.runParser(s0, p, pmap);
155   }
156 
157   /**
158    * To create a Parser that always succeeds and causes a certain side effect
159    * using a Runnable object.
160    * 
161    * @param name
162    *          the parser name.
163    * @param runnable
164    *          the Runnable object.
165    * @return the Parser object.
166    */
167   public static Parser<?> runnable(String   name, Runnable   runnable) {
168     return new ActionParser(name, runnable);
169   }
170 
171   /**
172    * To create a Parser that always succeeds and causes a certain side effect
173    * using a Runnable object.
174    * 
175    * @param runnable
176    *          the Runnable object.
177    * @return the Parser object.
178    */
179   public static Parser<?> runnable(Runnable   runnable) {
180     return runnable("runnable", runnable);
181   }
182 
183   /**
184    * The created parser object will take as input the array of Tok
185    * returned from the lexer object, feed it into the Parser object p and run
186    * it, return the result from parser p. <br>
187    * It fails if the lexer fails or parser p fails. 
188    * Parser [Tok] -> Parser a -> Parser a
189    * 
190    * @param lexer
191    *          the lexer object that returns an array of Tok objects.
192    * @param p
193    *          the token level parser object.
194    * @param module
195    *          the module name. Use any name that's meaningful. that will parse
196    *          the array of Tok objects.
197    * @return the new Parser object.
198    */
199   public static <R> Parser<R> parseTokens(
200       final Parser<Tok[]> lexer, final Parser<R> p,
201       final String   module) {
202     return parseTokens("parseTokens", lexer, p, module);
203   }
204 
205   /**
206    * The created parser object will take as input the array of Tok
207    * returned from the lexer object, feed it into the Parser object p and run
208    * it, return the result from parser p. <br>
209    * It fails if the lexer fails or parser p fails. 
210    * Parser [Tok] -> Parser a -> Parser a
211    * 
212    * @param name
213    *          the name of the new Parser object.
214    * @param lexer
215    *          the lexer object that returns an array of Tok objects.
216    * @param p
217    *          the token level parser object.
218    * @param module
219    *          the module name. Use any name that's meaningful. that will parse
220    *          the array of Tok objects.
221    * @return the new Parser object.
222    */
223   public static <R> Parser<R> parseTokens(final String   name,
224       final Parser<Tok[]> lexer, final Parser<R> p,
225       final String   module) {
226     return parseTokens(name, "EOF", Token2String.instance(), lexer, p, module);
227   }
228 
229   /**
230    * The created parser object will take as input the array of Tok
231    * returned from the lexer object, feed it into the Parser object p and run
232    * it, return the result from parser p. <br>
233    * It fails if the lexer fails or parser p fails. String -> ShowToken ->
234    * Parser [Tok] -> Parser a -> Parser a
235    * 
236    * @param eof_title
237    *          the name of "end of input"
238    * @param show
239    *          the object to transform a token to a string.
240    * @param lexer
241    *          the lexer object that returns an array of Tok objects.
242    * @param p
243    *          the token level parser object.
244    * @param module
245    *          the module name. Use any name that's meaningful. that will parse
246    *          the array of Tok objects.
247    * @return the new Parser object.
248    */
249   public static <R> Parser<R> parseTokens(final String   eof_title,
250       final ShowToken show,
251       final Parser<Tok[]> lexer, final Parser<R> p, String   module) {
252     return parseTokens("parseTokens", eof_title, show, lexer, p, module);
253   }
254 
255   /**
256    * The created parser object will take as input the array of Tok
257    * returned from the lexer object, feed it into the Parser object p and run
258    * it, return the result from parser p. <br>
259    * It fails if the lexer fails or parser p fails. String -> ShowToken ->
260    * Parser [Tok] -> Parser a -> Parser a
261    * 
262    * @param name
263    *          the name of the new Parser object.
264    * @param eof_title
265    *          the name of "end of input"
266    * @param show
267    *          the object to transform a token to a string.
268    * @param lexer
269    *          the lexer object that returns an array of Tok objects.
270    * @param p
271    *          the token level parser object
272    * @param module
273    *          the module name. Use any name that's meaningful. that will parse
274    *          the array of Tok objects.
275    * @return the new Parser object.
276    */
277   public static <R> Parser<R> parseTokens(final String   name,
278       final String   eof_title, final ShowToken show,
279       final Parser<Tok[]> lexer, final Parser<R> p,
280       final String   module) {
281     return new NestedParser<R>(name, show, module, lexer, p, eof_title);
282   }
283 
284   /** ****************** monadic combinators ******************* */
285   private static final Parser<?> _one = one("one");
286 
287   /**
288    * The parser that always succeed. It does not consume any input.
289    * <p>
290    * Parser ?
291    * @return the Parser object.
292    */
293   public static Parser<?> one() {
294     return _one;
295   }
296 
297   /**
298    * The parser that always succeed. It does not consume any input.
299    * <p>
300    * Parser ?
301    * @param name
302    *          the name of the Parser.
303    * @return the Parser object.
304    */
305   public static Parser<?> one(final String   name) {
306     return new OneParser(name);
307   }
308 
309   private static final Parser _zero = zero("zero");
310 
311   /**
312    * The parser that always fails. It does not consume any input.
313    * <p>
314    * Parser *
315    * 
316    * @return the Parser object.
317    */
318   public static <x> Parser<x> zero() {
319     return _zero;
320   }
321 
322   /**
323    * The parser that always fails. It does not consume any input.
324    * <p>
325    * Parser *
326    * 
327    * @param name
328    *          the name of the Parser.
329    * @return the Parser object.
330    */
331   public static <x> Parser<x> zero(final String   name) {
332     return new ZeroParser<x>(name);
333   }
334 
335   /**
336    * The parser that returns value v. It does not consume any input.
337    * <p>
338    * a -> Parser a
339    * @param r the value to be returned by the parser.
340    * @return the Parser object.
341    */
342   public static <R> Parser<R> retn(final R r) {
343     return retn("return", r);
344   }
345 
346   /**
347    * The parser that returns value v. It does not consume any input.
348    * <p>
349    * a -> Parser a
350    * 
351    * @param name the name of the Parser.
352    * @param r the value to be returned by the parser.
353    * @return the Parser object.
354    */
355   public static <R> Parser<R> retn(final String   name, final R r) {
356     return new ReturnParser<R>(name, r);
357   }
358 
359   /**
360    * First run p, if it succeeds, run ToParser f with the value returned from p.
361    * <p>
362    * Parser a -> (a->Parser b) -> Parser b
363    * 
364    * @param name
365    *          the name of the Parser.
366    * @param p
367    *          the first Parser object.
368    * @param f
369    *          the ToParser object to run if the first succeeds.
370    * @return the Parser object.
371    */
372   public static <From, To> Parser<To> bind(final String   name,
373       final Parser<From> p, final ToParser<? super From, To> f) {
374     return new Parser<To>(name) {
375       boolean apply(final ParseContext ctxt) {
376         if (!p.parse(ctxt))
377           return false;
378         return runNext(ctxt, f);
379       }
380     };
381   }
382 
383   private static final ToParser _toReturn = toReturn("return");
384 
385   /**
386    * Returns a ToParser instance that simply returns the previous return value.
387    * <p>
388    * a -> Parser a
389    * 
390    * @return The ToParser object.
391    */
392   public static <T> ToParser<T, T> toReturn() {
393     return _toReturn;
394   }
395 
396   /**
397    * Returns a ToParser instance that simply returns the previous return value.
398    * <p>
399    * a -> Parser a
400    * 
401    * @return The ToParser object.
402    */
403   public static <T> ToParser<T, T> toReturn(final String   name) {
404     return new ToReturn<T>(name);
405   }
406 
407   private static final ToParser _toOne = toParser(one());
408 
409   /**
410    * Returns a ToParser that ignores the value passed in and simply returns
411    * one().
412    * <p> x -> Parser ?
413    * 
414    * @return the ToParser object.
415    */
416   public static <x> ToParser<x, ?> toOne() {
417     return _toOne;
418   }
419 
420   /**
421    * Returns a ToParser that ignores the value passed in and simply returns
422    * one().
423    * <p> x -> Parser ?
424    * 
425    * @param name the name of the Parser that ToParser returns.
426    * @return the ToParser object.
427    */
428   public static <x> ToParser<x, ?> toOne(final String   name) {
429     Parser<?> p = one(name);
430     return toParser(p);
431   }
432 
433   private static final ToParser _toZero = toParser(zero());
434 
435   /**
436    * Returns a ToParser that ignores the value passed in and simply returns
437    * zero().
438    * <p> _ -> Parser *
439    * 
440    * @return the ToParser object.
441    */
442   public static <x, y> ToParser<x, y> toZero() {
443     return _toZero;
444   }
445 
446   /**
447    * Returns a ToParser that ignores the value passed in and simply returns
448    * zero().
449    * <p> _ -> Parser *
450    * 
451    * @param name the name of the Parser that ToParser returns.
452    * @return the ToParser object.
453    */
454   public static <x, y> ToParser<x, y> toZero(final String   name) {
455     Parser<y> p = zero(name);
456     return toParser(p);
457   }
458   
459   /**
460    * Creates a ToParser object by always returning the same Parser object.
461    * @param <x> the type of the input parameter. "x" is used to indicate that this type is irrelevant and we don't use it.
462    * @param <R> the result type of the Parser object.
463    * @param parser the parser object.
464    * @return the ToParser object.
465    * @since version 0.4.1
466    */
467   public static <x, R> ToParser<x, R> toParser(final Parser<R> parser){
468     return new ToParser<x, R>() {
469       public Parser<R> toParser(final x v) {
470         return parser;
471       }
472     };
473   }
474   /**
475    * Threads an array of ToParser into a single ToParser. The first return value
476    * is passed to the first ToParser, and the result Parser is executed to get
477    * the next return value. The return value keeps pass down until all ToParser
478    * are called. If any Parser fails, the threading fails.
479    * <p>
480    * [(a->Parser a)] -> a -> Parser a
481    * 
482    * @param binders all the ToParser objects.
483    * @return the new ToParser.
484    */
485   public static <T> ToParser<T, T> bindAll(final ToParser<T, T>... binders) {
486     return bindAll("bindAll", binders);
487   }
488 
489   /**
490    * Threads an array of ToParser into a single ToParser. The first return value
491    * is passed to the first ToParser, and the result Parser is executed to get
492    * the next return value. The return value keeps pass down until all ToParser
493    * are called. If any Parser fails, the threading fails.
494    * <p>
495    * [(a->Parser a)] -> a -> Parser a
496    * 
497    * @param binders all the ToParser objects.
498    * @param name the name of the Parser created by the result ToParser.
499    * @return the new ToParser.
500    */
501   public static <T> ToParser<T, T> bindAll(final String   name,
502       final ToParser<T, T>... binders) {
503     if (binders.length == 0)
504       return toReturn();
505     if (binders.length == 1)
506       return binders[0];
507     return new AllBinders<T>(name, binders);
508   }
509 
510   /**
511    * Sequencing 2 parser objects. The first Parser is executed, if it succeeds,
512    * the second Parser is executed.
513    * <p>
514    * Parser ? -> Parser b -> Parser b
515    * 
516    * @param p1 1st Parser.
517    * @param p2 2nd Parser.
518    * @return the new Parser.
519    */
520   public static <R> Parser<R> seq(final Parser<?> p1, final Parser<R> p2) {
521     return seq(">>", p1, p2);
522   }
523 
524   /**
525    * Sequencing 2 parser objects. The first Parser is executed, if it succeeds,
526    * the second Parser is executed.
527    * <p>
528    * Parser ? -> Parser b -> Parser b
529    * 
530    * @param name the name of the new Parser object.
531    * @param p1 1st Parser.
532    * @param p2 2nd Parser.
533    * @return the new Parser.
534    */
535   public static <R> Parser<R> seq(final String   name, final Parser<?> p1,
536       final Parser<R> p2) {
537     // return _seqAll(name, new Parser[]{p1, p2});
538     // optimize. inline _seqAll to avoid creating array object.
539     return new SeqParser<R>(name, p1, p2);
540   }
541 
542   /**
543    * Sequencing 3 parser objects.
544    * <p>
545    * Parser a -> Parser b -> Parser c -> Parser c
546    * 
547    * @param p1 1st Parser.
548    * @param p2 2nd Parser.
549    * @param p3 3rd Parser.
550    * @return the new Parser.
551    */
552   public static <R> Parser<R> seq(final Parser<?> p1, final Parser<?> p2,
553       final Parser<R> p3) {
554     return seq(">>", p1, p2, p3);
555   }
556 
557   /**
558    * Sequencing 3 parser objects.
559    * <p>
560    * Parser a -> Parser b -> Parser c -> Parser c
561    * 
562    * @param name the name of the new Parser object.
563    * @param p1 1st Parser.
564    * @param p2 2nd Parser.
565    * @param p3 3rd Parser.
566    * @return the new Parser.
567    */
568   public static <R> Parser<R> seq(final String   name, final Parser<?> p1,
569       final Parser<?> p2, final Parser<R> p3) {
570     return new Seq3Parser<R>(name, p3, p1, p2);
571   }
572 
573   /**
574    * Sequencing 4 parser objects.
575    * <p>
576    * Parser a -> Parser b -> Parser c -> Parser c -> Parser d -> Parser d
577    * 
578    * @param p1 1st Parser.
579    * @param p2 2nd Parser.
580    * @param p3 3rd Parser.
581    * @param p4 4th Parser.
582    * @return the new Parser.
583    */
584   public static <R> Parser<R> seq(final Parser<?> p1, final Parser<?> p2,
585       final Parser<?> p3, final Parser<R> p4) {
586     return seq(">>", p1, p2, p3, p4);
587   }
588 
589   /**
590    * Sequencing 4 parser objects.
591    * <p>
592    * Parser a -> Parser b -> Parser c -> Parser c -> Parser d -> Parser d
593    * 
594    * @param name the name of the new Parser object.
595    * @param p1 1st Parser.
596    * @param p2 2nd Parser.
597    * @param p3 3rd Parser.
598    * @param p4 4th Parser.
599    * @return the new Parser.
600    */
601   public static <R> Parser<R> seq(final String   name, final Parser<?> p1,
602       final Parser<?> p2, final Parser<?> p3, final Parser<R> p4) {
603     return new Seq4Parser<R>(name, p4, p1, p2, p3);
604   }
605 
606   /**
607    * Sequencing 5 parser objects.
608    * <p>
609    * Parser a -> Parser b -> Parser c -> Parser c -> Parser d -> Parser e -> Parser e
610    * 
611    * @param p1 1st Parser.
612    * @param p2 2nd Parser.
613    * @param p3 3rd Parser.
614    * @param p4 4th Parser.
615    * @param p5 5th Parser.
616    * @return the new Parser.
617    */
618   public static <R> Parser<R> seq(final Parser<?> p1, final Parser<?> p2,
619       final Parser<?> p3, final Parser<?> p4, final Parser<R> p5) {
620     return seq(">>", p1, p2, p3, p4, p5);
621   }
622 
623   /**
624    * Sequencing 5 parser objects.
625    * <p>
626    * Parser a -> Parser b -> Parser c -> Parser c -> Parser d -> Parser e -> Parser e
627    * 
628    * @param name the name of the new Parser object.
629    * @param p1 1st Parser.
630    * @param p2 2nd Parser.
631    * @param p3 3rd Parser.
632    * @param p4 4th Parser.
633    * @param p5 5th Parser.
634    * @return the new Parser.
635    */
636   public static <R> Parser<R> seq(final String   name, final Parser<?> p1,
637       final Parser<?> p2, final Parser<?> p3, final Parser<?> p4,
638       final Parser<R> p5) {
639     return new Seq5Parser<R>(name, p1, p3, p5, p4, p2);
640   }
641 
642   /**
643    * Sequentially run 2 parser objects and collect the results in a Pair object.
644    * @param p1 the first parser.
645    * @param p2 the second parser.
646    * @return the result parser.
647    */
648   public static <A,B> Parser<Pair<A,B>> pair(Parser<A> p1, Parser<B> p2){
649     return pair("pair", p1, p2);
650   }
651   /**
652    * Sequentially run 3 parser objects and collect the results in a Tuple3 object.
653    * @param p1 the first parser.
654    * @param p2 the second parser.
655    * @param p3 the 3rd parser.
656    * @return the result parser
657    */
658   public static <A,B,C> Parser<Tuple3<A,B,C>> tuple(Parser<A> p1, Parser<B> p2, Parser<C> p3){
659     return tuple("tuple3", p1, p2, p3);
660   }
661   /**
662    * Sequentially run 4 parser objects and collect the results in a Tuple4 object.
663    * @param p1 the first parser.
664    * @param p2 the second parser.
665    * @param p3 the 3rd parser.
666    * @param p4 the 4th parser.
667    * @return the result parser
668    */
669   public static <A,B,C,D> Parser<Tuple4<A,B,C,D>> tuple(
670       Parser<A> p1, Parser<B> p2, Parser<C> p3, Parser<D> p4){
671     return tuple("tuple4", p1, p2, p3, p4);
672   }
673   /**
674    * Sequentially run 5 parser objects and collect the results in a Tuple5 object.
675    * @param p1 the first parser.
676    * @param p2 the second parser.
677    * @param p3 the 3rd parser.
678    * @param p4 the 4th parser.
679    * @param p5 the 5th parser.
680    * @return the result parser
681    */
682   public static <A,B,C,D,E> Parser<Tuple5<A,B,C,D,E>> tuple(
683       Parser<A> p1, Parser<B> p2, Parser<C> p3, Parser<D> p4, Parser<E> p5){
684     return tuple("tuple5", p1, p2, p3, p4, p5);
685   }
686   /**
687    * Sequentially run 2 parser objects and collect the results in a Pair object.
688    * @param name the result parser name.
689    * @param p1 the first parser.
690    * @param p2 the second parser.
691    * @return the result parser.
692    */
693   public static <A,B> Parser<Pair<A,B>> pair(String   name, Parser<A> p1, Parser<B> p2){
694     final Map2<A,B,Pair<A,B>> m2 = Maps.id2();
695     return map2(name, p1, p2, m2);
696   }
697   /**
698    * Sequentially run 3 parser objects and collect the results in a Tuple3 object.
699    * @param name the result parser name.
700    * @param p1 the first parser.
701    * @param p2 the second parser.
702    * @param p3 the 3rd parser.
703    * @return the result parser
704    */
705   public static <A,B,C> Parser<Tuple3<A,B,C>> tuple(String   name,
706       Parser<A> p1, Parser<B> p2, Parser<C> p3){
707     final Map3<A,B,C,Tuple3<A,B,C>> m3 = Maps.id3();
708     return map3(name, p1, p2, p3, m3);
709   }
710   /**
711    * Sequentially run 4 parser objects and collect the results in a Tuple4 object.
712    * @param name the result parser name.
713    * @param p1 the first parser.
714    * @param p2 the second parser.
715    * @param p3 the 3rd parser.
716    * @param p4 the 4th parser.
717    * @return the result parser
718    */
719   public static <A,B,C,D> Parser<Tuple4<A,B,C,D>> tuple(String   name,
720       Parser<A> p1, Parser<B> p2, Parser<C> p3, Parser<D> p4){
721     final Map4<A,B,C,D,Tuple4<A,B,C,D>> m4 = Maps.id4();
722     return map4(name, p1, p2, p3, p4, m4);
723   }
724   /**
725    * Sequentially run 5 parser objects and collect the results in a Tuple5 object.
726    * @param name the result parser name.
727    * @param p1 the first parser.
728    * @param p2 the second parser.
729    * @param p3 the 3rd parser.
730    * @param p4 the 4th parser.
731    * @param p5 the 5th parser.
732    * @return the result parser
733    */
734   public static <A,B,C,D,E> Parser<Tuple5<A,B,C,D,E>> tuple(String   name,
735       Parser<A> p1, Parser<B> p2, Parser<C> p3, Parser<D> p4, Parser<E> p5){
736     final Map5<A,B,C,D,E,Tuple5<A,B,C,D,E>> m5 = Maps.id5();
737     return map5(name, p1, p2, p3, p4, p5, m5);
738   }
739   /**
740    * Sequencing of an array of Parser objects. If the array is empty, one() is
741    * returned. <br>
742    * The array of Parser objects are executed sequentially until an error
743    * occured or all the Parsers are executed. Return values are discarded.
744    * <p>
745    * [Parser ?] -> Parser ?
746    * 
747    * @param ps the array of Parser objects.
748    * @return the new Parser object.
749    * @since version 1.0
750    */
751   public static Parser<?> sequence(final Parser<?>... ps) {
752     return seqAll(ps);
753   }
754 
755   /**
756    * Sequencing of an array of Parser objects. If the array is empty, one() is
757    * returned. <br>
758    * The array of Parser objects are executed sequentially until an error
759    * occured or all the Parsers are executed. Return values are discarded.
760    * <p>
761    * [Parser ?] -> Parser ?
762    * 
763    * @param name the name of the new Parser.
764    * @param ps the array of Parser objects.
765    * @return the new Parser object.
766    * @since version 1.0
767    */
768   public static Parser<?> sequence(final String   name, final Parser<?>... ps) {
769     return seqAll(name, ps);
770   }
771 
772   /**
773    * Sequencing of an array of Parser objects. If the array is empty, one() is
774    * returned. <br>
775    * The array of Parser objects are executed sequentially until an error
776    * occured or all the Parsers are executed. Return values are discarded.
777    * <p>
778    * [Parser ?] -> Parser Object
779    * 
780    * @param ps
781    *          the array of Parser objects.
782    * @return the new Parser object.
783    */
784   public static Parser<Object  > seqAll(final Parser<?>[] ps) {
785     return seqAll("seqAll", ps);
786   }
787 
788   /**
789    * Sequencing of an array of Parser objects. If the array is empty, one() is
790    * returned. <br>
791    * The array of Parser objects are executed sequentially until an error
792    * occured or all the Parsers are executed. Return values are discarded.
793    * <p>
794    * [Parser ?] -> Parser Object
795    * 
796    * @param name
797    *          the name of the new Parser.
798    * @param ps
799    *          the array of Parser objects.
800    * @return the new Parser object.
801    */
802   public static Parser<Object  > seqAll(final String   name, final Parser<?>[] ps) {
803     if (ps.length == 0)
804       return one().convert();
805     if (ps.length == 1)
806       return ps[0].convert();
807     return _seqAll(name, ps);
808   }
809 
810   private static Parser<Object  > _seqAll(final String   name, final Parser<?>[] ps) {
811     return new SequenceParser(name, ps);
812   }
813 
814   /**
815    * Fails if the return value of the previous parser does not satisify the
816    * given predicate. No-op otherwise.
817    * 
818    * @param name
819    *          the name of the new Parser object.
820    * @param op
821    *          the predicate object.
822    * @return the new Parser object.
823    */
824   public static <R> Parser<R> isReturn(final String   name,
825       final ObjectPredicate<R> op) {
826     return new IsReturnParser<R>(name, op);
827   }
828 
829   /**
830    * The created Parser object will first run parser p, if the return value of
831    * parser p does not satisify the given predicate, it fails and the input
832    * consumption of parser p is undone. It is an atomic parser.
833    * 
834    * @param name
835    *          the name of the new Parser object.
836    * @param p
837    *          the parser object to test the return value of.
838    * @param op
839    *          the predicate object.
840    * @return the new Parser object.
841    */
842   public static <R> Parser<R> isReturn(final String   name, final Parser<R> p,
843       final ObjectPredicate<? super R> op) {
844     final Parser<R> p2 = isReturn(name, op).convert();
845     return seq(name, p, p2).atomize(name);
846   }
847 
848   /**
849    * The created Parser object will first run parser p, if the return value of
850    * parser p does not satisify the given predicate, it fails and the input
851    * consumption of parser p is undone. It is an atomic parser.
852    * 
853    * @param name
854    *          the name of the new Parser object.
855    * @param p
856    *          the parser object to test the return value of.
857    * @param op
858    *          the predicate object.
859    * @param expecting
860    *          the "expected" error message.
861    * @return the new Parser object.
862    */
863   public static <R> Parser<R> isReturn(final String   name, final Parser<R> p,
864       final ObjectPredicate<? super R> op, final String   expecting) {
865     final Parser<R> p2 = isReturn(name, op).convert();
866     return p.seq(name, p2.label(name, expecting)).atomize(name);
867   }
868 
869   /**
870    * Fails if the current user state value does not satisify the given
871    * predicate. No-op otherwise.
872    * 
873    * @param op
874    *          the predicate object.
875    * @return the new Parser object.
876    * @deprecated as of version 0.6
877    */
878   @Deprecated  
879   public static Parser<?> isState(final ObjectPredicate<Object  > op) {
880     return isState("isState", op);
881   }
882 
883   /**
884    * Fails if the current user state value does not satisify the given
885    * predicate. No-op otherwise.
886    * 
887    * @param name
888    *          the name of the new Parser object.
889    * @param op
890    *          the predicate object.
891    * @return the new Parser object.
892    * @deprecated as of version 0.6
893    */
894   @Deprecated  
895   public static Parser<?> isState(final String   name,
896       final ObjectPredicate<Object  > op) {
897     return new Parser<Object  >(name) {
898       boolean apply(final ParseContext ctxt) {
899         final Object   r = ctxt.getUserState();
900         return op.isObject(r);
901       }
902     };
903   }
904 
905   /**
906    * lookahead looks at logical steps. step(String, int, Parser) runs this
907    * parser and sets the number of logical steps.
908    * 
909    * @param name
910    *          the name of the new Parser object.
911    * @param n
912    *          the number logical steps. n>=0 has to be true.
913    * @param p
914    *          the Parser object.
915    * @return the new Parser object.
916    */
917   public static <R> Parser<R> step(final String   name, final int n,
918       final Parser<R> p) {
919     if (n < 0)
920       throw new IllegalArgumentException  ("" + n + "<0");
921     return new StepParser<R>(name, p, n);
922   }
923 
924   /**
925    * By default, ifelse, plus, sum will not try to run the next branch if the
926    * previous branch failed and consumed some input. this is because the default
927    * look-ahead token is 1. <br>
928    * by using lookahead, this default behavior can be altered. Parsers.plus(p1,
929    * p2).lookahead(3) will still try p2 even if p1 fails and consumes one or two
930    * inputs.
931    * <p>
932    * lookahead only affects one nesting level.
933    * Parsers.plus(p1,p2).ifelse(yes,no).lookahead(3) will not affect the
934    * Parsers.plus(p1,p2) nested within ifelse.
935    * <p>
936    * lookahead directly on top of lookahead will override the previous
937    * lookahead. Parsers.plus(p1,p2).lookahead(3).lookahead(1) is equivalent as
938    * Parsers.plus(p1, p2).lookahead(1). <br>
939    * lookahead looks at logical step. by default, each terminal is one logical
940    * step. atomize() combinator ensures at most 1 logical step for a parser. Use
941    * step() combinator to fine control logical steps.
942    * 
943    * @param name
944    *          the name of the new Parser object.
945    * @param toknum
946    *          the number of tokens to look ahead.
947    * @return the new Parser object.
948    */
949   public static <R> Parser<R> lookahead(final String   name, final int toknum,
950       final Parser<R> p) {
951     if (toknum <= 0)
952       return p;
953     return new LookaheadParser<R>(name, p, toknum);
954   }
955 
956   /**
957    * Sequencing of an array of Parser objects. The array of Parser objects are
958    * executed sequentially until an error occured or all the Parsers are
959    * executed. Return values are collected as a Object[] array and transformed
960    * by a Mapn object.
961    * <p>
962    * [Parser a] -> ([a]->r) -> Parser r
963    * 
964    * @param ps
965    *          the array of Parser objects.
966    * @param mn
967    *          the Mapn object.
968    * @return the new Parser object.
969    */
970   public static <R> Parser<R> mapn(final Parser<?>[] ps, final Mapn<R> mn) {
971     return mapn("mapn", ps, mn);
972   }
973 
974   /**
975    * Sequencing of an array of Parser objects. The array of Parser objects are
976    * executed sequentially until an error occured or all the Parsers are
977    * executed. Return values are collected and returned as an Object[] array and
978    * transformed by a Mapn object.
979    * <p>
980    * [Parser a] -> ([a]->r) -> Parser r
981    * 
982    * @param name
983    *          the name of the new Parser.
984    * @param ps
985    *          the array of Parser objects.
986    * @param mn
987    *          the Mapn object.
988    * @return the new Parser object.
989    */
990   public static <R> Parser<R> mapn(final String   name, final Parser<?>[] ps,
991       final Mapn<R> mn) {
992     if (ps.length == 0) {
993       final R r = mn.map(_empty_array);
994       return retn(r);
995     }
996     return mapn(name, ArrayFactories.defaultFactory(), ps, mn);
997   }
998 
999   /**
1000   * Sequencing of an array of Parser objects. The array of Parser objects are
1001   * executed sequentially until an error occured or all the Parsers are
1002   * executed. Return values are collected and returned as a T[] array where T
1003   * is the element type, and then transformed by a Mapn object.
1004   * <p>
1005   * [Parser a] -> ([a]->r) -> Parser r
1006   * 
1007   * @param etype
1008   *          the element type of the return value array.
1009   * @param ps
1010   *          the array of Parser objects.
1011   * @param mn
1012   *          the Mapn object.
1013   * @return the new Parser object.
1014   */
1015  public static <E, R> Parser<R> mapn(final Class  <? super E> etype,
1016      final Parser<E>[] ps, final Mapn<R> mn) {
1017    return mapn("mapn", etype, ps, mn);
1018  }
1019
1020  /**
1021   * Sequencing of an array of Parser objects. The array of Parser objects are
1022   * executed sequentially until an error occured or all the Parsers are
1023   * executed. Return values are collected and returned as a T[] array where T
1024   * is the element type, and then transformed by a Mapn object.
1025   * <p>
1026   * [Parser a] -> ([a]->r) -> Parser r
1027   * 
1028   * @param name
1029   *          the name of the new Parser.
1030   * @param etype
1031   *          the element type of the return value array.
1032   * @param ps
1033   *          the array of Parser objects.
1034   * @param mn
1035   *          the Mapn object.
1036   * @return the new Parser object.
1037   */
1038  public static <E, R> Parser<R> mapn(final String   name,
1039      final Class  <? super E> etype, final Parser<E>[] ps, final Mapn<R> mn) {
1040    return mapn(name, ArrayFactories.typedFactory(etype), ps, mn);
1041  }
1042
1043  /**
1044   * Sequencing of an array of Parser objects. The array of Parser objects are
1045   * executed sequentially until an error occured or all the Parsers are
1046   * executed. Return values are collected and returned as an array created by
1047   * the ArrayFactory parameter, and then transformed by a Mapn object.
1048   * <p>
1049   * [Parser a] -> ([a]->r) -> Parser r
1050   * 
1051   * @param af
1052   *          the ArrayFactory object.
1053   * @param ps
1054   *          the array of Parser objects.
1055   * @param mn
1056   *          the Mapn object.
1057   * @return the new Parser object.
1058   */
1059  public static <E, R> Parser<R> mapn(final ArrayFactory<?> af,
1060      final Parser<?>[] ps, final Mapn<R> mn) {
1061    return mapn("mapn", af, ps, mn);
1062  }
1063
1064  /**
1065   * Sequencing of an array of Parser objects. The array of Parser objects are
1066   * executed sequentially until an error occured or all the Parsers are
1067   * executed. Return values are collected and returned as an array created by
1068   * the ArrayFactory parameter and then transformed by a Mapn object.
1069   * <p>
1070   * [Parser a] -> ([a]->r) -> Parser r
1071   * 
1072   * @param name
1073   *          the name of the new Parser.
1074   * @param af
1075   *          the ArrayFactory object.
1076   * @param ps
1077   *          the array of Parser objects.
1078   * @param mn
1079   *          the Mapn object.
1080   * @return the new Parser object.
1081   */
1082  public static <R> Parser<R> mapn(final String   name,
1083      final ArrayFactory<?> af, final Parser<?>[] ps, final Mapn<R> mn) {
1084    return _mapn(name, af, ps, mn);
1085  }
1086
1087  private static <R> Parser<R> _mapn(final String   name,
1088      final ArrayFactory<?> af, final Parser<?>[] ps, final Mapn<R> mn) {
1089    return new MapnParser<R>(name, mn, af, ps);
1090  }
1091
1092  /**
1093   * A parser that always fail with the given error message.
1094   * <p>
1095   * Parser *
1096   * 
1097   * @param msg
1098   *          the error message.
1099   * @return the Parser object.
1100   */
1101  public static <R> Parser<R> fail(final String   msg) {
1102    return fail("fail", msg);
1103  }
1104
1105  /**
1106   * A parser that always fail with the given error message.
1107   * <p>
1108   * Parser *
1109   * 
1110   * @param name
1111   *          the Parser object name.
1112   * @param msg
1113   *          the error message.
1114   * @return the Parser object.
1115   */
1116  public static <R> Parser<R> fail(final String   name, final String   msg) {
1117    return new FailureParser<R>(name, msg);
1118  }
1119
1120  /**
1121   * First run Parser p, if it succeeds, thread the return value to ToParser
1122   * yes; if it fails and no input is consumed, run Parser no; fails if p fails
1123   * and some input is consumed.
1124   * <p>
1125   * Parser a -> (a->Parser b) -> Parser b -> Parser b
1126   * 
1127   * @param name
1128   *          the name of the new Parser object.
1129   * @param p
1130   *          the Parser object to test.
1131   * @param yes
1132   *          the true branch.
1133   * @param no
1134   *          the false branch.
1135   * @return the new Parser object.
1136   */
1137  public static <C, R> Parser<R> ifelse(final String   name, final Parser<C> p,
1138      final ToParser<? super C, R> yes, final Parser<? extends R> no) {
1139    return new IfElseParser<R, C>(name, no, p, yes);
1140  }
1141
1142  /**
1143   * First run Parser p, if it succeeds, run Parser yes; if it fails and no
1144   * input is consumed, run Parser no; fails if p fails and some input is
1145   * consumed.
1146   * <p>
1147   * Parser x -> Parser b -> Parser b -> Parser b
1148   * 
1149   * @param name
1150   *          the name of the new Parser object.
1151   * @param p
1152   *          the Parser object to test.
1153   * @param yes
1154   *          the true branch.
1155   * @param no
1156   *          the false branch.
1157   * @return the new Parser object.
1158   */
1159  public static <C, R> Parser<R> ifelse(final String   name, final Parser<C> p,
1160      final Parser<R> yes, final Parser<? extends R> no) {
1161    final ToParser<C, R> binder = toParser(yes);
1162    return ifelse(name, p, binder, no);
1163    /*
1164     * return new Parser(name){ boolean apply(final ParserState state){ final
1165     * Object ustate = state.getUserState(); final Object ret =
1166     * state.getReturn(); final int at = state.getAt(); final ParsecError error =
1167     * state.getError(); if(p.parse(state)) return yes.parse(state); return
1168     * recover(no, state, at, ret, ustate, error); } };
1169     */
1170  }
1171  /**
1172   * 2 alternative parser objects.
1173   * If the first Parser fails with no input consumption, the second one is executed.
1174   * <p>
1175   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1176   * </p>
1177   * <p> Parser a -> Parser a -> Parser a
1178   * @param p1 1st Parser.
1179   * @param p2 2nd Parser.
1180   * @return the new Parser.
1181   */
1182  public static <R> Parser<R> plus(final Parser<R> p1, final Parser<? extends R> p2){
1183    return plus("plus", p1, p2);
1184  }
1185  /**
1186   * 2 alternative parser objects.
1187   * If the first Parser fails with no input consumption, the second one is executed.
1188   * <p>
1189   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1190   * </p>
1191   * <p> Parser a -> Parser a -> Parser a
1192   * @param name the name of the new Parser object.
1193   * @param p1 1st Parser.
1194   * @param p2 2nd Parser.
1195   * @return the new Parser.
1196   */
1197  public static <R> Parser<R> plus(final String   name, final Parser<R> p1, final Parser<? extends R> p2){
1198    return plus(name, new Parser[]{p1, p2});
1199    //special optimize. inline _plusAll rather than creating the array object.
1200    /*
1201    return new Parser(name){
1202      boolean apply(final ParserState state){
1203        final Object ustate = state.getUserState();
1204        final Object ret = state.getReturn();
1205        final int at = state.getAt();
1206        final ParsecError error = state.getError();
1207        if(p1.parse(state)) return true;
1208        return recover(p2, state, at, ret, ustate, error);
1209      }
1210    };*/
1211  }
1212  /**
1213   * 3 alternative parser objects.
1214   * <p>
1215   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1216   * </p>
1217   * <p> Parser a -> Parser a -> Parser a -> Parser a
1218   * @param p1 1st Parser.
1219   * @param p2 2nd Parser.
1220   * @param p3 3rd Parser.
1221   * @return the new Parser.
1222   */
1223  public static <R> Parser<R> plus(final Parser<R> p1, 
1224      final Parser<? extends R> p2, final Parser<? extends R> p3){
1225    return plus("plus", p1, p2, p3);
1226  }
1227  /**
1228   * 3 alternative parser objects.
1229   * <p>
1230   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1231   * </p>
1232   * <p> Parser a -> Parser a -> Parser a -> Parser a
1233   * @param name the name of the new Parser object.
1234   * @param p1 1st Parser.
1235   * @param p2 2nd Parser.
1236   * @param p3 3rd Parser.
1237   * @return the new Parser.
1238   */
1239  public static <R> Parser<R> plus(final String   name, final Parser<R> p1, 
1240      final Parser<? extends R> p2, final Parser<? extends R> p3){
1241    return plus(name, new Parser[]{p1, p2, p3});
1242  }
1243  /**
1244   * 4 alternative parser objects.
1245   * <p>
1246   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1247   * </p>
1248   * <p> Parser a -> Parser a -> Parser a -> Parser a -> Parser a
1249   * @param p1 1st Parser.
1250   * @param p2 2nd Parser.
1251   * @param p3 3rd Parser.
1252   * @param p4 4th Parser.
1253   * @return the new Parser.
1254   */
1255  public static <R> Parser<R> plus(final Parser<R> p1, 
1256      final Parser<? extends R> p2, final Parser<? extends R> p3, final Parser<? extends R> p4){
1257    return plus("plus", p1, p2, p3, p4);
1258  }
1259  /**
1260   * 4 alternative parser objects.
1261   * <p>
1262   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1263   * </p>
1264   * <p> Parser a -> Parser a -> Parser a -> Parser a -> Parser a
1265   * @param name the name of the new Parser object.
1266   * @param p1 1st Parser.
1267   * @param p2 2nd Parser.
1268   * @param p3 3rd Parser.
1269   * @param p4 4th Parser.
1270   * @return the new Parser.
1271   */
1272  public static <R> Parser<R> plus(final String   name, final Parser<R> p1, final Parser<? extends R> p2, 
1273      final Parser<? extends R> p3, final Parser<? extends R> p4){
1274    return plus(name, new Parser[]{p1, p2, p3, p4});
1275  }
1276  /**
1277   * 5 alternative parser objects.
1278   * <p>
1279   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1280   * </p>
1281   * <p> Parser a -> Parser a -> Parser a -> Parser a -> Parser a -> Parser a
1282   * @param p1 1st Parser.
1283   * @param p2 2nd Parser.
1284   * @param p3 3rd Parser.
1285   * @param p4 4th Parser.
1286   * @param p5 5th Parser.
1287   * @return the new Parser.
1288   */
1289  public static <R> Parser<R> plus(final Parser<R> p1, final Parser<? extends R> p2, final Parser<? extends R> p3, 
1290      final Parser<? extends R> p4, final Parser<? extends R> p5){
1291    return plus("plus", p1, p2, p3, p4, p5);
1292  }
1293  /**
1294   * 5 alternative parser objects.
1295   * <p>
1296   * For backwward compatibility with java 1.4. Use the vararg version in java 5.
1297   * </p>
1298   * <p> Parser a -> Parser a -> Parser a -> Parser a -> Parser a -> Parser a
1299   * @param name the name of the new Parser object.
1300   * @param p1 1st Parser.
1301   * @param p2 2nd Parser.
1302   * @param p3 3rd Parser.
1303   * @param p4 4th Parser.
1304   * @param p5 5th Parser.
1305   * @return the new Parser.
1306   */
1307  public static <R> Parser<R> plus(final String   name, 
1308      final Parser<R> p1, final Parser<? extends R> p2, final Parser<? extends R> p3, 
1309      final Parser<? extends R> p4, final Parser<? extends R> p5){
1310    return plus(name, new Parser[]{p1, p2, p3, p4, p5});
1311  }
1312  /**
1313   * combine alternative parser objects. If the first Parser fails with no input
1314   * consumption, the next ones are executed until one succeeds.
1315   * 
1316   * @param name
1317   *          the name of the created parser.
1318   * @param ps
1319   *          the Parser objects.
1320   * @return the new Parser.
1321   */
1322  public static <R> Parser<R> plus(String   name, final Parser<R>... ps) {
1323    return sum(name, ps).convert();
1324  }
1325
1326  /**
1327   * combine alternative parser objects. If the first Parser fails with no input
1328   * consumption, the next ones are executed until one succeeds.
1329   * 
1330   * @param ps
1331   *          the Parser objects.
1332   * @return the new Parser.
1333   */
1334  public static <R> Parser<R> plus(final Parser<R>... ps) {
1335    return sum("plus", ps).convert();
1336  }
1337
1338  /**
1339   * An array of alternative Parser objects. zero() is returned if the array is
1340   * empty. the returned Parser object will try the Parser objects in the array
1341   * one by one, until one of the following conditioins are met: the Parser
1342   * succeeds, (sum() succeeds) <br>
1343   * the Parser fails with input consumed (sum() fails with input consumed) <br>
1344   * the end of array is encountered. (sum() fails with no input consumed).
1345   * <p>
1346   * [Parser a] -> Parser a
1347   * 
1348   * @param ps
1349   *          the array of alternative Parser objects.
1350   * @return the new Parser object.
1351   */
1352  public static Parser<Object  > sum(final Parser<?>... ps) {
1353    return sum("sum", ps);
1354  }
1355
1356  /**
1357   * An array of alternative Parser objects. zero() is returned if the array is
1358   * empty. the returned Parser object will try the Parser objects in the array
1359   * one by one, until one of the following conditioins are met: the Parser
1360   * succeeds, (sum() succeeds) <br>
1361   * the Parser fails with input consumed (sum() fails with input consumed) <br>
1362   * the end of array is encountered. (sum() fails with no input consumed).
1363   * <p>
1364   * [Parser a] -> Parser a
1365   * 
1366   * @param name
1367   *          the name of the new Parser object.
1368   * @param ps
1369   *          the array of alternative Parser objects.
1370   * @return the new Parser object.
1371   */
1372  public static Parser<Object  > sum(final String   name, final Parser<?>... ps) {
1373    if (ps.length == 0)
1374      return zero();
1375    if (ps.length == 1)
1376      return ps[0].convert();
1377    return _plusAll(name, ps);
1378  }
1379
1380  /**
1381   * Runs two alternative parsers. If both succeed, the one with the longer
1382   * match wins. If both matches the same length, the first one is favored.
1383   * 
1384   * @param name
1385   *          the name of the new Parser object.
1386   * @param p1
1387   *          the 1st alternative parser.
1388   * @param p2
1389   *          the 2nd alternative parser.
1390   * @return the new Parser object.
1391   */
1392  public static <R> Parser<R> longer(final String   name, final Parser<R> p1,
1393      final Parser<R> p2) {
1394    return _longest(name, p1, p2);
1395  }
1396
1397  /**
1398   * Runs an array of alternative parsers. If more than one succeed, the one
1399   * with the longest match wins. If two matches have the same length, the first
1400   * one is favored.
1401   * 
1402   * @param name
1403   *          the name of the new Parser object.
1404   * @param ps
1405   *          the array of alternative parsers.
1406   * @return the new Parser object.
1407   */
1408
1409  public static <R> Parser<R> longest(final String   name, final Parser<R>... ps) {
1410    if (ps.length == 0)
1411      return zero();
1412    if (ps.length == 1)
1413      return ps[0];
1414    return _longest(name, ps);
1415  }
1416
1417  /**
1418   * Runs two alternative parsers. If both succeed, the one with the shorter
1419   * match wins. If both matches the same length, the first one is favored.
1420   * 
1421   * @param name
1422   *          the name of the new Parser object.
1423   * @param p1
1424   *          the 1st alternative parser.
1425   * @param p2
1426   *          the 2nd alternative parser.
1427   * @return the new Parser object.
1428   */
1429
1430  public static <R> Parser<R> shorter(final String   name, final Parser<R> p1,
1431      final Parser<R> p2) {
1432    return _shortest(name, p1, p2);
1433  }
1434
1435  /**
1436   * Runs an array of alternative parsers. If more than one succeed, the one
1437   * with the shortest match wins. If two matches have the same length, the
1438   * first one is favored.
1439   * 
1440   * @param name
1441   *          the name of the new Parser object.
1442   * @param ps
1443   *          the array of alternative parsers.
1444   * @return the new Parser object.
1445   */
1446
1447  public static <R> Parser<R> shortest(final String   name, final Parser<R>... ps) {
1448    if (ps.length == 0)
1449      return zero();
1450    if (ps.length == 1)
1451      return ps[0];
1452    return _shortest(name, ps);
1453  }
1454
1455  private static <R> Parser<R> _shortest(final String   name,
1456      final Parser<R>... ps) {
1457    return _alternate(name, ps, IntOrders.lt());
1458  }
1459
1460  private static <R> Parser<R> _longest(final String   name,
1461      final Parser<R>... ps) {
1462    return _alternate(name, ps, IntOrders.gt());
1463  }
1464
1465  /**
1466   * Runs two alternative parsers. If both succeed, the one with the longer
1467   * match wins. If both matches the same length, the first one is favored.
1468   * 
1469   * @param p1
1470   *          the 1st alternative parser.
1471   * @param p2
1472   *          the 2nd alternative parser.
1473   * @return the new Parser object.
1474   */
1475  public static <R> Parser<R> longer(final Parser<R> p1, final Parser<R> p2) {
1476    return longer("longer", p1, p2);
1477  }
1478
1479  /**
1480   * Runs an array of alternative parsers. If more than one succeed, the one
1481   * with the longest match wins. If two matches have the same length, the first
1482   * one is favored.
1483   * 
1484   * @param ps
1485   *          the array of alternative parsers.
1486   * @return the new Parser object.
1487   */
1488
1489  public static <R> Parser<R> longest(final Parser<R>... ps) {
1490    return longest("longest", ps);
1491  }
1492
1493  /**
1494   * Runs two alternative parsers. If both succeed, the one with the shorter
1495   * match wins. If both matches the same length, the first one is favored.
1496   * 
1497   * @param p1
1498   *          the 1st alternative parser.
1499   * @param p2
1500   *          the 2nd alternative parser.
1501   * @return the new Parser object.
1502   */
1503
1504  public static <R> Parser<R> shorter(final Parser<R> p1, final Parser<R> p2) {
1505    return shorter("shorter", p1, p2);
1506  }
1507
1508  /**
1509   * Runs an array of alternative parsers. If more than one succeed, the one
1510   * with the shortest match wins. If two matches have the same length, the
1511   * first one is favored.
1512   * 
1513   * @param ps
1514   *          the array of alternative parsers.
1515   * @return the new Parser object.
1516   */
1517
1518  public static <R> Parser<R> shortest(final Parser<R>... ps) {
1519    return shortest("shortest", ps);
1520  }
1521  /**
1522   * To create a Parser that runs an array of Parser objects
1523   * until one succeeds. Regardless of look-ahead,
1524   * input consumption will not prevent the next parser from being executed.
1525   * 
1526   * @param name the new parser name.
1527   * @param alternatives the alternative parsers.
1528   * @return the new Parser object.
1529   */
1530  public static Parser<Object  > or(String   name, final Parser<?>... alternatives){
1531    return new OrParser(name, alternatives);
1532  }
1533  /**
1534   * To create a Parser that runs an array of Parser objects
1535   * until one succeeds. Regardless of look-ahead,
1536   * input consumption will not prevent the next parser from being executed.
1537   * 
1538   * @param alternatives the alternative parsers.
1539   * @return the new Parser object.
1540   */
1541  public static Parser<Object  > or(final Parser<?>... alternatives){
1542    return or("or", alternatives);
1543  }
1544  /**
1545   * To create a Parser that runs an array of Parser objects
1546   * until one succeeds. Regardless of look-ahead,
1547   * input consumption will not prevent the next parser from being executed.
1548   * 
1549   * @param name the new parser name.
1550   * @param alternatives the alternative parsers.
1551   * @return the new Parser object.
1552   */
1553  public static <T> Parser<T> alt(String   name, final Parser<T>... alternatives){
1554    return new OrParser(name, alternatives);
1555  }
1556  /**
1557   * To create a Parser that runs an array of Parser objects
1558   * until one succeeds. Regardless of look-ahead,
1559   * input consumption will not prevent the next parser from being executed.
1560   * 
1561   * @param alternatives the alternative parsers.
1562   * @return the new Parser object.
1563   */
1564  public static <T> Parser<T> alt(final Parser<T>... alternatives){
1565    return alt("or", alternatives);
1566  }
1567  private static Parser<Object  > _plusAll(final String   name, final Parser<?>... ps) {
1568    return new SumParser(name, ps);
1569  }
1570
1571  private static <R> Parser<R> _alternate(final String   name,
1572      final Parser<R>[] ps, final IntOrder ord) {
1573    return new BestParser<R>(name, ps, ord);
1574  }
1575
1576  /** ****************** monadic operations ******************* */
1577
1578  /** ****************** additional combinators ******************* */
1579  /**
1580   * First run the Parser p, if it succeeds with input consumed, isConsumed()
1581   * succeeds; if it fails or did not consume input, isConsumed() fails.
1582   * <p>
1583   * Parser a -> Parser a
1584   * 
1585   * @param p
1586   *          the Parser object to test.
1587   * @return the new Parser object.
1588   */
1589  public static <R> Parser<R> isConsumed(final Parser<R> p) {
1590    return isConsumed("isConsumed", p);
1591  }
1592
1593  /**
1594   * First run the Parser p, if it succeeds with input consumed, isConsumed()
1595   * succeeds; if it fails or did not consume input, isConsumed() fails.
1596   * <p>
1597   * Parser a -> Parser a
1598   * 
1599   * @param p
1600   *          the Parser object to test.
1601   * @param err
1602   *          the error message when p succeeds with no input consumed.
1603   * @return the new Parser object.
1604   */
1605  public static <R> Parser<R> isConsumed(final Parser<R> p, final String   err) {
1606    return isConsumed("isConsumed", p, err);
1607  }
1608
1609  /**
1610   * First run the Parser p, if it succeeds with input consumed, isConsumed()
1611   * succeeds; if it fails or did not consume input, isConsumed() fails.
1612   * <p>
1613   * Parser a -> Parser a
1614   * 
1615   * @param name
1616   *          the name of the new Parser object.
1617   * @param p
1618   *          the Parser object to test.
1619   * @return the new Parser object.
1620   */
1621  public static <R> Parser<R> isConsumed(final String   name, final Parser<R> p) {
1622    return isConsumed(name, p, "input not consumed");
1623  }
1624
1625  /**
1626   * First run the Parser p, if it succeeds with input consumed, isConsumed()
1627   * succeeds; if it fails or did not consume input, isConsumed() fails.
1628   * <p>
1629   * Parser a -> Parser a
1630   * 
1631   * @param name
1632   *          the name of the new Parser.
1633   * @param p
1634   *          the Parser object to test.
1635   * @param err
1636   *          the error message when p succeeds with no input consumed.
1637   * @return the new Parser object.
1638   */
1639  public static <R> Parser<R> isConsumed(final String   name, final Parser<R> p,
1640      final String   err) {
1641    return new IsConsumedParser<R>(name, p, err);
1642  }
1643
1644  /**
1645   * First run the Parser p, if it succeeds with no input consumed,
1646   * notConsumed() succeeds; if it fails, notConsumed() fails; if it succeeds
1647   * and consumes input, the input consumption is undone and notConsumed()
1648   * fails.
1649   * <p>
1650   * Parser a -> Parser a
1651   * 
1652   * @param p
1653   *          the Parser object to test.
1654   * @return the new Parser object.
1655   */
1656  public static <R> Parser<R> notConsumed(final Parser<R> p) {
1657    return notConsumed("notConsumed", p);
1658  }
1659
1660  /**
1661   * First run the Parser p, if it succeeds with no input consumed,
1662   * notConsumed() succeeds; if it fails, notConsumed() fails; if it succeeds
1663   * and consumes input, the input consumption is undone and notConsumed()
1664   * fails.
1665   * <p>
1666   * Parser a -> Parser a
1667   * 
1668   * @param p
1669   *          the Parser object to test.
1670   * @param err
1671   *          the error message when p succeeds and consumes some input.
1672   * @return the new Parser object.
1673   */
1674  public static <R> Parser<R> notConsumed(final Parser<R> p, final String   err) {
1675    return notConsumed("notConsumed", p, err);
1676  }
1677
1678  /**
1679   * First run the Parser p, if it succeeds with no input consumed,
1680   * notConsumed() succeeds; if it fails, notConsumed() fails; if it succeeds
1681   * and consumes input, the input consumption is undone and notConsumed()
1682   * fails.
1683   * <p>
1684   * Parser a -> Parser a
1685   * 
1686   * @param name
1687   *          the name of the new Parser.
1688   * @param p
1689   *          the Parser object to test.
1690   * @return the new Parser object.
1691   */
1692  public static <R> Parser<R> notConsumed(final String   name, final Parser<R> p) {
1693    return notConsumed(name, p, "input consumed");
1694  }
1695
1696  /**
1697   * First run the Parser p, if it succeeds with no input consumed,
1698   * notConsumed() succeeds; if it fails, notConsumed() fails; if it succeeds
1699   * and consumes input, the input consumption is undone and notConsumed()
1700   * fails.
1701   * <p>
1702   * Parser a -> Parser a
1703   * 
1704   * @param name
1705   *          the name of the new Parser.
1706   * @param p
1707   *          the Parser object to test.
1708   * @param err
1709   *          the error message when p succeeds and consumes some input.
1710   * @return the new Parser object.
1711   */
1712  public static <R> Parser<R> notConsumed(final String   name, final Parser<R> p,
1713      final String   err) {
1714    return new NotConsumedParser<R>(name, p, err);
1715  }
1716
1717  /**
1718   * Create a lazy evaluated Parser. the ParserEval object is evaluated only
1719   * when the Parser is actually executed.
1720   * <p>
1721   * Parser a -> Parser a
1722   * 
1723   * @param p
1724   *          the ParserEval object.
1725   * @return the Parser object.
1726   */
1727  public static <R> Parser<R> lazy(final ParserEval<R> p) {
1728    return lazy("lazy", p);
1729  }
1730  
1731  /**
1732   * Create a lazy evaluated parser.
1733   * When evaluated, it reads the parser object stored in an array indexed by pos.
1734   * @param placeholder the array that contains parser object.
1735   * @param pos the position (0-based) of the parser to lazily evaluate.
1736   * @return the lazy parser.
1737   */
1738  public static <R> Parser<R> lazy(final Parser<R>[] placeholder, final int pos){
1739    return lazy(new ParserEval<R>(){
1740      public Parser<R> eval() {
1741        return placeholder[pos];
1742      }
1743    });
1744  }
1745  /**
1746   * Create a lazy evaluated parser.
1747   * When evaluated, it reads the first parser object stored in an array.
1748   * @param placeholder the array whose first object is the lazily evaluated parser object.
1749   * @return the lazy parser.
1750   */
1751  public static <R> Parser<R> lazy(final Parser<R>[] placeholder){
1752    return lazy(placeholder, 0);
1753  }
1754  /**
1755   * Create a lazy evaluated Parser. the ParserEval object is evaluated only
1756   * when the Parser is actually executed.
1757   * <p>
1758   * Parser a -> Parser a
1759   * 
1760   * @param name
1761   *          the name of the Parser object.
1762   * @param p
1763   *          the ParserEval object.
1764   * @return the Parser object.
1765   */
1766  public static <R> Parser<R> lazy(final String   name, final ParserEval<R> p) {
1767    return LazyParser.instance(name, p);
1768  }
1769
1770  private static final Parser<Object  > _getState = getState("getState");
1771
1772  /**
1773   * Retrieves the user state.
1774   * <p>
1775   * Parser u u
1776   * 
1777   * @return the Parser object.
1778   * @deprecated as of version 0.6
1779   */
1780  @Deprecated  
1781  public static Parser<Object  > getState() {
1782    return _getState;
1783  }
1784
1785  /**
1786   * Retrieves the user state.
1787   * <p>
1788   * Parser u u
1789   * 
1790   * @param name
1791   *          the name of the Parser object.
1792   * @return the Parser object.
1793   */
1794  @Deprecated  
1795  public static Parser<Object  > getState(final String   name) {
1796    return transformState(name, Maps.id());
1797  }
1798
1799  /**
1800   * Updates the user state. The old user state value is returned.
1801   * <p>
1802   * Parser u1 u
1803   * 
1804   * @param s
1805   *          the new user state value.
1806   * @return the Parser object.
1807   * @deprecated as of version 0.6
1808   */
1809  @Deprecated  
1810  public static Parser<Object  > setState(final Object   s) {
1811    return setState("setState", s);
1812  }
1813
1814  /**
1815   * Updates the user state.
1816   * <p>
1817   * Parser u1 u
1818   * 
1819   * @param name
1820   *          the name of the Parser object.
1821   * @param s
1822   *          the new user state value.
1823   * @return the Parser object.
1824   * @deprecated as of version 0.6
1825   */
1826  @Deprecated  
1827  public static Parser<Object  > setState(final String   name, final Object   s) {
1828    return transformState(name, Maps.cnst(s));
1829  }
1830
1831  /**
1832   * Transforms and updates the user state. The old user state value is
1833   * returned.
1834   * <p>
1835   * (u1->u2) -> Parser u2 u1
1836   * 
1837   * @param m
1838   *          the transformation.
1839   * @return the Parser object.
1840   * @deprecated as of version 0.6
1841   */
1842  @Deprecated  
1843  public static <State> Parser<State> transformState(final Map<State, ?> m) {
1844    return transformState("transformState", m);
1845  }
1846
1847  /**
1848   * Transforms and updates the user state. The old user state value is
1849   * returned.
1850   * <p>
1851   * (u1->u2) -> Parser u2 u1
1852   * 
1853   * @param name
1854   *          the name of the Parser object.
1855   * @param m
1856   *          the transformation.
1857   * @return the Parser object.
1858   * @deprecated as of version 0.6
1859   */
1860  @Deprecated  
1861  public static <State> Parser<State> transformState(final String   name,
1862      final Map<State, ?> m) {
1863    return new Parser<State>(name) {
1864      boolean apply(final ParseContext ctxt) {
1865        final Object   ustate = ctxt.getUserState();
1866        ctxt.setUserState(m.map((State) ustate));
1867        ctxt.setReturn(ustate);
1868        return true;
1869      }
1870    };
1871  }
1872
1873  private static final Parser<Integer  > _getIndex = getIndex("getIndex");
1874
1875  /**
1876   * Retrieves the current index in the source.
1877   * <p>
1878   * Parser Integer
1879   * 
1880   * @return the Parser object.
1881   */
1882  public static Parser<Integer  > getIndex() {
1883    return _getIndex;
1884  }
1885
1886  /**
1887   * Retrieves the current index in the source.
1888   * <p>
1889   * Parser Integer
1890   * 
1891   * @param name
1892   *          the name of the Parser object.
1893   * @return the Parser object.
1894   */
1895  public static Parser<Integer  > getIndex(final String   name) {
1896    return new GetIndexParser(name);
1897  }
1898
1899  /**
1900   * Look ahead with Parser p. The input consumption is undone.
1901   * <p>
1902   * Parser a -> Parser a
1903   * 
1904   * @param name
1905   *          the name of the new Parser object.
1906   * @param p
1907   *          the Parser object.
1908   * @return the new Parser object.
1909   */
1910  public static <R> Parser<R> peek(final String   name, final Parser<R> p) {
1911    return new PeekParser<R>(name, p);
1912  }
1913
1914  /**
1915   * Backout input consumption if p fails. The logical step is ensured to be at
1916   * most 1.
1917   * <p>
1918   * Parser a -> Parser a
1919   * 
1920   * @param name
1921   *          the name of the new Parser object.
1922   * @param p
1923   *          the Parser object.
1924   * @return the new Parser object.
1925   */
1926  public static <R> Parser<R> atomize(final String   name, final Parser<R> p) {
1927    return new AtomicParser<R>(name, p);
1928  }
1929
1930  /**
1931   * if Parser p throws an exception, it is handled by Catch hdl.
1932   * <p>
1933   * Parser a -> Parser a
1934   * 
1935   * @param p
1936   *          the Parser object.
1937   * @param hdl
1938   *          the exception handler.
1939   * @return the new Parser object.
1940   */
1941  public static <R> Parser<R> tryParser(final Parser<R> p,
1942      final Catch<? extends R> hdl) {
1943    return tryParser("try_catch", p, hdl);
1944  }
1945
1946  /**
1947   * if Parser p throws an exception, it is handled by Catch hdl.
1948   * <p>
1949   * Parser a -> Parser a
1950   * 
1951   * @param name
1952   *          the name of the new Parser object.
1953   * @param p
1954   *          the Parser object.
1955   * @param hdl
1956   *          the exception handler.
1957   * @return the new Parser object.
1958   */
1959  public static <R> Parser<R> tryParser(final String   name, final Parser<R> p,
1960      final Catch<? extends R> hdl) {
1961    return new TryParser<R>(name, p, hdl);
1962  }
1963
1964  /**
1965   * Transform the return value of Parser p to a different value.
1966   * <p>
1967   * Parser a -> (a->b) -> Parser b
1968   * 
1969   * @param name
1970   *          the name of the new Parser object.
1971   * @param p
1972   *          the Parser object.
1973   * @param m
1974   *          the Map object.
1975   * @return the new Parser object.
1976   */
1977  public static <R, From> Parser<R> map(final String   name,
1978      final Parser<From> p, final Map<? super From, R> m) {
1979    return new MapParser<R, From>(name, p, m);
1980  }
1981
1982  /**
1983   * Reports an unexpected error.
1984   * <p>
1985   * Parser *
1986   * 
1987   * @param msg
1988   *          the error message.
1989   * @return the new Parser object.
1990   */
1991  public static <x> Parser<x> unexpected(final String   msg) {
1992    return unexpected("unexpected", msg);
1993  }
1994
1995  /**
1996   * Reports an unexpected error.
1997   * <p>
1998   * Parser *
1999   * 
2000   * @param name
2001   *          the name of the new Parser object.
2002   * @param msg
2003   *          the error message.
2004   * @return the new Parser object.
2005   */
2006  public static <x> Parser<x> unexpected(final String   name, final String   msg) {
2007    return new UnexpectedParser<x>(name, msg);
2008  }
2009
2010  /**
2011   * Token level parser. checks the current token with the FromToken object. If
2012   * the fromToken() method returns null, a system unexpected token error
2013   * occurs; if the method returns anything other than null, the token is
2014   * consumed and token() succeeds.
2015   * <p>
2016   * (SourcePos->Token->a) -> Parser a
2017   * 
2018   * @param ft
2019   *          the FromToken object.
2020   * @return the new Parser object.
2021   */
2022  public static <R> Parser<R> token(final FromToken<R> ft) {
2023    return token("token", ft);
2024  }
2025
2026  /**
2027   * Token level parser. checks the current token with the FromToken object. If
2028   * the fromToken() method returns null, a system unexpected token error
2029   * occurs; if the method returns anything other than null, the token is
2030   * consumed and token() succeeds.
2031   * <p>
2032   * (SourcePos->Object->a) -> Parser a
2033   * 
2034   * @param name
2035   *          the name of the new Parser object.
2036   * @param ft
2037   *          the FromToken object.
2038   * @return the new Parser object.
2039   */
2040  public static <R> Parser<R> token(final String   name, final FromToken<R> ft) {
2041    return new IsTokenParser<R>(name, ft);
2042  }
2043
2044  /**
2045   * Token level parser. checks to see if the current token is token t. (using
2046   * ==). If no, a system unexpected token error occurs; if yes, the token is
2047   * consumed and token() succeeds. the token is used as the parse result.
2048   * <p>
2049   * Object -> Parser SourcePos
2050   * 
2051   * @param t
2052   *          the expected Token object.
2053   * @return the new Parser object.
2054   */
2055  public static Parser<Tok> token(final Object   t) {
2056    return token("token", t);
2057  }
2058
2059  /**
2060   * Token level parser. checks to see if the current token is token t. (using
2061   * ==). If no, a system unexpected token error occurs; if yes, the token is
2062   * consumed and token() succeeds. the token is used as the parse result.
2063   * <p>
2064   * Token -> Parser SourcePos
2065   * 
2066   * @param name
2067   *          the name of the new Parser object.
2068   * @param t
2069   *          the expected Token object.
2070   * @return the new Parser object.
2071   */
2072  public static Parser<Tok> token(final String   name, final Object   t) {
2073    // the token has to be singleton
2074    return token(name, IsToken.instance(t));
2075  }
2076
2077  /**
2078   * if Parser p fails and does not consume input, reports an expecting error
2079   * with the given label.
2080   * <p>
2081   * Parser a -> Parser a
2082   * 
2083   * @param name
2084   *          the name of the new Parser object.
2085   * @param lbl
2086   *          the label text.
2087   * @param p
2088   *          the Parser object to label.
2089   * @return the new Parser object.
2090   */
2091  public static <R> Parser<R> label(final String   name, final String   lbl,
2092      final Parser<R> p) {
2093    final Parser<R> otherwise = expect(lbl);
2094    return plus(name, p, otherwise);
2095    /*
2096    return new Parser<R>(name) {
2097      boolean apply(final ParseContext ctxt) {
2098        final int at = ctxt.getAt();
2099        final boolean r = p.parse(ctxt);
2100        if (ctxt.getAt() != at)
2101          return r;
2102        if (r)
2103          return r;
2104        return setErrorExpecting(lbl, ctxt);
2105      }
2106    };*/
2107  }
2108  /**
2109   * Create a Parser object that reports a "something expected" error.
2110   * @param <x> the result Parser object is good for any result type. 
2111   * (it does not return anyway)
2112   * @param name the parser name.
2113   * @param lbl the label.
2114   * @return the Parser object.
2115   * @since version 0.6
2116   * 
2117   */
2118  public static <x> Parser<x> expect(final String   name, final String   lbl){
2119    return new ExpectParser<x>(name, lbl);    
2120  }
2121  /**
2122   * Create a Parser object that reports a "something expected" error.
2123   * @param <x> the result Parser object is good for any result type. 
2124   * (it does not return anyway)
2125   * @param lbl the label.
2126   * @return the Parser object.
2127   * @since version 0.6
2128   */
2129  public static <x> Parser<x> expect(final String   lbl){
2130    return expect("expect", lbl);  
2131  }
2132  /**
2133   * throws a pseudo-exception.
2134   * <p>
2135   * Parser *
2136   * 
2137   * @param e
2138   *          the exception object.
2139   * @return the Parser object.
2140   */
2141  public static <R> Parser<R> raise(final Object   e) {
2142    return raise("raise", e);
2143  }
2144
2145  /**
2146   * throws a pseudo-exception.
2147   * <p>
2148   * Parser *
2149   * 
2150   * @param name
2151   *          the name of the new Parser object.
2152   * @param e
2153   *          the exception object.
2154   * @return the Parser object.
2155   */
2156  public static <R> Parser<R> raise(final String   name, final Object   e) {
2157    return new RaiseParser<R>(name, e);
2158  }
2159
2160  /**
2161   * Greedily runs Parser p repeatedly for at least min times and collect the
2162   * result with the Accumulator object created by Accumulatable. Fails if p
2163   * fails and consumes some input or if p throws a pseudo-exception.
2164   * <p>
2165   * Accumulatable a r -> int -> int -> Parser a -> Parser r
2166   * 
2167   * @param name
2168   *          the name of the new Parser object.
2169   * @param accm
2170   *          the Accumulatable object.
2171   * @param min
2172   *          the minimum times to repeat.
2173   * @param p
2174   *          the Parser object.
2175   * @return the new Parser object.
2176   */
2177  public static <From, A extends From, R, To extends R> Parser<R> manyAccum(
2178      final String   name, final Accumulatable<From, To> accm, final int min,
2179      final Parser<A> p) {
2180    if (min < 0)
2181      throw new IllegalArgumentException  ("min<0");
2182    return new ManyAccumMinParser<R, From, To, A>(name, accm, min, p);
2183  }
2184
2185  /**
2186   * Greedily runs Parser p repeatedly for 0 or more times. and collect the
2187   * result with the Accumulator object created by Accumulatable. Fails if p
2188   * fails and consumes some input or if p throws a pseudo-exception.
2189   * <p>
2190   * Accumulatable a r -> int -> int -> Parser a -> Parser r
2191   * 
2192   * @param name
2193   *          the name of the new Parser object.
2194   * @param accm
2195   *          the Accumulatable object.
2196   * @param p
2197   *          the Parser object.
2198   * @return the new Parser object.
2199   */
2200  public static <From, A extends From, R, To extends R> Parser<R> manyAccum(
2201      final String   name, final Accumulatable<From, To> accm, final Parser<A> p) {
2202    return new ManyAccumParser<R, From, To, A>(name, accm, p);
2203  }
2204
2205  /**
2206   * Greedily runs Parser p repeatedly for at least min times and at most max
2207   * times, collect the result with the Accumulator object created by
2208   * Accumulatable. Fails if p fails and consumes some input or if p throws a
2209   * pseudo-exception.
2210   * <p>
2211   * Accumulatable a r -> int -> int -> Parser a -> Parser r
2212   * 
2213   * @param name
2214   *          the name of the new Parser object.
2215   * @param accm
2216   *          the Accumulatable object.
2217   * @param min
2218   *          the minimum times to repeat.
2219   * @param max
2220   *          the maximum times to repeat.
2221   * @param p
2222   *          the Parser object.
2223   * @return the new Parser object.
2224   */
2225  public static <From, A extends From, R, To extends R> Parser<R> someAccum(
2226      final String   name, final Accumulatable<From, To> accm, final int min,
2227      final int max, final Parser<A> p) {
2228    if (min < 0 || max < 0 || min > max)
2229      throw new IllegalArgumentException  ();
2230    return new ManyAccumMinMaxParser<R, From, To, A>(name, max, p, min, accm);
2231  }
2232
2233  /**
2234   * Greedily runs Parser p repeatedly for at most max times, collect the result
2235   * with the Accumulator object created by Accumulatable. Fails if p fails and
2236   * consumes some input or if p throws a pseudo-exception.
2237   * <p>
2238   * Accumulatable a r -> int -> int -> Parser a -> Parser r
2239   * 
2240   * @param name
2241   *          the name of the new Parser object.
2242   * @param accm
2243   *          the Accumulatable object.
2244   * @param max
2245   *          the maximum times to repeat.
2246   * @param p
2247   *          the Parser object.
2248   * @return the new Parser object.
2249   */
2250  public static <From, A extends From, R, To extends R> Parser<R> someAccum(
2251      final String   name, final Accumulatable<From, To> accm, final int max,
2252      final Parser<A> p) {
2253    if (max < 0)
2254      throw new IllegalArgumentException  ("max<0");
2255    return new SomeAccumMaxParser<R, From, To, A>(name, max, accm, p);
2256  }
2257
2258  private static final Parser<?> _eof = eof("EOF");
2259
2260  /**
2261   * Asserts eof is met. Fails otherwise.
2262   * <p>
2263   * Parser ?
2264   * 
2265   * @return the Parser object.
2266   */
2267  public static Parser<?> eof() {
2268    return _eof;
2269  }
2270
2271  /**
2272   * Asserts eof is met. Fails otherwise.
2273   * <p>
2274   * Parser ?
2275   * 
2276   * @param msg the error message if eof is not met.
2277   * @return the Parser object.
2278   */
2279  public static Parser<?> eof(final String   msg) {
2280    return eof("eof", msg);
2281  }
2282
2283  /**
2284   * Asserts eof is met. Fails otherwise.
2285   * <p>
2286   * Parser ?
2287   * 
2288   * @param name the name of the new Parser object.
2289   * @param msg the error message if eof is not met.
2290   * @return the Parser object.
2291   */
2292  public static Parser<?> eof(final String   name, final String   msg) {
2293    return new EofParser(name, msg);
2294  }
2295
2296  /**
2297   * Succeeds if Parser p fails; Fails otherwise. Input consumption is undone.
2298   * <p>
2299   * Parser ? -> Parser ?
2300   * 
2301   * @param name the name of the new Parser object.
2302   * @param p the Parser to 'not'
2303   * @return the new Parser object.
2304   */
2305  public static Parser<?> not(final String   name, final Parser<?> p) {
2306    return not(name, p, p.getName());
2307  }
2308
2309  /**
2310   * Succeeds if Parser p fails; Fails otherwise. Input consumption is undone.
2311   * <p>
2312   * Parser ? -> Parser ?
2313   * 
2314   * @param name the name of the new Parser object.
2315   * @param p the Parser to 'not'
2316   * @param errmsg the error message if Parser p succeeds.
2317   * @return the new Parser object.
2318   */
2319  public static Parser<?> not(final String   name, final Parser<?> p,
2320      final String   errmsg) {
2321    return ifelse(name, p.peek(), unexpected(errmsg), one());
2322  }
2323
2324  /** ****************** additional combinators ******************* */
2325
2326  /**
2327   * Greedily runs Parser p repeatedly for at least min times and discard the
2328   * results.
2329   * <p>
2330   * int -> Parser ? -> Parser _
2331   * 
2332   * @param name
2333   *          the name of the new Parser object.
2334   * @param min
2335   *          the minimal times to run.
2336   * @param p
2337   *          the Parser object.
2338   * @return the new Parser object.
2339   */
2340  public static <R> Parser<_> many(final String   name, final int min,
2341      final Parser<?> p) {
2342    return new ManyMinParser(name, p, min);
2343  }
2344
2345  /**
2346   * Greedily runs Parser p repeatedly and discard the results.
2347   * <p>
2348   * Parser ? -> Parser _
2349   * 
2350   * @param name
2351   *          the name of the new Parser object.
2352   * @param p
2353   *          the Parser object.
2354   * @return the new Parser object.
2355   */
2356  public static Parser<_> many(final String   name, final Parser<?> p) {
2357    return new ManyParser(name, p);
2358  }
2359
2360  /**
2361   * Greedily runs Parser p repeatedly for at least min times and collect the
2362   * result in an array whose element type is etype.
2363   * <p>
2364   * Class [a] -> int -> Parser a -> Parser [a]
2365   * 
2366   * @param name
2367   *          the name of the new Parser object.
2368   * @param etype
2369   *          the array element type.
2370   * @param min
2371   *          the maximal times to run.
2372   * @param p
2373   *          the Parser object.
2374   * @return the new Parser object.
2375   */
2376  public static <R> Parser<R[]> many(final String   name, final Class  <R> etype,
2377      final int min, final Parser<? extends R> p) {
2378    return many(name, ArrayFactories.typedFactory(etype), min, p);
2379  }
2380
2381  /**
2382   * Greedily runs Parser p repeatedly and collect the result in an array whose
2383   * element type is etype.
2384   * <p>
2385   * Class [a] -> Parser a -> Parser [a]
2386   * 
2387   * @param name
2388   *          the name of the new Parser object.
2389   * @param etype
2390   *          the array element type.
2391   * @param p
2392   *          the Parser object.
2393   * @return the new Parser object.
2394   */
2395  public static <R> Parser<R[]> many(final String   name, final Class  <R> etype,
2396      final Parser<? extends R> p) {
2397    return many(name, ArrayFactories.typedFactory(etype), p);
2398  }
2399
2400  /**
2401   * Greedily runs Parser p repeatedly for at least min times and collect the
2402   * result in an array created by ArrayFactory object.
2403   * <p>
2404   * ArrayFactory a -> int -> Parser a -> Parser [a]
2405   * 
2406   * @param name
2407   *          the name of the new Parser object.
2408   * @param af
2409   *          the ArrayFacory object.
2410   * @param min
2411   *          the maximal times to run.
2412   * @param p
2413   *          the Parser object.
2414   * @return the new Parser object.
2415   */
2416  public static <R> Parser<R[]> many(final String   name,
2417      final ArrayFactory<R> af, final int min, final Parser<? extends R> p) {
2418    return manyAccum(name, getArrayAccumulatable(af), min, p);
2419  }
2420
2421  /**
2422   * Greedily runs Parser p repeatedly and collect the result in an array
2423   * created by ArrayFactory object.
2424   * <p>
2425   * ArrayFactory a -> Parser a -> Parser [a]
2426   * 
2427   * @param name
2428   *          the name of the new Parser object.
2429   * @param af
2430   *          the ArrayFacory object.
2431   * @param p
2432   *          the Parser object.
2433   * @return the new Parser object.
2434   */
2435  public static <R> Parser<R[]> many(final String   name,
2436      final ArrayFactory<R> af, final Parser<? extends R> p) {
2437    return manyAccum(name, getArrayAccumulatable(af), p);
2438  }
2439
2440  /**
2441   * Greedily runs Parser p repeatedly for at least min times and at most max
2442   * time. The return values are discarded.
2443   * <p>
2444   * int -> int -> Parser ? -> Parser _
2445   * 
2446   * @param name
2447   *          the name of the new Parser object.
2448   * @param min
2449   *          the minimal number of times to run.
2450   * @param max
2451   *          the maximal number of times to run.
2452   * @param p
2453   *          the Parser object.
2454   * @return the new Parser object.
2455   */
2456  public static <R> Parser<_> some(final String   name, final int min,
2457      final int max, final Parser<?> p) {
2458    if (min < 0 || max < 0 || min > max)
2459      throw new IllegalArgumentException  ();
2460    if (max == 0)
2461      return _retn_unit();
2462    return new SomeMinMaxParser(name, max, p, min);
2463  }
2464
2465  /**
2466   * Greedily runs Parser p repeatedly for at most max time. The return values
2467   * are discarded.
2468   * <p>
2469   * int -> Parser ? -> Parser _
2470   * 
2471   * @param name
2472   *          the name of the new Parser object.
2473   * @param max
2474   *          the maximal number of times to run.
2475   * @param p
2476   *          the Parser object.
2477   * @return the new Parser object.
2478   */
2479  public static Parser<_> some(final String   name, final int max,
2480      final Parser<?> p) {
2481    if (max < 0)
2482      throw new IllegalArgumentException  ("max<0");
2483    if (max == 0)
2484      return _retn_unit();
2485    return new SomeMaxParser(name, max, p);
2486  }
2487
2488  /**
2489   * Greedily runs Parser p repeatedly for at least min times and at most max
2490   * time. The results are collected and returned in an array created by
2491   * ArrayFactory object.
2492   * <p>
2493   * ArrayFactory a -> int -> int -> Parser a -> Parser [a]
2494   * 
2495   * @param name
2496   *          the name of the new Parser object.
2497   * @param af
2498   *          the ArrayFacory object.
2499   * @param min
2500   *          the minimal number of times to run.
2501   * @param max
2502   *          the maximal number of times to run.
2503   * @param p
2504   *          the Parser object.
2505   * @return the new Parser object.
2506   */
2507  public static <R> Parser<R[]> some(final String   name,
2508      final ArrayFactory<R> af, final int min, final int max,
2509      final Parser<? extends R> p) {
2510    return someAccum(name, getArrayAccumulatable(af), min, max, p);
2511  }
2512
2513  /**
2514   * Greedily runs Parser p repeatedly for at most max time. The results are
2515   * collected and returned in an array created by ArrayFactory object.
2516   * <p>
2517   * ArrayFactory a -> int -> Parser a -> Parser [a]
2518   * 
2519   * @param name
2520   *          the name of the new Parser object.
2521   * @param af
2522   *          the ArrayFacory object.
2523   * @param max
2524   *          the maximal number of times to run.
2525   * @param p
2526   *          the Parser object.
2527   * @return the new Parser object.
2528   */
2529  public static <R> Parser<R[]> some(final String   name,
2530      final ArrayFactory<R> af, final int max, final Parser<? extends R> p) {
2531    return someAccum(name, getArrayAccumulatable(af), max, p);
2532  }
2533
2534  /**
2535   * Greedily runs Parser p repeatedly for at least min times and at most max
2536   * times. The return values are collected and returned in an array whose
2537   * element type is etype.
2538   * <p>
2539   * Class -> int -> int -> Parser a -> Parser [Object]
2540   * 
2541   * @param name
2542   *          the name of the new Parser object.
2543   * @param etype
2544   *          the array element type.
2545   * @param min
2546   *          the minimal number of times to run.
2547   * @param max
2548   *          the maximal number of times to run.
2549   * @param p
2550   *          the Parser object.
2551   * @return the new Parser object.
2552   */
2553  public static <R> Parser<R[]> some(final String   name, Class  <R> etype,
2554      final int min, final int max, final Parser<? extends R> p) {
2555    return some(name, ArrayFactories.typedFactory(etype), min, max, p);
2556  }
2557
2558  /**
2559   * Greedily runs Parser p repeatedly for at most max times. The return values
2560   * are collected and returned in an array whose element type is etype.
2561   * <p>
2562   * Class -> int -> Parser a -> Parser [Object]
2563   * 
2564   * @param name
2565   *          the name of the new Parser object.
2566   * @param etype
2567   *          the array element type.
2568   * @param max
2569   *          the maximal number of times to run.
2570   * @param p
2571   *          the Parser object.
2572   * @return the new Parser object.
2573   */
2574  public static <R> Parser<R[]> some(final String   name, Class  <R> etype,
2575      final int max, final Parser<? extends R> p) {
2576    return some(name, ArrayFactories.typedFactory(etype), max, p);
2577  }
2578
2579  /**
2580   * Run 2 Parsers sequentially and transform the return values to a new value.
2581   * <p>
2582   * Parser a->Parser b->(a->b->r)->Parser r
2583   * 
2584   * @param p1
2585   *          1st parser.
2586   * @param p2
2587   *          2nd parser.
2588   * @param m2
2589   *          the transformer.
2590   * @return the new Parser object.
2591   */
2592  public static <A, B, R> Parser<R> map2(final Parser<A> p1,
2593      final Parser<B> p2, final Map2<? super A, ? super B, R> m2) {
2594    return map2("map2", p1, p2, m2);
2595  }
2596
2597  /**
2598   * Run 2 Parsers sequentially and transform the return values to a new value.
2599   * <p>
2600   * Parser a->Parser b->(a->b->r)->Parser r
2601   * 
2602   * @param name
2603   *          the name of the new Parser object.
2604   * @param p1
2605   *          1st parser.
2606   * @param p2
2607   *          2nd parser.
2608   * @param m2
2609   *          the transformer.
2610   * @return the new Parser object.
2611   */
2612  public static <A, B, R> Parser<R> map2(final String   name, final Parser<A> p1,
2613      final Parser<B> p2, final Map2<? super A, ? super B, R> m2) {
2614    return new Map2Parser<R, A, B>(name, m2, p1, p2);
2615  }
2616
2617  /**
2618   * Run 3 Parsers sequentially and transform the return values to a new value.
2619   * <p>
2620   * Parser a->Parser b->Parser c->(a->b->c->r)->Parser r
2621   * 
2622   * @param p1
2623   *          1st parser.
2624   * @param p2
2625   *          2nd parser.
2626   * @param p3
2627   *          3rd parser.
2628   * @param m3
2629   *          the transformer.
2630   * @return the new Parser object.
2631   */
2632  public static <A, B, C, R> Parser<R> map3(final Parser<A> p1,
2633      final Parser<B> p2, final Parser<C> p3,
2634      final Map3<? super A, ? super B, ? super C, R> m3) {
2635    return map3("map3", p1, p2, p3, m3);
2636  }
2637
2638  /**
2639   * Run 3 Parsers sequentially and transform the return values to a new value.
2640   * <p>
2641   * Parser a->Parser b->Parser c->(a->b->c->r)->Parser r
2642   * 
2643   * @param name
2644   *          the name of the new Parser object.
2645   * @param p1
2646   *          1st parser.
2647   * @param p2
2648   *          2nd parser.
2649   * @param p3
2650   *          3rd parser.
2651   * @param m3
2652   *          the transformer.
2653   * @return the new Parser object.
2654   */
2655  public static <A, B, C, R> Parser<R> map3(final String   name,
2656      final Parser<A> p1, final Parser<B> p2, final Parser<C> p3,
2657      final Map3<? super A, ? super B, ? super C, R> m3) {
2658    return new Map3Parser<R, A, B, C>(name, m3, p2, p1, p3);
2659  }
2660
2661  /**
2662   * Run 4 Parsers sequentially and transform the return values to a new value.
2663   * <p>
2664   * Parser a->Parser b->Parser c->Parser d->(a->b->c->d->r)->Parser r
2665   * 
2666   * @param p1
2667   *          1st parser.
2668   * @param p2
2669   *          2nd parser.
2670   * @param p3
2671   *          3rd parser.
2672   * @param p4
2673   *          4th parser.
2674   * @param m4
2675   *          the transformer.
2676   * @return the new Parser object.
2677   */
2678  public static <A, B, C, D, R> Parser<R> map4(final Parser<A> p1,
2679      final Parser<B> p2, final Parser<C> p3, final Parser<D> p4,
2680      final Map4<? super A, ? super B, ? super C, ? super D, R> m4) {
2681    return map4("map4", p1, p2, p3, p4, m4);
2682  }
2683
2684  /**
2685   * Run 4 Parsers sequentially and transform the return values to a new value.
2686   * <p>
2687   * Parser a->Parser b->Parser c->Parser d->(a->b->c->d->r)->Parser r
2688   * 
2689   * @param name
2690   *          the name of the new Parser object.
2691   * @param p1
2692   *          1st parser.
2693   * @param p2
2694   *          2nd parser.
2695   * @param p3
2696   *          3rd parser.
2697   * @param p4
2698   *          4th parser.
2699   * @param m4
2700   *          the transformer.
2701   * @return the new Parser object.
2702   */
2703  public static <A, B, C, D, R> Parser<R> map4(final String   name,
2704      final Parser<A> p1, final Parser<B> p2, final Parser<C> p3,
2705      final Parser<D> p4,
2706      final Map4<? super A, ? super B, ? super C, ? super D, R> m4) {
2707    return new Map4Parser<R, A, B, C, D>(name, m4, p3, p2, p1, p4);
2708  }
2709
2710  /**
2711   * Run 5 Parsers sequentially and transform the return values to a new value.
2712   * <p>
2713   * Parser a->Parser b->Parser c->Parser d->Parser
2714   * e->(a->b->c->d->e->r)->Parser r
2715   * 
2716   * @param p1
2717   *          1st parser.
2718   * @param p2
2719   *          2nd parser.
2720   * @param p3
2721   *          3rd parser.
2722   * @param p4
2723   *          4th parser.
2724   * @param p5
2725   *          5th parser.
2726   * @param m5
2727   *          the transformer.
2728   * @return the new Parser object.
2729   */
2730  public static <A, B, C, D, E, R> Parser<R> map5(final Parser<A> p1,
2731      final Parser<B> p2, final Parser<C> p3, final Parser<D> p4,
2732      final Parser<E> p5,
2733      final Map5<? super A, ? super B, ? super C, ? super D, ? super E, R> m5) {
2734    return map5("map5", p1, p2, p3, p4, p5, m5);
2735  }
2736
2737  /**
2738   * Run 5 Parsers sequentially and transform the return values to a new value.
2739   * <p>
2740   * Parser a->Parser b->Parser c->Parser d->Parser
2741   * e->(a->b->c->d->e->r)->Parser r
2742   * 
2743   * @param name
2744   *          the name of the new Parser object.
2745   * @param p1
2746   *          1st parser.
2747   * @param p2
2748   *          2nd parser.
2749   * @param p3
2750   *          3rd parser.
2751   * @param p4
2752   *          4th parser.
2753   * @param p5
2754   *          5th parser.
2755   * @param m5
2756   *          the transformer.
2757   * @return the new Parser object.
2758   */
2759  public static <A, B, C, D, E, R> Parser<R> map5(final String   name,
2760      final Parser<A> p1, final Parser<B> p2, final Parser<C> p3,
2761      final Parser<D> p4, final Parser<E> p5,
2762      final Map5<? super A, ? super B, ? super C, ? super D, ? super E, R> m5) {
2763    return new Map5Parser<R, A, B, C, D, E>(name, p1, p3, p4, p2, m5, p5);
2764  }
2765
2766  /**
2767   * Runs Parser p, if it fails with no input consumed, return default value v
2768   * instead. <br>
2769   * plus(p, retn(v))
2770   * <p>
2771   * a -> Parser a -> Parser a
2772   * 
2773   * @param v
2774   *          the default value.
2775   * @param p
2776   *          the Parser object.
2777   * @return the new Parser object.
2778   */
2779  public static <R> Parser<R> option(final R v, final Parser<R> p) {
2780    return option("option", v, p);
2781  }
2782
2783  /**
2784   * Runs Parser p, if it fails with no input consumed, return default value v
2785   * instead. <br>
2786   * plus(name, p, retn(v))
2787   * <p>
2788   * a -> Parser a -> Parser a
2789   * 
2790   * @param name
2791   *          the name of the new Parser object.
2792   * @param v
2793   *          the default value.
2794   * @param p
2795   *          the Parser object.
2796   * @return the new Parser object.
2797   */
2798  public static <R> Parser<R> option(final String   name, final R v,
2799      final Parser<R> p) {
2800    return plus(name, p, retn(v));
2801  }
2802
2803  /**
2804   * Runs Parser p, if it fails with no input consumed, succeed anyway with null as the result. <br>
2805   * option(p, null)
2806   * <p>
2807   * Parser a -> Parser a
2808   * 
2809   * @param p
2810   *          the Parser object.
2811   * @return the new Parser object.
2812   */
2813  public static <R> Parser<R> optional(final Parser<R> p) {
2814    return optional("optional", p);
2815  }
2816
2817  /**
2818   * Runs Parser p, if it fails with no input consumed, succeed anyway with null as result. <br>
2819   * option(name, p, null)
2820   * <p>
2821   * Parser a -> Parser a
2822   * 
2823   * @param name
2824   *          the name of the new Parser object.
2825   * @param p
2826   *          the Parser object.
2827   * @return the new Parser object.
2828   */
2829  public static <R> Parser<R> optional(final String   name, final Parser<R> p) {
2830    return plus(name, p, _retn_null);
2831  }
2832
2833  /**
2834   * Runs a Parser that is between a pair of parsers. First run Parser open,
2835   * then run Parser p, finally run Parser close. The return value of p is
2836   * preserved as the return value. <br>
2837   * do {open; x<-p; close; return p}
2838   * <p>
2839   * Parser ? -> Parser a -> Parser ? -> Parser a
2840   * 
2841   * @param open
2842   *          the opening parser.
2843   * @param close
2844   *          the closing parser.
2845   * @param p
2846   *          the Parser object.
2847   * @return the new Parser object.
2848   */
2849  public static <R> Parser<R> between(final Parser<?> open,
2850      final Parser<?> close, final Parser<R> p) {
2851    return between("between", open, close, p);
2852  }
2853
2854  /**
2855   * runs a Parser that is between a pair of parsers. First run Parser open,
2856   * then run Parser p, finally run Parser close. The return value of p is
2857   * preserved as the return value. <br>
2858   * do {open; x<-p; close; return p}
2859   * <p>
2860   * Parser ? -> Parser ? -> Parser a -> Parser a
2861   * 
2862   * @param name
2863   *          the name of the new Parser object.
2864   * @param open
2865   *          the opening parser.
2866   * @param close
2867   *          the closing parser.
2868   * @param p
2869   *          the Parser object.
2870   * @return the new Parser object.
2871   */
2872  public static <R> Parser<R> between(final String   name, final Parser<?> open,
2873      final Parser<?> close, final Parser<R> p) {
2874    return seq(name, open, p.followedBy(close));
2875  }
2876
2877  /**
2878   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2879   * <p>
2880   * Parser p has to succeed at least once. <br>
2881   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2882   * <br>
2883   * The return values are discarded.
2884   * <p>
2885   * Parser ? -> Parser ? -> Parser _
2886   * 
2887   * @param sep
2888   *          the seperator.
2889   * @param p
2890   *          the Parser object.
2891   * @return the new Parser object.
2892   */
2893  public static Parser<_> sepBy1(final Parser<?> sep, final Parser<?> p) {
2894    return sepBy1("sepBy1", sep, p);
2895  }
2896
2897  /**
2898   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2899   * <p>
2900   * Parser p has to succeed at least once. <br>
2901   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2902   * <br>
2903   * The return values are discarded.
2904   * <p>
2905   * Parser ? -> Parser ? -> Parser _
2906   * 
2907   * @param name
2908   *          the name of the new Parser object.
2909   * @param sep
2910   *          the seperator.
2911   * @param p
2912   *          the Parser object.
2913   * @return the new Parser object.
2914   */
2915  public static Parser<_> sepBy1(final String   name, final Parser<?> sep,
2916      final Parser<?> p) {
2917    // return sepBy1(name, ArrayFactories.defaultFactory(), sep, p);
2918    final Parser<?> sepp = seq(sep, p);
2919    return seq(name, p, sepp.many());
2920  }
2921
2922  /**
2923   * <p>
2924   * Class -> Parser a -> Parser [Object]. <br>
2925   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2926   * <p>
2927   * Parser p has to succeed at least once. <br>
2928   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2929   * <br>
2930   * The return values are collected in an array whose element type is etype.
2931   * 
2932   * @param etype
2933   *          the array element type.
2934   * @param sep
2935   *          the seperator.
2936   * @param p
2937   *          the Parser object.
2938   * @return the new Parser object.
2939   */
2940  public static <R> Parser<R[]> sepBy1(final Class  <R> etype,
2941      final Parser<?> sep, final Parser<? extends R> p) {
2942    return sepBy1("sepBy1", etype, sep, p);
2943  }
2944
2945  /**
2946   * <p>
2947   * Class -> Parser a -> Parser [Object]. <br>
2948   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2949   * <p>
2950   * Parser p has to succeed at least once. <br>
2951   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2952   * <br>
2953   * The return values are collected in an array whose element type is etype.
2954   * 
2955   * @param name
2956   *          the name of the new Parser object.
2957   * @param etype
2958   *          the array element type.
2959   * @param sep
2960   *          the seperator.
2961   * @param p
2962   *          the Parser object.
2963   * @return the new Parser object.
2964   */
2965  public static <R> Parser<R[]> sepBy1(final String   name, final Class  <R> etype,
2966      final Parser<?> sep, final Parser<? extends R> p) {
2967    return sepBy1(name, ArrayFactories.typedFactory(etype), sep, p);
2968  }
2969
2970  /**
2971   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2972   * <p>
2973   * Parser p has to succeed at least once. <br>
2974   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2975   * <br>
2976   * The return values are collected in an array created by the ArrayFactory
2977   * object af.
2978   * <p>
2979   * ArrayFactory a -> Parser a -> Parser [a]
2980   * 
2981   * @param af
2982   *          the ArrayFacory object.
2983   * @param sep
2984   *          the seperator.
2985   * @param p
2986   *          the Parser object.
2987   * @return the new Parser object.
2988   */
2989  public static <R> Parser<R[]> sepBy1(final ArrayFactory<R> af,
2990      final Parser<?> sep, final Parser<? extends R> p) {
2991    return sepBy1("sepBy1", af, sep, p);
2992  }
2993
2994  /**
2995   * run a series of Parser p pattern that is seperated by Parser sep pattern.
2996   * <p>
2997   * Parser p has to succeed at least once. <br>
2998   * For example: pattern "token, token, token, token" is sepBy1(comma, token).
2999   * <br>
3000   * The return values are collected in an array created by the ArrayFactory
3001   * object af.
3002   * <p>
3003   * ArrayFactory a -> Parser a -> Parser [a]
3004   * 
3005   * @param name
3006   *          the name of the new Parser object.
3007   * @param af
3008   *          the ArrayFacory object.
3009   * @param sep
3010   *          the seperator.
3011   * @param p
3012   *          the Parser object.
3013   * @return the new Parser object.
3014   */
3015  public static <R, A extends R> Parser<R[]> sepBy1(final String   name,
3016      final ArrayFactory<R> af, final Parser<?> sep, final Parser<A> p) {
3017    final Parser<A> sepp = seq(sep, p);
3018    final ToParser<A, R[]> binder = new ToParser<A, R[]>() {
3019      public Parser<R[]> toParser(final A v) {
3020        return manyAccum("sepBy1", getArrayAccumulatable(af, v), sepp);
3021      }
3022    };
3023    return bind(name, p, binder);
3024  }
3025
3026  /**
3027   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3028   * <p>
3029   * Parser p can succeed 0 or more times. <br>
3030   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3031   * <br>
3032   * The return values are discarded.
3033   * <p>
3034   * Parser ? -> Parser ? -> Parser _
3035   * 
3036   * @param sep
3037   *          the seperator.
3038   * @param p
3039   *          the Parser object.
3040   * @return the new Parser object.
3041   */
3042  public static Parser<_> sepBy(final Parser<?> sep, final Parser<?> p) {
3043    return sepBy("sepBy", sep, p);
3044  }
3045
3046  /**
3047   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3048   * <p>
3049   * Parser p can succeed 0 or more times. <br>
3050   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3051   * <br>
3052   * The return values are discarded.
3053   * <p>
3054   * Parser ? -> Parser ? -> Parser _
3055   * 
3056   * @param name
3057   *          the name of the new Parser object.
3058   * @param sep
3059   *          the seperator.
3060   * @param p
3061   *          the Parser object.
3062   * @return the new Parser object.
3063   */
3064  public static Parser<_> sepBy(final String   name, final Parser<?> sep,
3065      final Parser<?> p) { 
3066    return plus(name, sepBy1(sep, p), _retn_unit());
3067  }
3068
3069  /**
3070   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3071   * <p>
3072   * Parser p can succeed 0 or more times. <br>
3073   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3074   * <br>
3075   * The return values are collected in an array whose element type is etype.
3076   * <p>
3077   * Class -> Parser a -> Parser [Object]
3078   * 
3079   * @param etype
3080   *          the array element type.
3081   * @param sep
3082   *          the seperator.
3083   * @param p
3084   *          the Parser object.
3085   * @return the new Parser object.
3086   */
3087  public static <R> Parser<R[]> sepBy(final Class  <R> etype,
3088      final Parser<?> sep, final Parser<? extends R> p) {
3089    return sepBy("sepBy", etype, sep, p);
3090  }
3091
3092  /**
3093   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3094   * <p>
3095   * Parser p can succeed 0 or more times. <br>
3096   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3097   * <br>
3098   * The return values are collected in an array created by the ArrayFactory
3099   * object af.
3100   * <p>
3101   * ArrayFactory a -> Parser a -> Parser [a]
3102   * 
3103   * @param af
3104   *          the ArrayFacory object.
3105   * @param sep
3106   *          the seperator.
3107   * @param p
3108   *          the Parser object.
3109   * @return the new Parser object.
3110   */
3111  public static <R> Parser<R[]> sepBy(final ArrayFactory<R> af,
3112      final Parser<?> sep, final Parser<? extends R> p) {
3113    return sepBy("sepBy", af, sep, p);
3114  }
3115
3116  /**
3117   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3118   * <p>
3119   * Parser p can succeed 0 or more times. <br>
3120   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3121   * <br>
3122   * The return values are collected in an array created by the ArrayFactory
3123   * object af.
3124   * <p>
3125   * ArrayFactory a -> Parser a -> Parser [a]
3126   * 
3127   * @param name
3128   *          the name of the new Parser object.
3129   * @param af
3130   *          the ArrayFacory object.
3131   * @param sep
3132   *          the seperator.
3133   * @param p
3134   *          the Parser object.
3135   * @return the new Parser object.
3136   */
3137  public static <R> Parser<R[]> sepBy(final String   name,
3138      final ArrayFactory<R> af, final Parser<?> sep, final Parser<? extends R> p) {
3139    return option(name, af.createArray(0), sepBy1(af, sep, p));
3140  }
3141
3142  /**
3143   * run a series of Parser p pattern that is seperated by Parser sep pattern.
3144   * <p>
3145   * Parser p can succeed 0 or more times. <br>
3146   * For example: pattern "token, token, token, token" is sepBy(comma, token).
3147   * <br>
3148   * The return values are collected in an array whose element type is etype.
3149   * <p>
3150   * Class -> Parser a -> Parser [Object]
3151   * 
3152   * @param name
3153   *          the name of the new Parser object.
3154   * @param etype
3155   *          the array element type.
3156   * @param sep
3157   *          the seperator.
3158   * @param p
3159   *          the Parser object.
3160   * @return the new Parser object.
3161   */
3162  public static <R> Parser<R[]> sepBy(final String   name, final Class  <R> etype,
3163      final Parser<?> sep, final Parser<? extends R> p) {
3164    return sepBy(name, ArrayFactories.typedFactory(etype), sep, p);
3165  }
3166
3167  /**
3168   * First run Parser p, then run Parser sep. The return value of Parser p is
3169   * preserved as the return value. <br>
3170   * do{x<-p;sep;return x}.
3171   * <p>
3172   * Parser ? -> Parser a -> Parser a
3173   * 
3174   * @param name
3175   *          the name of the new Parser object.
3176   * @param sep
3177   *          the following parser.
3178   * @param p
3179   *          the Parser object.
3180   * @return the new Parser object.
3181   */
3182  public static <R> Parser<R> followedBy(final String   name,
3183      final Parser<?> sep, final Parser<R> p) {
3184    return new FollowedByParser<R>(name, sep, p);
3185  }
3186
3187  /**
3188   * run a series of Parser p pattern ended by Parser sep pattern.
3189   * <p>
3190   * Parser p can succeed 0 or more times. <br>
3191   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3192   * <br>
3193   * The return values are discarded.
3194   * <p>
3195   * Class -> Parser ? -> Parser _
3196   * 
3197   * @param sep
3198   *          the end seperator.
3199   * @param p
3200   *          the Parser object.
3201   * @return the new Parser object.
3202   */
3203  public static Parser<_> endBy(final Parser<?> sep, final Parser<?> p) {
3204    return endBy("endBy", sep, p);
3205  }
3206
3207  /**
3208   * run a series of Parser p pattern ended by Parser sep pattern.
3209   * <p>
3210   * Parser p can succeed 0 or more times. <br>
3211   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3212   * <br>
3213   * The return values are discarded.
3214   * <p>
3215   * Parser ? -> Parser ? -> Parser _
3216   * 
3217   * @param name
3218   *          the name of the new Parser object.
3219   * @param sep
3220   *          the end seperator.
3221   * @param p
3222   *          the Parser object.
3223   * @return the new Parser object.
3224   */
3225  public static Parser<_> endBy(final String   name, final Parser<?> sep,
3226      final Parser<?> p) {
3227    return p.followedBy(sep).many(name);
3228  }
3229
3230  /**
3231   * run a series of Parser p pattern ended by Parser sep pattern.
3232   * <p>
3233   * Parser p can succeed 0 or more times. <br>
3234   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3235   * <br>
3236   * The return values are collected in an array whose element type is etype.
3237   * <p>
3238   * Class -> Parser a -> Parser [Object]
3239   * 
3240   * @param etype
3241   *          array element type.
3242   * @param sep
3243   *          the end seperator.
3244   * @param p
3245   *          the Parser object.
3246   * @return the new Parser object.
3247   */
3248  public static <R> Parser<R[]> endBy(final Class  <R> etype,
3249      final Parser<?> sep, final Parser<? extends R> p) {
3250    return endBy("endBy", etype, sep, p);
3251  }
3252
3253  /**
3254   * run a series of Parser p pattern ended by Parser sep pattern.
3255   * <p>
3256   * Parser p can succeed 0 or more times. <br>
3257   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3258   * <br>
3259   * The return values are discarded.
3260   * <p>
3261   * ArrayFactory a -> Parser ? -> Parser a -> Parser a[]
3262   * 
3263   * @param af
3264   *          the ArrayFacory object.
3265   * @param sep
3266   *          the end seperator.
3267   * @param p
3268   *          the Parser object.
3269   * @return the new Parser object.
3270   */
3271  public static <R> Parser<R[]> endBy(final ArrayFactory<R> af,
3272      final Parser<?> sep, final Parser<? extends R> p) {
3273    return endBy("endBy", af, sep, p);
3274  }
3275
3276  /**
3277   * run a series of Parser p pattern ended by Parser sep pattern.
3278   * <p>
3279   * Parser p can succeed 0 or more times. <br>
3280   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3281   * <br>
3282   * The return values are collected in an array whose element type is etype.
3283   * <p>
3284   * Class -> Parser a -> Parser [Object]
3285   * 
3286   * @param name
3287   *          the name of the new Parser object.
3288   * @param etype
3289   *          array element type.
3290   * @param sep
3291   *          the end seperator.
3292   * @param p
3293   *          the Parser object.
3294   * @return the new Parser object.
3295   */
3296  public static <R> Parser<R[]> endBy(final String   name, final Class  <R> etype,
3297      final Parser<?> sep, final Parser<? extends R> p) {
3298    return many(name, etype, p.followedBy(sep));
3299  }
3300
3301  /**
3302   * run a series of Parser p pattern ended by Parser sep pattern.
3303   * <p>
3304   * Parser p can succeed 0 or more times. <br>
3305   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3306   * <br>
3307   * The return values are collected in an array created by the ArrayFactory
3308   * object af.
3309   * <p>
3310   * ArrayFactory a -> Parser a -> Parser [a]
3311   * 
3312   * @param name
3313   *          the name of the new Parser object.
3314   * @param af
3315   *          the ArrayFacory object.
3316   * @param sep
3317   *          the end seperator.
3318   * @param p
3319   *          the Parser object.
3320   * @return the new Parser object.
3321   */
3322  public static <R> Parser<R[]> endBy(final String   name,
3323      final ArrayFactory<R> af, final Parser<?> sep, final Parser<? extends R> p) {
3324    return many(name, af, p.followedBy(sep));
3325  }
3326
3327  /**
3328   * run a series of Parser p pattern ended by Parser sep pattern.
3329   * <p>
3330   * Parser p should succeed for at least once. <br>
3331   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3332   * <br>
3333   * The return values are discarded.
3334   * <p>
3335   * Parser ? -> Parser ? -> Parser _
3336   * 
3337   * @param sep
3338   *          the end seperator.
3339   * @param p
3340   *          the Parser object.
3341   * @return the new Parser object.
3342   */
3343  public static Parser<_> endBy1(final Parser<?> sep, final Parser<?> p) {
3344    return endBy1("endBy1", sep, p);
3345  }
3346
3347  /**
3348   * run a series of Parser p pattern ended by Parser sep pattern.
3349   * <p>
3350   * Parser p should succeed for at least once. <br>
3351   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3352   * <br>
3353   * The return values are discarded.
3354   * <p>
3355   * Parser ? -> Parser ? -> Parser _
3356   * 
3357   * @param name
3358   *          the name of the new Parser object.
3359   * @param sep
3360   *          the end seperator.
3361   * @param p
3362   *          the Parser object.
3363   * @return the new Parser object.
3364   */
3365  public static Parser<_> endBy1(final String   name, final Parser<?> sep,
3366      final Parser<?> p) {
3367    return p.followedBy(sep).many1(name);
3368  }
3369
3370  /**
3371   * run a series of Parser p pattern ended by Parser sep pattern.
3372   * <p>
3373   * Parser p should succeed for at least once. <br>
3374   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3375   * <br>
3376   * The return values are collected in an array whose element type is etype.
3377   * <p>
3378   * Class -> Parser a -> Parser [Object]
3379   * 
3380   * @param etype
3381   *          array element type.
3382   * @param sep
3383   *          the end seperator.
3384   * @param p
3385   *          the Parser object.
3386   * @return the new Parser object.
3387   */
3388  public static <R> Parser<R[]> endBy1(final Class  <R> etype,
3389      final Parser<?> sep, final Parser<? extends R> p) {
3390    return endBy1("endBy1", etype, sep, p);
3391  }
3392
3393  /**
3394   * run a series of Parser p pattern ended by Parser sep pattern.
3395   * <p>
3396   * Parser p should succeed for at least once. <br>
3397   * For example: pattern "token; token; token; token;" is endBy1(comma, token).
3398   * <br>
3399   * The return values are collected in an array created by the ArrayFactory
3400   * object af.
3401   * <p>
3402   * ArrayFactory a -> Parser a -> Parser [a]
3403   * 
3404   * @param af
3405   *          the ArrayFacory object.
3406   * @param sep
3407   *          the end seperator.
3408   * @param p
3409   *          the Parser object.
3410   * @return the new Parser object.
3411   */
3412  public static <R> Parser<R[]> endBy1(final ArrayFactory<R> af,
3413      final Parser<?> sep, final Parser<? extends R> p) {
3414    return endBy1("endBy1", af, sep, p);
3415  }
3416
3417  /**
3418   * run a series of Parser p pattern ended by Parser sep pattern.
3419   * <p>
3420   * Parser p should succeed for at least once. <br>
3421   * For example: pattern "token; token; token; token;" is endBy1(comma, token).
3422   * <br>
3423   * The return values are collected in an array created by the ArrayFactory
3424   * object af.
3425   * <p>
3426   * ArrayFactory a -> Parser a -> Parser [a]
3427   * 
3428   * @param name
3429   *          the name of the new Parser object.
3430   * @param af
3431   *          the ArrayFacory object.
3432   * @param sep
3433   *          the end seperator.
3434   * @param p
3435   *          the Parser object.
3436   * @return the new Parser object.
3437   */
3438  public static <R> Parser<R[]> endBy1(final String   name,
3439      final ArrayFactory<R> af, final Parser<?> sep, final Parser<? extends R> p) {
3440    return many(name, af, 1, p.followedBy(sep));
3441  }
3442
3443  /**
3444   * run a series of Parser p pattern ended by Parser sep pattern.
3445   * <p>
3446   * Parser p should succeed for at least once. <br>
3447   * For example: pattern "token; token; token; token;" is endBy(comma, token).
3448   * <br>
3449   * The return values are collected in an array whose element type is etype.
3450   * <p>
3451   * Class -> Parser a -> Parser [Object]
3452   * 
3453   * @param name
3454   *          the name of the new Parser object.
3455   * @param etype
3456   *          array element type.
3457   * @param sep
3458   *          the end seperator.
3459   * @param p
3460   *          the Parser object.
3461   * @return the new Parser object.
3462   */
3463  public static <R> Parser<R[]> endBy1(final String   name, final Class  <R> etype,
3464      final Parser<?> sep, final Parser<? extends R> p) {
3465    return many(name, etype, 1, p.followedBy(sep));
3466  }
3467
3468  /**
3469   * run a series of Parser p pattern that is seperated and optionally ended by
3470   * Parser sep pattern.
3471   * <p>
3472   * Parser p may succeed 0 or more times. <br>
3473   * For example: patterns "token; token; token; token" and "token;" are both
3474   * sepEndBy(semicolon, token). <br>
3475   * The return values are discarded.
3476   * <p>
3477   * Parser ? -> Parser ? -> Parser _
3478   * 
3479   * @param sep
3480   *          the end seperator.
3481   * @param p
3482   *          the Parser object.
3483   * @return the new Parser object.
3484   */
3485  public static Parser<_> sepEndBy(final Parser<?> sep, final Parser<?> p) {
3486    return sepEndBy("sepEndBy", sep, p);
3487  }
3488
3489  /**
3490   * run a series of Parser p pattern that is seperated and optionally ended by
3491   * Parser sep pattern.
3492   * <p>
3493   * Parser p may succeed 0 or more times. <br>
3494   * For example: patterns "token; token; token; token" and "token;" are both
3495   * sepEndBy(semicolon, token). <br>
3496   * The return values are collected in an array whose element type is etype.
3497   * <p>
3498   * Class -> Parser a -> Parser [Object]
3499   * 
3500   * @param etype
3501   *          the array element type.
3502   * @param sep
3503   *          the end seperator.
3504   * @param p
3505   *          the Parser object.
3506   * @return the new Parser object.
3507   */
3508  public static <R> Parser<R[]> sepEndBy(final Class  <R> etype,
3509      final Parser<?> sep, final Parser<? extends R> p) {
3510    return sepEndBy("sepEndBy", etype, sep, p);
3511  }
3512
3513  /**
3514   * run a series of Parser p pattern that is seperated and optionally ended by
3515   * Parser sep pattern.
3516   * <p>
3517   * Parser p may succeed 0 or more times. <br>
3518   * For example: patterns "token; token; token; token" and "token;" are both
3519   * sepEndBy(semicolon, token). <br>
3520   * The return values are collected in an array created by the ArrayFactory
3521   * object af.
3522   * <p>
3523   * ArrayFactory a -> Parser a -> Parser [a]
3524   * 
3525   * @param af
3526   *          the ArrayFacory object.
3527   * @param sep
3528   *          the end seperator.
3529   * @param p
3530   *          the Parser object.
3531   * @return the new Parser object.
3532   */
3533  public static <R> Parser<R[]> sepEndBy(final ArrayFactory<R> af,
3534      final Parser<?> sep, final Parser<? extends R> p) {
3535    return sepEndBy("sepEndBy", af, sep, p);
3536  }
3537
3538  /**
3539   * run a series of Parser p pattern that is seperated and optionally ended by
3540   * Parser sep pattern.
3541   * <p>
3542   * Parser p may succeed 0 or more times. <br>
3543   * For example: patterns "token; token; token; token" and "token;" are both
3544   * sepEndBy(semicolon, token). <br>
3545   * The return values are discarded.
3546   * <p>
3547   * Parser ? -> Parser ? -> Parser _
3548   * 
3549   * @param name
3550   *          the name of the new Parser object.
3551   * @param sep
3552   *          the end seperator.
3553   * @param p
3554   *          the Parser object.
3555   * @return the new Parser object.
3556   */
3557  public static Parser<_> sepEndBy(final String   name, final Parser<?> sep,
3558      final Parser<?> p) {
3559    return plus(name, sepEndBy1(sep, p), _retn_unit());
3560  }
3561
3562  /**
3563   * run a series of Parser p pattern that is seperated and optionally ended by
3564   * Parser sep pattern.
3565   * <p>
3566   * Parser p may succeed 0 or more times. <br>
3567   * For example: patterns "token; token; token; token" and "token;" are both
3568   * sepEndBy(semicolon, token). <br>
3569   * The return values are collected in an array whose element type is etype.
3570   * <p>
3571   * Class -> Parser a -> Parser [Object]
3572   * 
3573   * @param name
3574   *          the name of the new Parser object.
3575   * @param etype
3576   *          the array element type.
3577   * @param sep
3578   *          the end seperator.
3579   * @param p
3580   *          the Parser object.
3581   * @return the new Parser object.
3582   */
3583  public static <R> Parser<R[]> sepEndBy(final String   name,
3584      final Class  <R> etype, final Parser<?> sep, final Parser<? extends R> p) {
3585    return sepEndBy(name, ArrayFactories.typedFactory(etype), sep, p);
3586  }
3587
3588  /**
3589   * run a series of Parser p pattern that is seperated and optionally ended by
3590   * Parser sep pattern.
3591   * <p>
3592   * Parser p may succeed 0 or more times. <br>
3593   * For example: patterns "token; token; token; token" and "token;" are both
3594   * sepEndBy(semicolon, token). <br>
3595   * The return values are collected in an array created by the ArrayFactory
3596   * object af.
3597   * <p>
3598   * ArrayFactory a -> Parser a -> Parser [a]
3599   * 
3600   * @param name
3601   *          the name of the new Parser object.
3602   * @param af
3603   *          the ArrayFacory object.
3604   * @param sep
3605   *          the end seperator.
3606   * @param p
3607   *          the Parser object.
3608   * @return the new Parser object.
3609   */
3610  public static <R> Parser<R[]> sepEndBy(final String   name,
3611      final ArrayFactory<R> af, final Parser<?> sep, final Parser<? extends R> p) {
3612    return option(name, af.createArray(0), sepEndBy1(af, sep, p));
3613  }
3614
3615  /**
3616   * run a series of Parser p pattern that is seperated and optionally ended by
3617   * Parser sep pattern.
3618   * <p>
3619   * Parser p should succeed at least once. <br>
3620   * For example: patterns "token; token; token; token" and "token;" are both
3621   * sepEndBy1(semicolon, token). <br>
3622   * The return values are discarded.
3623   * <p>
3624   * Parser ? -> Parser ? -> Parser _
3625   * 
3626   * @param sep
3627   *          the end seperator.
3628   * @param p
3629   *          the Parser object.
3630   * @return the new Parser object.
3631   */
3632  public static Parser<_> sepEndBy1(final Parser<?> sep, final Parser<?> p) {
3633    return sepEndBy1("sepEndBy1", sep, p);
3634  }
3635
3636  /**
3637   * run a series of Parser p pattern that is seperated and optionally ended by
3638   * Parser sep pattern.
3639   * <p>
3640   * Parser p should succeed at least once. <br>
3641   * For example: patterns "token; token; token; token" and "token;" are both
3642   * sepEndBy1(semicolon, token). <br>
3643   * The return values are discarded.
3644   * <p>
3645   * Parser ? -> Parser ? -> Parser _
3646   * 
3647   * @param name
3648   *          the name of the new Parser object.
3649   * @param sep
3650   *          the end seperator.
3651   * @param p
3652   *          the Parser object.
3653   * @return the new Parser object.
3654   */
3655  public static Parser<_> sepEndBy1(final String   name, final Parser<?> sep,
3656      final Parser<?> p) {
3657    // return sepEndBy1(name, ArrayFactories.defaultFactory(), sep, p);
3658    final _ end = new _();
3659    final Catch<_> catcher = new Catch1<_>(end);
3660    final Parser<?> x = seq(sep, sum(p, raise(end)));
3661    return seq(p, tryParser(x.many(name), catcher));
3662  }
3663
3664  /**
3665   * run a series of Parser p pattern that is seperated and optionally ended by
3666   * Parser sep pattern.
3667   * <p>
3668   * Parser p should succeed at least once. <br>
3669   * For example: patterns "token; token; token; token" and "token;" are both
3670   * sepEndBy1(semicolon, token). <br>
3671   * The return values are collected in an array whose element type is etype.
3672   * <p>
3673   * Class -> Parser a -> Parser [Object]
3674   * 
3675   * @param etype
3676   *          the array element type.
3677   * @param sep
3678   *          the end seperator.
3679   * @param p
3680   *          the Parser object.
3681   * @return the new Parser object.
3682   */
3683  public static <R> Parser<R[]> sepEndBy1(final Class  <R> etype,
3684      final Parser<?> sep, final Parser<? extends R> p) {
3685    return sepEndBy1("sepEndBy1", etype, sep, p);
3686  }
3687
3688  /**
3689   * run a series of Parser p pattern that is seperated and optionally ended by
3690   * Parser sep pattern.
3691   * <p>
3692   * Parser p should succeed at least once. <br>
3693   * For example: patterns "token; token; token; token" and "token;" are both
3694   * sepEndBy1(semicolon, token). <br>
3695   * The return values are collected in an array created by the ArrayFactory
3696   * object af.
3697   * <p>
3698   * ArrayFactory a -> Parser a -> Parser [a]
3699   * 
3700   * @param af
3701   *          the ArrayFacory object.
3702   * @param sep
3703   *          the end seperator.
3704   * @param p
3705   *          the Parser object.
3706   * @return the new Parser object.
3707   */
3708  public static <R> Parser<R[]> sepEndBy1(final ArrayFactory<R> af,
3709      final Parser<?> sep, final Parser<? extends R> p) {
3710    return sepEndBy1("sepEndBy1", af, sep, p);
3711  }
3712
3713  /**
3714   * run a series of Parser p pattern that is seperated and optionally ended by
3715   * Parser sep pattern.
3716   * <p>
3717   * Parser p should succeed at least once. <br>
3718   * For example: patterns "token; token; token; token" and "token;" are both
3719   * sepEndBy1(semicolon, token). <br>
3720   * The return values are collected in an array whose element type is etype.
3721   * <p>
3722   * Class -> Parser a -> Parser [Object]
3723   * 
3724   * @param name
3725   *          the name of the new Parser object.
3726   * @param etype
3727   *          the array element type.
3728   * @param sep
3729   *          the end seperator.
3730   * @param p
3731   *          the Parser object.
3732   * @return the new Parser object.
3733   */
3734  public static <R> Parser<R[]> sepEndBy1(final String   name,
3735      final Class  <R> etype, final Parser<?> sep, final Parser<? extends R> p) {
3736    return sepEndBy1(name, ArrayFactories.typedFactory(etype), sep, p);
3737  }
3738
3739  /**
3740   * run a series of Parser p pattern that is seperated and optionally ended by
3741   * Parser sep pattern.
3742   * <p>
3743   * Parser p should succeed at least once. <br>
3744   * For example: patterns "token; token; token; token" and "token;" are both
3745   * sepEndBy1(semicolon, token). <br>
3746   * The return values are collected in an array created by the ArrayFactory
3747   * object af.
3748   * <p>
3749   * ArrayFactory a -> Parser ? -> Parser a -> Parser [a]
3750   * 
3751   * @param name
3752   *          the name of the new Parser object.
3753   * @param af
3754   *          the ArrayFacory object.
3755   * @param sep
3756   *          the end seperator.
3757   * @param p
3758   *          the Parser object.
3759   * @return the new Parser object.
3760   */
3761  public static <R> Parser<R[]> sepEndBy1(final String   name,
3762      final ArrayFactory<R> af, final Parser<?> sep, final Parser<? extends R> p) {
3763    /*
3764     * final Object end = new Object(); final Catch catcher = new Catch1(end);
3765     * final Parser x = seq(sep, plus(p, raise(end))); return bind(name, p, new
3766     * ToParser(){ public Parser toParser(final Object v){ final Parser rep =
3767     * manyAccum(name, getArrayAccumulatable(af, v), x); return tryParser(rep,
3768     * catcher); } });
3769     */
3770    return bind(name, p, new ToParser<R, R[]>() {
3771      public Parser<R[]> toParser(final R v) {
3772        return delimitedBy(name, getArrayAccumulatable(af, v), sep, p);
3773      }
3774    });
3775  }
3776
3777  private static <E1, E extends E1, R, R1 extends R> Parser<R> delimitedBy(
3778      final String   name, final Accumulatable<E1, R1> accm,
3779      final Parser<?> delim, final Parser<E> p) {
3780    return new DelimitedByParser<R, E1, R1, E>(name, p, accm, delim);
3781  }
3782
3783  /**
3784   * Runs Parser p for n times. Return values are discarded.
3785   * <p>
3786   * int -> Parser ? -> Parser _
3787   * 
3788   * @param name
3789   *          the name of the new Parser object.
3790   * @param n
3791   *          the number of times to run.
3792   * @param p
3793   *          the Parser object.
3794   * @return the new Parser object.
3795   */
3796  public static Parser<_> repeat(final String   name, final int n,
3797      final Parser<?> p) {
3798    return new RepeatParser(name, p, n);
3799  }
3800
3801  /**
3802   * Runs Parser p for n times, collect the return values in an array whose
3803   * element type is etype.
3804   * <p>
3805   * Class -> int -> Parser a -> Parser [Object]
3806   * 
3807   * @param name
3808   *          the name of the new Parser object.
3809   * @param etype
3810   *          the array element type.
3811   * @param n
3812   *          the number of times to run.
3813   * @param p
3814   *          the Parser object.
3815   * @return the new Parser object.
3816   */
3817  public static <R> Parser<R[]> repeat(final String   name, final Class  <R> etype,
3818      final int n, final Parser<? extends R> p) {
3819    return repeat(name, ArrayFactories.typedFactory(etype), n, p);
3820  }
3821
3822  /**
3823   * Runs Parser p for n times, collect the return values in an array created by
3824   * the ArrayFactory object.
3825   * <p>
3826   * ArrayFactory a -> int -> Parser a -> Parser [a]
3827   * 
3828   * @param name
3829   *          the name of the new Parser object.
3830   * @param af
3831   *          the ArrayFactory object.
3832   * @param n
3833   *          the number of times to run.
3834   * @param p
3835   *          the Parser object.
3836   * @return the new Parser object.
3837   */
3838  public static <R> Parser<R[]> repeat(final String   name,
3839      final ArrayFactory<R> af, final int n, final Parser<? extends R> p) {
3840    return new RepeatArrayParser<R>(name, af, n, p);
3841  }
3842
3843  /**
3844   * Runs Parser op for 0 or more times greedily. Then run Parser p. The Map
3845   * object returned from op are applied from right to left to the return value
3846   * of p. <br>
3847   * prefix(op, p) is equivalent to op* p in EBNF
3848   * <p>
3849   * Parser (a->a) -> Parser a -> Parser a
3850   * 
3851   * @param op
3852   *          the operator.
3853   * @param p
3854   *          the operand.
3855   * @return the new Parser object.
3856   */
3857  public static <T> Parser<T> prefix(
3858      final Parser<? extends Map<? super T, T>> op, final Parser<? extends T> p) {
3859    return prefix("prefix", op, p);
3860  }
3861
3862  private static <T> T postfix_thread_maps(T a, final Map<? super T, T>[] ms) {
3863    for (int i = 0; i < ms.length; i++) {
3864      final Map<? super T, T> m = ms[i];
3865      a = m.map(a);
3866    }
3867    return a;
3868  }
3869
3870  private static <T> T prefix_thread_maps(T a, final Map<? super T, T>[] ms) {
3871    for (int i = ms.length - 1; i >= 0; i--) {
3872      final Map<? super T, T> m = ms[i];
3873      a = m.map(a);
3874    }
3875    return a;
3876  }
3877
3878  private static final Map2 _prefix_map2 = _get_prefix_map2();
3879
3880  private static <T> Map2<Map<? super T, T>[], T, T> _get_prefix_map2() {
3881    return new Map2<Map<? super T, T>[], T, T>() {
3882      public T map(final Map<? super T, T>[] ops, final T a) {
3883        return prefix_thread_maps(a, ops);
3884      }
3885    };
3886  }
3887
3888  /**
3889   * Runs Parser op for 0 or more times greedily. Then run Parser p. The Map
3890   * object returned from op are applied from right to left to the return value
3891   * of p. <br>
3892   * prefix(op, p) is equivalent to op* p in EBNF
3893   * <p>
3894   * Parser (a->a) -> Parser a -> Parser a
3895   * 
3896   * @param name
3897   *          the name of the new Parser object.
3898   * @param op
3899   *          the operator.
3900   * @param p
3901   *          the operand.
3902   * @return the new Parser object.
3903   */
3904  public static <T> Parser<T> prefix(final String   name,
3905      final Parser<? extends Map<? super T, T>> op, final Parser<? extends T> p) {
3906    final Parser<Map> _op = op.convert();// because Map<...>.class is not
3907                                          // supported.
3908    return map2(name, _op.many("prefix", Map.class), p, _prefix_map2);
3909  }
3910
3911  /**
3912   * Runs Parser p and then run Parser op for 0 or more times greedily. The Map
3913   * object returned from op are applied from left to right to the return value
3914   * of p. <br>
3915   * postfix(op, p) is equivalent to p op* in EBNF
3916   * <p>
3917   * Parser (a->a) -> Parser a -> Parser a
3918   * 
3919   * @param op
3920   *          the operator.
3921   * @param p
3922   *          the operand.
3923   * @return the new Parser object.
3924   */
3925  public static <T> Parser<T> postfix(
3926      final Parser<? extends Map<? super T, T>> op, final Parser<? extends T> p) {
3927    return postfix("postfix", op, p);
3928  }
3929
3930  private static final Map2 _postfix_map2 = _get_postfix_map2();
3931
3932  private static <T> Map2<T, Map<? super T, T>[], T> _get_postfix_map2() {
3933    return new Map2<T, Map<? super T, T>[], T>() {
3934      public T map(final T a, final Map<? super T, T>[] ops) {
3935        return postfix_thread_maps(a, ops);
3936      }
3937    };
3938  }
3939
3940  /**
3941   * Runs Parser p and then run Parser op for 0 or more times greedily. The Map
3942   * object returned from op are applied from left to right to the return value
3943   * of p. <br>
3944   * postfix(op, p) is equivalent to p op* in EBNF
3945   * <p>
3946   * Parser (a->a) -> Parser a -> Parser a
3947   * 
3948   * @param name
3949   *          the name of the new Parser object.
3950   * @param op
3951   *          the operator.
3952   * @param p
3953   *          the operand.
3954   * @return the new Parser object.
3955   */
3956  public static <T> Parser<T> postfix(final String   name,
3957      final Parser<? extends Map<? super T, T>> op, final Parser<? extends T> p) {
3958    final Parser<Map> _op = op.convert();
3959    final Parser ops = _op.many(name, Map.class);
3960    return map2(name, p, ops, _postfix_map2);
3961  }
3962
3963  /**
3964   * Non-associative infix operator. Runs Parser p and then run Parser op and
3965   * Parser p optionally. The Map2 object returned from op is applied to the
3966   * return values of the two p pattern, if any. <br>
3967   * infixn(op, p) is equivalent to p (op p)? in EBNF
3968   * <p>
3969   * Parser (a->a->a) -> Parser a -> Parser a
3970   * 
3971   * @param op
3972   *          the operator.
3973   * @param operand
3974   *          the operand.
3975   * @return the new Parser object.
3976   */
3977  public static <T> Parser<T> infixn(
3978      final Parser<? extends Map2<? super T, ? super T, T>> op,
3979      final Parser<? extends T> operand) {
3980    return infixn("infixn", op, operand);
3981  }
3982
3983  /**
3984   * Non-associative infix operator. Runs Parser p and then run Parser op and
3985   * Parser p optionally. The Map2 object returned from op is applied to the
3986   * return values of the two p pattern, if any. <br>
3987   * infixn(op, p) is equivalent to p (op p)? in EBNF
3988   * <p>
3989   * Parser (a->a->a) -> Parser a -> Parser a
3990   * 
3991   * @param name
3992   *          the name of the new Parser object.
3993   * @param op
3994   *          the operator.
3995   * @param operand
3996   *          the operand.
3997   * @return the new Parser object.
3998   */
3999  public static <T> Parser<T> infixn(final String   name,
4000      final Parser<? extends Map2<? super T, ? super T, T>> op,
4001      final Parser<? extends T> operand) {
4002    return operand.bind(name, new ToParser<T, T>() {
4003      public Parser<T> toParser(final T a) {
4004        final Parser<T> shift = op.and(operand,
4005            new Map2<Map2<? super T, ? super T, T>, T, T>() {
4006              public T map(final Map2<? super T, ? super T, T> m2, final T b) {
4007                return m2.map(a, b);
4008              }
4009            });
4010        return Parsers.plus(shift, retn(a));
4011      }
4012    });
4013  }
4014
4015  /**
4016   * Left associative infix operator. Runs Parser p and then run Parser op and
4017   * Parser p for 0 or more times greedily. The Map object returned from op are
4018   * applied from left to right to the return value of p. <br>
4019   * for example: a+b+c+d is evaluated as (((a+b)+c)+d). <br>
4020   * infixl(op, p) is equivalent to p (op p)* in EBNF.
4021   * <p>
4022   * Parser (a->a->a) -> Parser a -> Parser a
4023   * 
4024   * @param op
4025   *          the operator.
4026   * @param p
4027   *          the operand.
4028   * @return the new Parser object.
4029   */
4030  public static <T> Parser<T> infixl(
4031      final Parser<? extends Map2<? super T, ? super T, T>> op,
4032      final Parser<? extends T> p) {
4033    return infixl("infixl", op, p);
4034  }
4035
4036  /**
4037   * Left associative infix operator. Runs Parser p and then run Parser op and
4038   * Parser p for 0 or more times greedily. The Map object returned from op are
4039   * applied from left to right to the return values of p. <br>
4040   * for example: a+b+c+d is evaluated as (((a+b)+c)+d). <br>
4041   * infixl(op, p) is equivalent to p (op p)* in EBNF.
4042   * <p>
4043   * Parser (a->a->a) -> Parser a -> Parser a
4044   * 
4045   * @param name
4046   *          the name of the new Parser object.
4047   * @param op
4048   *          the operator.
4049   * @param p
4050   *          the operand.
4051   * @return the new Parser object.
4052   */
4053  public static <T> Parser<T> infixl(final String   name,
4054      final Parser<? extends Map2<? super T, ? super T, T>> op,
4055      final Parser<? extends T> p) {
4056    final Parser op_and_rhs = op_rhs(op, p);
4057    return bind(name, p, new ToParser<T, T>() {
4058      public Parser<T> toParser(final T a) {
4059        return manyAccum("infixl", lassocAccumulatable(a), op_and_rhs);
4060      }
4061    });
4062    // return postfix(name, op_rhs(op, p), p); //this uses a temporary array.
4063  }
4064
4065  /**
4066   * Right associative infix operator. Runs Parser p and then run Parser op and
4067   * Parser p for 0 or more times greedily. The Map object returned from op are
4068   * applied from right to left to the return values of p. <br>
4069   * for example: a+b+c+d is evaluated as a+(b+(c+d)). <br>
4070   * infixr(op, p) is equivalent to p (op p)* in EBNF.
4071   * <p>
4072   * Parser (a->a->a) -> Parser a -> Parser a
4073   * 
4074   * @param op
4075   *          the operator.
4076   * @param p
4077   *          the operand.
4078   * @return the new Parser object.
4079   */
4080  public static <T> Parser<T> infixr(
4081      final Parser<? extends Map2<? super T, ? super T, T>> op,
4082      final Parser<? extends T> p) {
4083    return infixr("infixr", op, p);
4084  }
4085
4086  // 1+ 1+ 1+ ..... 1
4087  private static final class Rhs<T> {
4088    final Map2<? super T, ? super T, T> op;
4089
4090    final T rhs;
4091
4092    Rhs(final Map2<? super T, ? super T, T> op, final T rhs) {
4093      this.op = op;
4094      this.rhs = rhs;
4095    }
4096  }
4097
4098  private static final Map2 _infixr_map2 = _get_infixr_map2();
4099
4100  private static <T> Map2<Map2<? super T, ? super T, T>, T, Rhs<T>> _get_infixr_map2() {
4101    return new Map2<Map2<? super T, ? super T, T>, T, Rhs<T>>() {
4102      public Rhs<T> map(final Map2<? super T, ? super T, T> m2, final T b) {
4103        return new Rhs<T>(m2, b);
4104      }
4105    };
4106  }
4107
4108  private static final Map2 _calc_infixr = _get_calc_infixr();
4109
4110  private static final <T> Map2<T, Rhs<T>[], T> _get_calc_infixr() {
4111    return new Map2<T, Rhs<T>[], T>() {
4112      public T map(final T a, final Rhs<T>[] rhss) {
4113        if (rhss.length == 0)
4114          return a;
4115        T o2 = rhss[rhss.length - 1].rhs;
4116        for (int i = rhss.length - 1; i > 0; i--) {
4117          final Map2<? super T, ? super T, T> m2 = rhss[i].op;
4118          final T o1 = rhss[i - 1].rhs;
4119          o2 = m2.map(o1, o2);
4120        }
4121        return rhss[0].op.map(a, o2);
4122      }
4123    };
4124  }
4125
4126  /**
4127   * Right associative infix operator. Runs Parser p and then run Parser op and
4128   * Parser p for 0 or more times greedily. The Map object returned from op are
4129   * applied from right to left to the return values of p. <br>
4130   * for example: a+b+c+d is evaluated as a+(b+(c+d)). <br>
4131   * infixr(op, p) is equivalent to p (op p)* in EBNF.
4132   * <p>
4133   * Parser (a->a->a) -> Parser a -> Parser a
4134   * 
4135   * @param name
4136   *          the name of the new Parser object.
4137   * @param op
4138   *          the operator.
4139   * @param p
4140   *          the operand.
4141   * @return the new Parser object.
4142   */
4143  public static <T> Parser<T> infixr(final String   name,
4144      final Parser<? extends Map2<? super T, ? super T, T>> op,
4145      final Parser<? extends T> p) {
4146    final Parser<Rhs> op_rhs2 = map2(op, p, _infixr_map2);
4147    final Parser<Rhs[]> tmp = op_rhs2.many(name, Rhs.class);// doesn't like
4148                                                            // Rhs<T>.class?
4149    return map2(p, tmp, _calc_infixr);
4150  }
4151
4152  /**
4153   * Consumes a token. The token is used as the return value of the parser.
4154   * <p>
4155   * Parser Token
4156   * 
4157   * @return the Parser object.
4158   */
4159  public static Parser<Tok> anyToken() {
4160    return anyToken("anyToken");
4161  }
4162
4163  private static final FromToken<Tok> _any_tok = new FromToken<Tok>() {
4164    public Tok fromToken(final Tok tok) {
4165      return tok;
4166    }
4167  };
4168
4169  /**
4170   * Consumes a token. The {@link Tok} is used as the return value
4171   * of the parser.
4172   * <p>
4173   * Parser Tok
4174   * 
4175   * @param name
4176   *          the name of the Parser object.
4177   * @return the Parser object.
4178   */
4179  public static Parser<Tok> anyToken(final String   name) {
4180    return token(name, _any_tok);
4181  }
4182
4183  private static <T> Accumulatable<Map<? super T, ? extends T>, T> lassocAccumulatable(
4184      final T init) {
4185    return new Accumulatable<Map<? super T, ? extends T>, T>() {
4186      public Accumulator<Map<? super T, ? extends T>, T> getAccumulator() {
4187        return new Accumulator<Map<? super T, ? extends T>, T>() {
4188          private T a = init;
4189
4190          public void accumulate(final Map<? super T, ? extends T> m) {
4191            a = m.map(a);
4192          }
4193
4194          public T getResult() {
4195            return a;
4196          }
4197        };
4198      }
4199    };
4200  }
4201
4202  private static final Map2 _op_rhs_map2 = _getOperatorRhsMap2();
4203
4204  private static <A, B, R> Map2<Map2<A, B, R>, B, Map<A, R>> _getOperatorRhsMap2() {
4205    return new Map2<Map2<A, B, R>, B, Map<A, R>>() {
4206      public Map<A, R> map(final Map2<A, B, R> op, final B b) {
4207        return new Map<A, R>() {
4208          public R map(final A a) {
4209            return op.map(a, b);
4210          }
4211        };
4212      }
4213    };
4214  }
4215
4216  // Parser Map
4217  private static <B, R, Op extends Map2<? super B, ? super B, R>> Parser/* <Map<A,R>> */op_rhs(
4218      final Parser<Op> op, final Parser<B> rhs) {
4219    return map2(op, rhs, _op_rhs_map2);
4220  }
4221
4222  private static <From> boolean runToParser(final ToParser<? super From, ?> p,
4223      final ParseContext state) {
4224    return p.toParser((From) state.getReturn()).parse(state);
4225  }
4226
4227  private static <From> boolean runNext(final ParseContext s,
4228      final ToParser<? super From, ?> p) {
4229    return runToParser(p, s);
4230  }
4231
4232  private static <E, T extends E> Accumulatable<T, E[]> getArrayAccumulatable(
4233      final ArrayFactory<E> af) {
4234    return new Accumulatable<T, E[]>() {
4235      public Accumulator<T, E[]> getAccumulator() {
4236        return new ArrayAccumulator<E, T>(af, new java.util.ArrayList  <T>());
4237      }
4238    };
4239  }
4240
4241  private static <E, T extends E> Accumulatable<T, E[]> getArrayAccumulatable(
4242      final ArrayFactory<E> af, final T init) {
4243    return new Accumulatable<T, E[]>() {
4244      public Accumulator<T, E[]> getAccumulator() {
4245        final java.util.ArrayList  <T> a = new java.util.ArrayList  <T>();
4246        a.add(init);
4247        return new ArrayAccumulator<E, T>(af, a);
4248      }
4249    };
4250  }
4251
4252  private static final Object  [] _empty_array = new Object  [0];
4253  private static final Parser _retn_null = retn(null);
4254  private static final Parser<_> _retn_unit(){
4255    return _retn_null;
4256  }
4257}
4258
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags