KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > jfun > parsec > pattern > Pattern


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 Dec 16, 2004
10  *
11  * Author Ben Yu
12  */
13 package jfun.parsec.pattern;
14
15 /**
16  * A Pattern object encapsulates an algorithm
17  * to recognize certain string pattern.
18  * When fed with a character range,
19  * a Pattern object either fails to match,
20  * or matches with the match length returned.
21  * <p>
22  * Pattern object is used for terminal level parsers.
23  * A Pattern differs from a Parser in that it does not return object,
24  * and it simply reports mismatch whenenver fails.
25  * While Parser cannot be implemented directly,
26  * Pattern can be implemented directly by user code.
27  * @author Ben Yu
28  *
29  * Dec 16, 2004
30  */
31 public abstract class Pattern implements java.io.Serializable JavaDoc{
32   /**
33    * returned by match() method when match fails.
34    */
35   public static final int MISMATCH = -1;
36   /**
37    * The actual length of the pattern string is len - from.
38    * @param src the source string.
39    * @param len the length of the sequence.
40    * NOTE: the range is [from, len], not [from,from+len].
41    * @param from the starting index in the sequence.
42    * @return the number of characters matched. MISMATCH otherwise.
43    */
44   public abstract int match(CharSequence JavaDoc src, int len, int from);
45   /**
46    * First matches this pattern.
47    * If succeed, match the remaining input against Pattern p2.
48    * Fails if either this or p2 fails.
49    * Succeed with the entire match length,
50    * which is the sum of the match length of this and p2.
51    * @param p2 the next Pattern object to match.
52    * @return the new Pattern object.
53    */
54   public final Pattern seq(final Pattern p2){
55     return Patterns.seq(this, p2);
56   }
57   /**
58    * Match with 0 length even if this pattern mismatches.
59    * @return the new Pattern object.
60    */
61   public final Pattern optional(){
62     return Patterns.optional(this);
63   }
64   /**
65    * Matches this pattern for 0 or more times.
66    * Return the total match length.
67    * @return the new Pattern object.
68    */
69   public final Pattern many(){
70     return Patterns.many(this);
71   }
72   /**
73    * Matches this pattern for at least min times.
74    * Return the total match length.
75    * @param min the minimal number of times to match.
76    * @return the new Pattern object.
77    */
78   public final Pattern many(int min){
79     return Patterns.many(min, this);
80   }
81   /**
82    * Matches this pattern for 1 or more times.
83    * Return the total match length.
84    * @return the new Pattern object.
85    */
86   public final Pattern many1(){
87     return Patterns.many(1, this);
88   }
89   /**
90    * Matches this pattern for up to max times.
91    * Return the total match length.
92    * @param max the maximal number of times to match.
93    * @return the new Pattern object.
94    */
95   public final Pattern some(final int max){
96     return Patterns.some(max, this);
97   }
98   /**
99    * Matches this pattern for at least min times
100    * and at most max times.
101    * Return the total match length.
102    * @param min the minimal number of times to match.
103    * @param max the maximal number of times to match.
104    * @return the new Pattern object.
105    */
106   public final Pattern some(final int min, final int max){
107     return Patterns.some(min, max, this);
108   }
109   /**
110    * If this pattern matches, return mismatch.
111    * return match length 0 otherwise.
112    * @return the new Pattern object.
113    */
114   public final Pattern not(){
115     return Patterns.not(this);
116   }
117   /**
118    * Matches with match length 0 if this Pattern object matches.
119    * Mismatch otherwise.
120    * @return the new Pattern object.
121    */
122   public final Pattern peek(){
123     return Patterns.peek(this);
124   }
125   
126   /**
127    * If this pattern matches,
128    * match the remaining input against Pattern object yes.
129    * Otherwise, match the input against Pattern object no.
130    * @param yes the true Pattern.
131    * @param no the false Pattern.
132    * @return the new Pattern object.
133    */
134   public final Pattern ifelse(final Pattern yes, final Pattern no){
135     return Patterns.ifelse(this, yes, no);
136   }
137   /**
138    * Matches the input against this pattern for n times.
139    * @param n the number of times to match.
140    * @return the new Pattern object.
141    */
142   public final Pattern repeat(final int n){
143     return Patterns.repeat(n, this);
144   }
145 }
146
Popular Tags