Parser


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  import java.io.PrintWriter  ;
16  
17  import jfun.parsec.trace.Trace;
18  import jfun.parsec.trace.Traces;
19  
20  
21  /**
22   * <p>
23   * A parser runs either on character level or token level.
24   * It takes as input a CharSequence object or a Tok[] array,
25   * recognizes certain patterns and returns a value.
26   * </p>
27   * <p>
28   * <ul>
29   * <li>A character level parser object that simply recognizes input but not returning token is called a scanner.</li>
30   * <li>A character level parser object that recognizes input and returns a token object is called a lexer.</li>
31   * <li>A token level parser is called a parser. </li>
32   * <li>a parser object can fail, or "return" a value via the retn() function.</li>
33   * <li>a parser object can throw pseudo-exception object for other parsers to catch.</li>
34   * <li>a parser object represents a parsing computation algorithm, not the actual parsing process.</li>
35   * <li>a parser object is executed by Parsers.runParser() function.</li>
36   * </ul>
37   * </p>
38   * @author Ben Yu
39   *
40   * 2004-11-11
41   */
42  public abstract class Parser<Type> implements java.io.Serializable  {
43    private final ParsingFrame getErrorFrame(ParseContext ctxt, int ind){
44      return new ParsingFrame(ctxt.getModuleName(),
45          ctxt.getIndex(),
46          ctxt.getPositionMap().getPos(ind), this);
47    }
48    private RuntimeException   wrapException(Throwable   e, ParseContext ctxt,
49        int ind){
50      if(e instanceof UserException){
51        return (UserException)e;
52      }
53      else if(e instanceof ParserException){
54        final ParserException pe = ((ParserException)e);
55        pe.pushFrame(getErrorFrame(ctxt, ind));
56        return pe;
57      }
58      else{
59        final ParserException pe = 
60          new ParserException(e, null,
61              ctxt.getModuleName(),
62              ctxt.getPositionMap().getPos(ind));
63        return pe;
64      }
65    }
66    final boolean parse(final ParseContext ctxt){
67      final int ind = ctxt.getIndex();
68      try{
69        return apply(ctxt);
70      }
71      catch(RuntimeException   e){
72        throw wrapException(e, ctxt, ind);
73      }
74    }
75    abstract boolean apply(final ParseContext ctxt);
76    boolean apply(final ParseContext ctxt, final int look_ahead){
77      return apply(ctxt);
78    }
79    
80    final boolean parse(final ParseContext ctxt, final int look_ahead){
81      final int ind = ctxt.getIndex();
82      try{
83        return apply(ctxt, look_ahead);
84      }
85      catch(RuntimeException   e){
86        throw wrapException(e, ctxt, ind);
87      }
88    }
89    /*{
90      throw new IllegalStateException("lookahead not in effect.");
91    }*/
92    private final String   name;
93    Parser(final String   n){
94      this.name = n;
95    }
96    final String   getName(){return name;}
97    public String   toString(){return name;}
98    /**
99     * Create a Parser object that traces the parsing result of this parser.
100    * Only effective when {@link Parsers#isDebugEnabled()} returns true.
101    * @param trc the Trace object.
102    * @return the new Parser object.
103    * @since version 1.1
104    */
105   public final Parser<Type> trace(Trace<? super Type> trc){
106     if(!Parsers.isDebugEnabled()) return this;
107     return new TracedParser(name, this, trc);
108   }
109   /**
110    * Create a Parser object that traces the parsing error of this parser when it fails.
111    * Only effective when {@link Parsers#isDebugEnabled()} returns true.
112    * @param id the identifier of the parser object in the trace message.
113    * @param min_steps the minimal logical steps consumed to trigger the trace message.
114    * @return the new Parser object.
115    * @since version 1.1
116    */
117   public final Parser<Type> printError(String   id, final int min_steps){
118     return trace(Traces.printError(id, new PrintWriter  (System.out), min_steps));
119   }
120   /**
121    * Create a Parser object that traces the parsing error of this parser when it fails.
122    * Only effective when {@link Parsers#isDebugEnabled()} returns true.
123    * The trace message is triggered only when 1 or more logical steps are consumed.
124    * @param id the identifier of the parser object in the trace message.
125    * @return the new Parser object.
126    * @since version 1.1
127    */
128   public final Parser<Type> printError(String   id){
129     return printError(id, 1);
130   }
131   /**
132    * Create a Parser object that traces the parsing result of this parser when it succeeds.
133    * Only effective when {@link Parsers#isDebugEnabled()} returns true.
134    * @param id the identifier of the parser object in the trace message.
135    * @return the new Parser object.
136    * @since version 1.1
137    */
138   public final Parser<Type> printResult(String   id){
139     return trace(Traces.printResult(id, new PrintWriter  (System.out)));
140   }
141   /**
142    * Create a Parser object that traces the parsing result of this parser when it terminates.
143    * Only effective when {@link Parsers#isDebugEnabled()} returns true.
144    * @param id the identifier of the parser object in the trace message.
145    * @return the new Parser object.
146    * @since version 1.1
147    */
148   public final Parser<Type> printTrace(String   id){
149     return trace(Traces.printTrace(id, new PrintWriter  (System.out)));
150   }
151   /**
152    * if this parser succeeds, the returned value gets passed on to tp.
153    * The monadic bind (product) operation.
154    * @param tp the next step.
155    * @return the new Parser.
156    */
157   public final <To> Parser<To> bind(final ToParser<? super Type,To> tp){
158     return Parsers.bind("bind", this, tp);
159   }
160   /**
161    * if this parser succeeds, the returned value gets passed on to tp.
162    * The monadic bind (product or >>=) operation. 
163    * @param name the name of the new parser.
164    * @param tp the next step.
165    * @return the new Parser.
166    */
167   public final <To> Parser<To> bind(final String   name, 
168       final ToParser<? super Type, To> tp){
169     return Parsers.bind(name, this, tp);
170   }
171   /**
172    * if this parser succeeds,
173    * the returned value is discarded and the next parser is excuted.
174    * The monadic seq (>>) operation. 
175    * @param p the next parser.
176    * @return the new Parser.
177    */
178   public final <R> Parser<R> seq(final Parser<R> p){
179     return Parsers.seq("seq", this, p);
180   }
181   /**
182    * if this parser succeeds,
183    * the returned value is discarded and the next parser is excuted.
184    * The monadic seq (>>) operation. 
185    * @param name the name of the new parser.
186    * @param p the next parser.
187    * @return the new Parser.
188    */
189   public final <R> Parser<R> seq(final String   name, final Parser<R> p){
190     return Parsers.seq(name, this, p);
191   }
192   
193   /**
194    * Run Parser 'this' for n times. 
195    * The return values are discarded.
196    * @param n the number of times to run.
197    * @return the new Parser object.
198    */
199   public final Parser<_> repeat(final int n){
200     return Parsers.repeat("repeat", n, this);
201   }
202   /**
203    * Run Parser 'this' for n times, collect the return values in an array
204    * whose element type is etype.
205    * @param etype the array element type.
206    * @param n the number of times to run.
207    * @return the new Parser object.
208    */
209   public final Parser<Type[]> repeat(final Class  <Type> etype, final int n){
210     return Parsers.repeat("repeat", etype, n, this);
211   }
212   /**
213    * Run Parser 'this' for n times, collect the return values in an array
214    * created by the ArrayFactory object.
215    * @param af the ArrayFactory object.
216    * @param n the number of times to run.
217    * @return the new Parser object.
218    */
219   public final Parser<Type[]> repeat(final ArrayFactory<Type> af, final int n){
220     return Parsers.repeat("repeat", af, n, this);
221   }
222 
223   /**
224    * Run Parser 'this' for n times.
225    * The return values are discarded.
226    * @param name the name of the new Parser object.
227    * @param n the number of times to run.
228    * @return the new Parser object.
229    */
230   public final Parser<_> repeat(final String   name, final int n){
231     return Parsers.repeat(name, n, this);
232   }
233   /**
234    * Run Parser 'this' for n times, collect the return values in an array
235    * whose element type is etype.
236    * @param name the name of the new Parser object.
237    * @param etype the array element type.
238    * @param n the number of times to run.
239    * @return the new Parser object.
240    */
241   public final Parser<Type[]> repeat(final String   name, final Class  <Type> etype, final int n){
242     return Parsers.repeat(name, etype, n, this);
243   }
244   /**
245    * Run Parser 'this' for n times, collect the return values in an array
246    * created by the ArrayFactory object.
247    * @param name the name of the new Parser object.
248    * @param af the ArrayFactory object.
249    * @param n the number of times to run.
250    * @return the new Parser object.
251    */
252   public final Parser<Type[]> repeat(final String   name, final ArrayFactory<Type> af, final int n){
253     return Parsers.repeat(name, af, n, this);
254   }
255   /**
256    * p.many(af) is equivalent to p* in EBNF.
257    * The return values are collected and returned in an array
258    * created by the ArrayFactory object.
259    * @param af the ArrayFactory.
260    * @return the new Parser.
261    */
262   public final Parser<Type[]> many(final ArrayFactory<Type> af){
263     return Parsers.many("many", af, this);
264   }
265   /**
266    * p.many(name, af) is equivalent to p* in EBNF.
267    * The return values are collected and returned in an array created by the ArrayFactory object.
268    * @param name the name of the new parser.
269    * @param af the ArrayFactory.
270    * @return the new Parser.
271    */
272   public final Parser<Type[]> many(final String   name, final ArrayFactory<Type> af){
273     return Parsers.many(name, af, this);
274   }
275   /**
276    * p.many(elem_type) is equivalent to p* in EBNF.
277    * The return values are collected and returned in an array.
278    * @param elem_type the element type of the result array.
279    * @return the new Parser.
280    */
281   public final Parser<Type[]> many(final Class  <Type> elem_type){
282     return Parsers.many("many", elem_type, this);
283   }
284   /**
285    * p.many(name, elem_type) is equivalent to p* in EBNF.
286    * The return values are collected and returned in an array.
287    * @param name the name of the new parser.
288    * @param elem_type the element type of the result array.
289    * @return the new Parser.
290    */
291   public final Parser<Type[]> many(final String   name, final Class  <Type> elem_type){
292     return Parsers.many(name, elem_type, this);
293   }
294   /**
295    * p.many() is equivalent to p* in EBNF.
296    * The return values are discarded.
297    * @return the new Parser.
298    */
299   public final Parser<_> many(){
300     return Parsers.many("many", this);
301   }
302   /**
303    * p.many(name) is equivalent to p* in EBNF.
304    * The return values are discarded.
305    * @param name the name of the new parser.
306    * @return the new Parser.
307    */
308   public final Parser<_> many(final String   name){
309     return Parsers.many(name, this);
310   }
311 
312   
313 
314   
315   
316   /**
317    * Runs this parser greedily for at least min times.
318    * The return values are collected and returned in an array created by the ArrayFactory object.
319    * @param af the ArrayFactory.
320    * @param min the minimal number of times to run this parser.
321    * @return the new Parser.
322    */
323   public final Parser<Type[]> many(final ArrayFactory<Type> af, final int min){
324     return Parsers.many("many", af, min, this);
325   }
326   /**
327    * Runs this parser greedily for at least min times.
328    * The return values are collected and returned in an array created by the ArrayFactory object.
329    * @param name the name of the new parser.
330    * @param af the ArrayFactory.
331    * @param min the minimal number of times to run this parser.
332    * @return the new Parser.
333    */
334   public final Parser<Type[]> many(final String   name, final ArrayFactory<Type> af, final int min){
335     return Parsers.many(name, af, min, this);
336   }
337   /**
338    * Runs this parser greedily for at least min times.
339    * The return values are collected and returned in an array.
340    * @param elem_type the element type of the result array.
341    * @param min the minimal number of times to run this parser.
342    * @return the new Parser.
343    */
344   public final Parser<Type[]> many(final Class  <Type> elem_type, final int min){
345     return Parsers.many("many", elem_type, min, this);
346   }
347   /**
348    * Runs this parser greedily for at least min times.
349    * The return values are collected and returned in an array.
350    * @param name the name of the new parser.
351    * @param elem_type the element type of the result array.
352    * @param min the minimal number of times to run this parser.
353    * @return the new Parser.
354    */
355   public final Parser<Type[]> many(final String   name, final Class  <Type> elem_type, final int min){
356     return Parsers.many(name, elem_type, min, this);
357   }
358   /**
359    * Runs this parser greedily for at least min times.
360    * The return values are discarded.
361    * @return the new Parser.
362    */
363   public final Parser<_> many(final int min){
364     return Parsers.many("many", min, this);
365   }
366   /**
367    * Runs this parser greedily for at least min times.
368    * The return values are discarded.
369    * @param name the name of the new parser.
370    * @param min the minimal number of times to run this parser.
371    * @return the new Parser.
372    */
373   public final Parser<_> many(final String   name, final int min){
374     return Parsers.many(name, min, this);
375   }
376 
377   
378   
379   
380   
381   /**
382    * Runs this for at least min times and at most max times.
383    * The return values are collected and returned in an array created by the ArrayFactory object.
384    * @param af the ArrayFactory.
385    * @param min the minimal number of times to run this parser.
386    * @param max the maximal number of times to run this parser.
387    * @return the new Parser.
388    */
389   public final Parser<Type[]> some(final ArrayFactory<Type> af, final int min, final int max){
390     return Parsers.some("some", af, min, max, this);
391   }
392   /**
393    * Runs this for at least min times and at most max times.
394    * The return values are collected and returned in an array
395    * created by the ArrayFactory object.
396    * @param name the name of the new parser.
397    * @param af the ArrayFactory.
398    * @param min the minimal number of times to run this parser.
399    * @param max the maximal number of times to run this parser.
400    * @return the new Parser.
401    */
402   public final Parser<Type[]> some(final String   name, final ArrayFactory<Type> af, final int min, final int max){
403     return Parsers.some(name, af, min, max, this);
404   }
405   /**
406    * Runs this for at least min times and at most max times.
407    * The return values are collected and returned in an array
408    * whose element type is elem_type.
409    * @param elem_type the element type of the result array.
410    * @param min the minimal number of times to run this parser.
411    * @param max the maximal number of times to run this parser.
412    * @return the new Parser.
413    */
414   public final Parser<Type[]> some(final Class  <Type> elem_type, final int min, final int max){
415     return Parsers.some("some", elem_type, min, max, this);
416   }
417   /**
418    * Runs this for at least min times and at most max times.
419    * The return values are collected and returned in an array
420    * whose element type is elem_type.
421    * @param elem_type the element type of the result array.
422    * @param min the minimal number of times to run this parser.
423    * @param max the maximal number of times to run this parser.
424    * @return the new Parser.
425    */
426   public final Parser<Type[]> some(final String   name, final Class  <Type> elem_type, final int min, final int max){
427     return Parsers.some(name, elem_type, min, max, this);
428   }
429   /**
430    * Runs this for at least min times and at most max times.
431    * The return values are discarded.
432    * @param min the minimal number of times to run this parser.
433    * @param max the maximal number of times to run this parser.
434    * @return the new Parser.
435    */
436   public final Parser<_> some(final int min, final int max){
437     return Parsers.some("some", min, max, this);
438   }
439   /**
440    * Runs this for at least min times and at most max times.
441    * The return values are discarded.
442    * @param name the name of the new parser.
443    * @param min the minimal number of times to run this parser.
444    * @param max the maximal number of times to run this parser.
445    * @return the new Parser.
446    */
447   public final Parser<_> some(final String   name, final int min, final int max){
448     return Parsers.some(name, min, max, this);
449   }
450   
451   /**
452    * Runs this for up to max times.
453    * The return values are discarded.
454    * @param max the maximal number of times to run.
455    * @return the new Parser.
456    */
457   public final Parser<_> some(final int max){
458     return Parsers.some("some", max, this);
459   }
460   /**
461    * Runs this for up to max times.
462    * The return values are collected and returned in an array
463    * whose element type is etype.
464    * @param etype the element type of the result array.
465    * @param max the maximal number times to run.
466    * @return the new Parser.
467    */
468   public final Parser<Type[]> some(final Class  <Type> etype, final int max){
469     return Parsers.some("some", etype, max, this);
470   }
471   /**
472    * Runs this for up to max times.
473    * The return values are collected and returned in an array
474    * created by af.
475    * @param max the maximal number of times to run.
476    * @return the new Parser.
477    */
478   public final Parser<Type[]> some(final ArrayFactory<Type> af, final int max){
479     return Parsers.some("some", af, max, this);
480   }
481   /**
482    * Runs this for up to max times.
483    * The return values are discarded.
484    * @param name the name of the new parser.
485    * @param max the maximal number times to run.
486    * @return the new Parser.
487    */
488   public final Parser<_> some(final String   name, final int max){
489     return Parsers.some(name, max, this);
490   }
491   /**
492    * Runs this for up to max times.
493    * The return values are collected and returned in an array
494    * whose element type is etype.
495    * @param name the name of the new parser.
496    * @param etype the element type of the result array.
497    * @param max the maximal number of times to run.
498    * @return the new Parser.
499    */
500   public final Parser<Type[]> some(final String   name, final Class  <Type> etype, final int max){
501     return Parsers.some(name, etype, max, this);
502   }
503   /**
504    * Runs this for up to max times.
505    * The return values are collected and returned in an array
506    * created by af.
507    * @param name the name of the new parser.
508    * @param af the ArrayFactory object.
509    * @param max the maximal number of times to run.
510    * @return the new Parser.
511    */
512   public final Parser<Type[]> some(final String   name, final ArrayFactory<Type> af, final int max){
513     return Parsers.some(name, af, max, this);
514   }
515   /**
516    * p.many1(elem_type) is equivalent to p+ in EBNF.
517    * The return values are collected and returned in an array
518    * whose element type is elem_type.
519    * @param elem_type the element type of the result array.
520    * @return the new Parser.
521    */
522   public final Parser<Type[]> many1(final Class  <Type> elem_type){
523     return Parsers.many("many1", elem_type, 1, this);
524   }
525   /**
526    * p.many1(name, elem_type) is equivalent to p+ in EBNF.
527    * The return values are collected and returned in an array
528    * whose element type is elem_type.
529    * @param name the name of the new parser.
530    * @param elem_type the element type of the result array.
531    * @return the new Parser.
532    */
533   public final Parser<Type[]> many1(final String   name, final Class  <Type> elem_type){
534     return Parsers.many(name, elem_type, 1, this);
535   }
536   /**
537    * p.many1(af) is equivalent to p+ in EBNF.
538    * The return values are collected and returned in an array
539    * created by the ArrayFactory object.
540    * @param af the ArrayFactory.
541    * @return the new Parser.
542    */
543   public final Parser<Type[]> many1(final ArrayFactory<Type> af){
544     return Parsers.many("many1", af, 1, this);
545   }
546   /**
547    * p.many1(name, af) is equivalent to p+ in EBNF.
548    * The return values are collected and returned in an array
549    * created by the ArrayFactory object.
550    * @param name the name of the new parser.
551    * @param af the ArrayFactory.
552    * @return the new Parser.
553    */
554   public final Parser<Type[]> many1(final String   name, final ArrayFactory<Type> af){
555     return Parsers.many(name, af, 1, this);
556   }
557   /**
558    * p.many1() is equivalent to p+ in EBNF.
559    * The return values are discarded.
560    * @return the new Parser.
561    */
562   public final Parser<_> many1(){
563     return Parsers.many("many1", 1, this);
564   }
565   /**
566    * p.many1(name) is equivalent to p+ in EBNF.
567    * The return values are discarded.
568    * @param name the name of the new parser.
569    * @return the new Parser.
570    */
571   public final Parser<_> many1(final String   name){
572     return Parsers.many(name, 1, this);
573   }
574 
575   /**
576    * p.optional() is equivalent to p? in EBNF. null is the result when p fails.
577    * @return the new Parser.
578    */
579   public final Parser<Type> optional(){
580     return Parsers.optional("optional", this);
581   }
582   /**
583    * p.optional(name) is equivalent to p? in EBNF. null is the result when p fails.
584    * @param name the name of the new Parser.
585    * @return the new Parser.
586    */
587   public final Parser<Type> optional(final String   name){
588     return Parsers.optional(name, this);
589   }
590   /**
591    * If this fails with no input consumed, the default value is returned.
592    * p.option(name, def) = p | retn(def).
593    * @param def the default value.
594    * @return the new Parser.
595    */
596   public final Parser<Type> option(final Type def){
597     return Parsers.option("option", def, this);
598   }
599   /**
600    * If this fails with no input consumed, the default value is returned.
601    * p.option(name, def) = p | retn(def).
602    * @param name the name of the new Parser.
603    * @param def the default value.
604    * @return the new Parser.
605    */
606   public final Parser<Type> option(final String   name, final Type def){
607     return Parsers.option(name, def, this);
608   }
609   /**
610    * fails if 'this' succeeds. Input consumption is undone.
611    * @return the new Parser.
612    */
613   public final Parser<?> not(){
614     return Parsers.not("not", this);
615   }
616   /**
617    * fails if 'this' succeeds. Input consumption is undone.
618    * @param err the error message if fails.
619    * @return the new Parser.
620    */
621   public final Parser<?> not(final String   err){
622     return Parsers.not("not", this, err);
623   }
624   /**
625    * fails if 'this' succeeds. Input consumption is undone.
626    * @param name the name of the new Parser.
627    * @param err the error message if fails.
628    * @return the new Parser.
629    */
630   public final Parser<?> not(final String   name, final String   err){
631     return Parsers.not(name, this, err);
632   }
633   /**
634    * this is a look-ahead operation.
635    * Succeed or not, the input consumption is undone.
636    * @return the new Parser.
637    */
638   public final Parser<Type> peek(){
639     return Parsers.peek("peek", this);
640   }
641   /**
642    * this is a look-ahead operation.
643    * Succeed or not, the input consumption is undone.
644    * @param name the name of the new Parser
645    * @return the new Parser
646    */
647   public final Parser<Type> peek(final String   name){
648     return Parsers.peek(name, this);
649   }
650   /**
651    * if this succeeds, the returned value is transformed with m to a new return value.
652    * @param m the map object to transform return value.
653    * @return the new Parser.
654    */
655   public final <R> Parser<R> map(final Map<? super Type, R> m){
656     return Parsers.map("map", this, m);
657   }
658   /**
659    * if this succeeds, the returned value is transformed with m to a new return value.
660    * @param name the name of the new Parser.
661    * @param m the map object to transform return value.
662    * @return the new Parser.
663    */
664   public final <R> Parser<R> map(final String   name, final Map<? super Type, R> m){
665     return Parsers.map(name, this, m);
666   }
667   /**
668    * it sequentially run this and p, and then transforms the two return values with m to a new return value.
669    * @param p the next parser to run.
670    * @param m the transformation.
671    * @return the new Parser object.
672    */
673   public final <T, R> Parser<R> and(final Parser<T> p, final Map2<? super Type, ? super T, R> m){
674     return Parsers.map2("and", this, p, m);
675   }
676   /**
677    * it sequentially run this and p, and then transforms the two return values with m to a new return value.
678    * @param name the name of the new parser.
679    * @param p the next parser to run.
680    * @param m the transformation.
681    * @return the new Parser object.
682    */
683   public final <T, R> Parser<R> and(final String   name, final Parser<T> p, final Map2<? super Type, ? super T, R> m){
684     return Parsers.map2(name, this, p, m);
685   }
686   /**
687    * 'this' and 'sep' are executed sequentially.
688    * The return value of 'this' is returned.
689    * @param sep the following parser.
690    * @return the new Parser.
691    */
692   public final Parser<Type> followedBy(final Parser<?> sep){
693     return Parsers.followedBy("followedBy", sep, this);
694   }
695   /**
696    * 'this' and 'sep' are executed sequentially.
697    * The return value of 'this' is returned.
698    * @param name the name of the new Parser.
699    * @param sep the following parser.
700    * @return the new Parser.
701    */
702   public final Parser<Type> followedBy(final String   name, final Parser<?> sep){
703     return Parsers.followedBy(name, sep, this);
704   }
705   /**
706    * Make sure 'this' is atomic. When fails, no input is consumed.
707    * For lookahead, a successful atomized operation is considered 
708    * at most one logical step.
709    * @param name the name of the new Parser.
710    * @return the new Parser.
711    */
712   public final Parser<Type> atomize(final String   name){
713     return Parsers.atomize(name, this);
714   }
715   /**
716    * Make sure 'this' is atomic. When fails, no input is consumed.
717    * For lookahead, a successful atomized operation is considered 
718    * at most one logical step.
719    * @return the new Parser.
720    */
721   public final Parser<Type> atomize(){
722     return Parsers.atomize("atomize", this);
723   }
724   /**
725    * run yes if this succeeds, no if this fails without consuming input;
726    * fails otherwise.
727    * @param yes the true branch.
728    * @param no the false branch.
729    * @return the new Parser object.
730    */
731   public final <R> Parser ifelse(final Parser<R> yes, final Parser<? extends R> no){
732     return Parsers.ifelse("ifelse", this, yes, no);
733   }
734   /**
735    * run yes if this succeeds, no if this fails without consuming input;
736    * fails otherwise.
737    * @param name the name of the new Parser object.
738    * @param yes the true branch.
739    * @param no the false branch.
740    * @return the new Parser object.
741    */
742   public final <R> Parser<R> ifelse(final String   name, final Parser<R> yes, final Parser<R> no){
743     return Parsers.ifelse(name, this, yes, no);
744   }
745 
746   /**
747    * run yes if this succeeds, no if this fails without consuming input;
748    * fails otherwise.
749    * @param yes the true branch.
750    * @param no the false branch.
751    * @return the new Parser object.
752    */
753   public final <R> Parser<R> ifelse(final ToParser<? super Type, R> yes, final Parser<R> no){
754     return Parsers.ifelse("ifelse", this, yes, no);
755   }
756   /**
757    * run yes if this succeeds, no if this fails without consuming input;
758    * fails otherwise.
759    * @param name the name of the new Parser object.
760    * @param yes the true branch.
761    * @param no the false branch.
762    * @return the new Parser object.
763    */
764   public final <R> Parser<R> ifelse(final String   name, final ToParser<? super Type, R> yes, final Parser<R> no){
765     return Parsers.ifelse(name, this, yes, no);
766   }
767   /**
768    * By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed
769    * and consumed some input.
770    * this is because the default look-ahead token is 1.
771    * <br> by using lookahead, this default behavior can be altered.
772    * Parsers.plus(p1, p2).lookahead(3)
773    * will still try p2 even if p1 fails and consumes one or two inputs.
774    * <p> lookahead only affects one nesting level.
775    * Parsers.plus(p1,p2).ifelse(yes,no).lookahead(3)
776    * will not affect the Parsers.plus(p1,p2) nested within ifelse.
777    * <p> lookahead directly on top of lookahead will override the previous lookahead.
778    * Parsers.plus(p1,p2).lookahead(3).lookahead(1)
779    * is equivalent as Parsers.plus(p1, p2).lookahead(1).
780    * <br>
781    * lookahead looks at logical step.
782    * by default, each terminal is one logical step.
783    * atomize() combinator ensures at most 1 logical step for a parser.
784    * Use step() combinator to fine control logical steps.
785    * @param name the name of the new Parser object.
786    * @param toknum the number of tokens to look ahead.
787    * @return the new Parser object.
788    */
789   public final Parser<Type> lookahead(final String   name, final int toknum){
790     return Parsers.lookahead(name, toknum, this);
791   }
792   /**
793    * By default, ifelse, plus, sum will not try to run the next branch if the previous branch failed
794    * and consumed some input.
795    * this is because the default look-ahead token is 1.
796    * <br> by using lookahead, this default behavior can be altered.
797    * Parsers.plus(p1, p2).lookahead(3)
798    * will still try p2 even if p1 fails and consumes one or two inputs.
799    * <p> lookahead only affects one nesting level.
800    * Parsers.plus(p1,p2).ifelse(yes,no).lookahead(3)
801    * will not affect the Parsers.plus(p1,p2) nested within ifelse.
802    * <p> lookahead directly on top of lookahead will override the previous lookahead.
803    * Parsers.plus(p1,p2).lookahead(3).lookahead(1)
804    * is equivalent as Parsers.plus(p1, p2).lookahead(1).
805    * <br>
806    * lookahead looks at logical step.
807    * by default, each terminal is one logical step.
808    * atomize() combinator ensures at most 1 logical step for a parser.
809    * Use step() combinator to fine control logical steps.
810    * @param toknum the number of tokens to look ahead.
811    * @return the new Parser object.
812    */
813   public final Parser<Type> lookahead(final int toknum){
814     return Parsers.lookahead("lookahead", toknum, this);
815   }
816   /**
817    * if fails and did not consume input, 
818    * reports an expecting error with the given label.
819    * @param lbl the label text.
820    * @return the new Parser object.
821    */
822   public final Parser<Type> label(final String   lbl){
823     return Parsers.label("label", lbl, this);
824   }
825   /**
826    * if fails and did not consume input,
827    * reports an expecting error with the given label.
828    * @param name the name of the new Parser object.
829    * @param lbl the label text.
830    * @return the new Parser object.
831    */
832   public final Parser<Type> label(final String   name, final String   lbl){
833     return Parsers.label(name, lbl, this);
834   }
835   
836   /**
837    * Fails if the return value of this parser does not satisify the given predicate.
838    * No-op otherwise.
839    * @param name the name of the new Parser object.
840    * @param op the predicate object.
841    * @return the new Parser object.
842    */
843   public final Parser<Type> isReturn(final String   name, final ObjectPredicate<? super Type> op){
844     return Parsers.isReturn(name, this, op);
845   }
846   /**
847    * Fails if the return value of this parser does not satisify the given predicate.
848    * No-op otherwise.
849    * @param op the predicate object.
850    * @return the new Parser object.
851    */
852   public final Parser<Type> isReturn(final ObjectPredicate<? super Type> op){
853     return Parsers.isReturn("isReturn", this, op);
854   }
855   /**
856    * Fails if the return value of this parser does not satisify the given predicate.
857    * No-op otherwise.
858    * When fails, an "expecting" error will be generated.
859    * @param name the name of the new Parser object.
860    * @param op the predicate object.
861    * @param expecting the expected string.
862    * @return the new Parser object.
863    */
864   public final Parser<Type> isReturn(final String   name, final ObjectPredicate<? super Type> op, final String   expecting){
865     return Parsers.isReturn(name, this, op, expecting);
866   }
867   /**
868    * Fails if the return value of this parser does not satisify the given predicate.
869    * No-op otherwise.
870    * When fails, an "expecting" error will be generated.
871    * @param op the predicate object.
872    * @param expecting the expected string.
873    * @return the new Parser object.
874    */
875   public final Parser<Type> isReturn(final ObjectPredicate<? super Type> op, final String   expecting){
876     return Parsers.isReturn("isReturn", this, op, expecting);
877   }
878   /**
879    * lookahead looks at logical steps.
880    * step(int) runs this parser and sets the number of logical steps.
881    * 
882    * @param name the name of the new Parser object.
883    * @param n the number logical steps. n>=0 has to be true.
884    * @return the new Parser object.
885    */
886   public final Parser<Type> step(String   name, int n){
887     return Parsers.step(name, n, this);
888   }
889   /**
890    * lookahead looks at logical steps.
891    * step() runs this parser and sets 1 logical step.
892    * 
893    * @param name the name of the new Parser object.
894    * @return the new Parser object.
895    */
896   public final Parser<Type> step(final String   name){
897     return Parsers.step(name, 1, this);
898   }
899   /**
900    * lookahead looks at logical steps.
901    * step(int) runs this parser and sets the number of logical steps.
902    * 
903    * @param n the number logical steps. n>=0 has to be true.
904    * @return the new Parser object.
905    */
906   public final Parser<Type> step(int n){
907     return Parsers.step("step", n, this);
908   }
909   /**
910    * lookahead looks at logical steps.
911    * step() runs this parser and sets 1 logical step.
912    * 
913    * @return the new Parser object.
914    */
915   public final Parser<Type> step(){
916     return Parsers.step("step", 1, this);
917   }
918   
919   /**
920    * To cast the current Parser to a Parser object that returns a subtype of the current type.
921    * @param <R> the target return type.
922    * @return the Parser object that returns the expected type.
923    * @since version 1.0
924    */
925   public final <R extends Type> Parser<R> cast(){
926     return (Parser<R>)this;
927   }
928   /**
929    * To cast the current Parser to a Parser object that returns a subtype of the current type.
930    * @param <R> the target return type.
931    * @param type the class literal for the target type.
932    * @return the Parser object that returns the expected type.
933    * @since version 1.0
934    */
935   public final <R extends Type> Parser<R> cast(Class  <R> type){
936     return cast();
937   }
938   /**
939    * To convert the current Parser to a Parser object that returns any target type.
940    * @param <R> the target return type.
941    * @return the Parser object that returns the expected type.
942    * @since version 1.0
943    */
944   public final <R> Parser<R> convert(){
945     return (Parser<R>)this;
946   }
947   /**
948    * To convert the current Parser to a Parser object that returns any target type.
949    * @param <R> the target return type.
950    * @param type the class literal for the target type.
951    * @return the Parser object that returns the expected type.
952    * @since version 1.0
953    */
954   public final <R> Parser<R> convert(Class  <R> type){
955     return convert();
956   }
957   Type getReturn(ParseContext ctxt){
958     return (Type)ctxt.getReturn();
959   }
960   /**
961    * To parse a source string. 
962    * @param source the source string.
963    * @param moduleName the name of the module, this name appears in error message.
964    * @return the result.
965    * @since v1.2
966    */
967   public final Type parse(CharSequence   source, String   moduleName) {
968     return Parsers.runParser(source, this, moduleName);
969   }
970   /**
971    * To parse a source string. 
972    * @param source the source string.
973    * @return the result.
974    * @since v1.2
975    */
976   public final Type parse(CharSequence   source) {
977     return parse(source, "source");
978   }
979 }
980
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags