PatternMatcher


1   package org.apache.oro.text.regex;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2000 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro" 
29   *    must not be used to endorse or promote products derived from this
30   *    software without prior written permission. For written
31   *    permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache" 
34   *    or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their 
35   *    name, without prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   *
56   * Portions of this software are based upon software originally written 
57   * by Daniel F. Savarese. We appreciate his contributions.
58   */
59  
60  /**
61   * The PatternMatcher interface defines the operations a regular
62   * expression matcher must implement.  However, the types of the Pattern 
63   * implementations recognized by a matcher are not restricted.  Typically
64   * PatternMatcher instances will only recognize a specific type of Pattern.
65   * For example, the Perl5Matcher only recognizes Perl5Pattern instances.
66   * However, none of the PatternMatcher methods are required to throw an
67   * exception in case of the use of an invalid pattern.  This is done for
68   * efficiency reasons, although usually a CastClassException will be
69   * thrown by the Java runtime system if you use the wrong Pattern
70   * implementation.  It is the responsibility of the programmer to make
71   * sure he uses the correct Pattern instance with a given PatternMatcher
72   * instance.  The current version of this package only contains the Perl5
73   * suite of pattern matching classes, but future ones for other regular
74   * expression grammars may be added and users may also create their own
75   * implementations of the provided interfaces. Therefore the programmer
76   * should be careful not to mismatch classes.
77  
78   @author <a HREF="dfs@savarese.org">Daniel F. Savarese</a>
79   @version $Id: PatternMatcher.java,v 1.1.1.1 2000/07/23 23:08:51 jon Exp $
80  
81   * @see Pattern
82   * @see PatternCompiler
83   * @see MatchResult
84   */
85  public interface PatternMatcher {
86  
87    /**
88     * Determines if a prefix of a string (represented as a char[])
89     * matches a given pattern, starting from a given offset into the string.
90     * If a prefix of the string matches the pattern, a MatchResult instance
91     * representing the match is made accesible via
92     * {@link #getMatch()}.
93     * <p>
94     * This method is useful for certain common token identification tasks
95     * that are made more difficult without this functionality.
96     * <p>
97     * @param input  The char[] to test for a prefix match.
98     * @param pattern  The Pattern to be matched.
99     * @param offset The offset at which to start searching for the prefix.
100    * @return True if input matches pattern, false otherwise.
101    */
102   public boolean matchesPrefix(char[] input, Pattern pattern, int offset);
103 
104   /**
105    * Determines if a prefix of a string matches a given pattern.
106    * If a prefix of the string matches the pattern, a MatchResult instance
107    * representing the match is made accesible via
108    * {@link #getMatch()}.
109    * <p>
110    * This method is useful for certain common token identification tasks
111    * that are made more difficult without this functionality.
112    * <p>
113    * @param input  The String to test for a prefix match.
114    * @param pattern  The Pattern to be matched.
115    * @return True if input matches pattern, false otherwise.
116    */
117   public boolean matchesPrefix(String   input, Pattern pattern);
118 
119   /**
120    * Determines if a prefix of a string (represented as a char[])
121    * matches a given pattern.
122    * If a prefix of the string matches the pattern, a MatchResult instance
123    * representing the match is made accesible via
124    * {@link #getMatch()}.
125    * <p>
126    * This method is useful for certain common token identification tasks
127    * that are made more difficult without this functionality.
128    * <p>
129    * @param input  The char[] to test for a prefix match.
130    * @param pattern  The Pattern to be matched.
131    * @return True if input matches pattern, false otherwise.
132    */
133   public boolean matchesPrefix(char[] input, Pattern pattern);
134 
135   /**
136    * Determines if a prefix of a PatternMatcherInput instance
137    * matches a given pattern.  If there is a match, a MatchResult instance
138    * representing the match is made accesible via
139    * {@link #getMatch()}.  Unlike the
140    * {@link #contains(PatternMatcherInput, Pattern)}
141    * method, the current offset of the PatternMatcherInput argument
142    * is not updated.  You should remember that the region starting
143    * from the begin offset of the PatternMatcherInput will be
144    * tested for a prefix match.
145    * <p>
146    * This method is useful for certain common token identification tasks
147    * that are made more difficult without this functionality.
148    * <p>
149    * @param input  The PatternMatcherInput to test for a prefix match.
150    * @param pattern  The Pattern to be matched.
151    * @return True if input matches pattern, false otherwise.
152    */
153   public boolean matchesPrefix(PatternMatcherInput input, Pattern pattern);
154 
155   /**
156    * Determines if a string exactly matches a given pattern.  If
157    * there is an exact match, a MatchResult instance
158    * representing the match is made accesible via
159    * {@link #getMatch()}.
160    * <p>
161    * @param input  The String to test for an exact match.
162    * @param pattern  The Pattern to be matched.
163    * @return True if input matches pattern, false otherwise.
164    */
165   public boolean matches(String   input, Pattern pattern);
166 
167   /**
168    * Determines if a string (represented as a char[]) exactly matches
169    * a given pattern.  If there is an exact match, a MatchResult
170    * instance representing the match is made accesible via
171    * {@link #getMatch()}.
172    * <p>
173    * @param input  The char[] to test for a match.
174    * @param pattern  The Pattern to be matched.
175    * @return True if input matches pattern, false otherwise.
176    */
177   public boolean matches(char[] input, Pattern pattern);
178 
179   /**
180    * Determines if the contents of a PatternMatcherInput instance
181    * exactly matches a given pattern.  If
182    * there is an exact match, a MatchResult instance
183    * representing the match is made accesible via
184    * {@link #getMatch()}.  Unlike the
185    * {@link #contains(PatternMatcherInput, Pattern)}
186    * method, the current offset of the PatternMatcherInput argument
187    * is not updated.  You should remember that the region between
188    * the begin and end offsets of the PatternMatcherInput will be
189    * tested for an exact match.
190    * <p>
191    * @param input  The PatternMatcherInput to test for a match.
192    * @param pattern  The Pattern to be matched.
193    * @return True if input matches pattern, false otherwise.
194    */
195   public boolean matches(PatternMatcherInput input, Pattern pattern);
196 
197   /**
198    * Determines if a string contains a pattern.  If the pattern is
199    * matched by some substring of the input, a MatchResult instance
200    * representing the <b> first </b> such match is made acessible via 
201    * {@link #getMatch()}.  If you want to access
202    * subsequent matches you should either use a PatternMatcherInput object
203    * or use the offset information in the MatchResult to create a substring
204    * representing the remaining input.  Using the MatchResult offset 
205    * information is the recommended method of obtaining the parts of the
206    * string preceeding the match and following the match.
207    * <p>
208    * @param input  The String to test for a match.
209    * @param pattern  The Pattern to be matched.
210    * @return True if the input contains a pattern match, false otherwise.
211    */
212   public boolean contains(String   input, Pattern pattern);
213 
214   /**
215    * Determines if a string (represented as a char[]) contains a pattern.
216    * If the pattern is matched by some substring of the input, a MatchResult
217    * instance representing the <b>first</b> such match is made acessible via 
218    * {@link #getMatch()}.  If you want to access
219    * subsequent matches you should either use a PatternMatcherInput object
220    * or use the offset information in the MatchResult to create a substring
221    * representing the remaining input.  Using the MatchResult offset 
222    * information is the recommended method of obtaining the parts of the
223    * string preceeding the match and following the match.
224    * <p>
225    * @param input  The String to test for a match.
226    * @param pattern  The Pattern to be matched.
227    * @return True if the input contains a pattern match, false otherwise.
228    */
229   public boolean contains(char[] input, Pattern pattern);
230 
231   /**
232    * Determines if the contents of a PatternMatcherInput, starting from the
233    * current offset of the input contains a pattern.
234    * If a pattern match is found, a MatchResult
235    * instance representing the <b>first</b> such match is made acessible via 
236    * {@link #getMatch()}.  The current offset of the
237    * PatternMatcherInput is set to the offset corresponding to the end
238    * of the match, so that a subsequent call to this method will continue
239    * searching where the last call left off.  You should remember that the
240    * region between the begin and end offsets of the PatternMatcherInput are
241    * considered the input to be searched, and that the current offset
242    * of the PatternMatcherInput reflects where a search will start from.
243    * Matches extending beyond the end offset of the PatternMatcherInput
244    * will not be matched.  In other words, a match must occur entirely
245    * between the begin and end offsets of the input.  See
246    * {@link PatternMatcherInput} for more details.
247    * <p>
248    * This method is usually used in a loop as follows:
249    * <blockquote><pre>
250    * PatternMatcher matcher;
251    * PatternCompiler compiler;
252    * Pattern pattern;
253    * PatternMatcherInput input;
254    * MatchResult result;
255    *
256    * compiler = new Perl5Compiler();
257    * matcher  = new Perl5Matcher();
258    *
259    * try {
260    *   pattern = compiler.compile(somePatternString);
261    * } catch(MalformedPatternException e) {
262    *   System.out.println("Bad pattern.");
263    *   System.out.println(e.getMessage());
264    *   return;
265    * }
266    *
267    * input   = new PatternMatcherInput(someStringInput);
268    *
269    * while(matcher.contains(input, pattern)) {
270    *   result = matcher.getMatch();  
271    *   // Perform whatever processing on the result you want.
272    * }
273    *
274    * </pre></blockquote>
275    * <p>
276    * @param input  The PatternMatcherInput to test for a match.
277    * @param pattern  The Pattern to be matched.
278    * @return True if the input contains a pattern match, false otherwise.
279    */
280   public boolean contains(PatternMatcherInput input, Pattern pattern);
281 
282   /**
283    * Fetches the last match found by a call to a matches() or contains()
284    * method.
285    * <p>
286    * @return A MatchResult instance containing the pattern match found
287    *         by the last call to any one of the matches() or contains()
288    *         methods.  If no match was found by the last call,
289    *         returns null.
290    */
291   public MatchResult getMatch();
292 }
293
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags