KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > oro > text > regex > MatchResult


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 MatchResult interface allows PatternMatcher implementors to return
62  * results storing match information in whatever format they like, while
63  * presenting a consistent way of accessing that information. However,
64  * MatchResult implementations should strictly follow the behavior
65  * described for the interface methods.
66  * <p>
67  *
68  * A MatchResult instance contains a pattern match and its saved groups.
69  * You can access the entire match directly using the
70  * {@link #group(int)} method with an argument of 0,
71  * or by the {@link #toString()} method which is
72  * defined to return the same thing. It is also possible to obtain
73  * the beginning and ending offsets of a match relative to the input
74  * producing the match by using the
75  * {@link #beginOffset(int)} and {@link #endOffset(int)} methods. The
76  * {@link #begin(int)} and {@link #end(int)} are useful in some
77  * circumstances and return the begin and end offsets of the subgroups
78  * of a match relative to the beginning of the match.
79  * <p>
80  *
81  * You might use a MatchResult as follows:
82  * <blockquote><pre>
83  * int groups;
84  * PatternMatcher matcher;
85  * PatternCompiler compiler;
86  * Pattern pattern;
87  * PatternMatcherInput input;
88  * MatchResult result;
89  *
90  * compiler = new Perl5Compiler();
91  * matcher = new Perl5Matcher();
92  *
93  * try {
94  * pattern = compiler.compile(somePatternString);
95  * } catch(MalformedPatternException e) {
96  * System.out.println("Bad pattern.");
97  * System.out.println(e.getMessage());
98  * return;
99  * }
100  *
101  * input = new PatternMatcherInput(someStringInput);
102  *
103  * while(matcher.contains(input, pattern)) {
104  * result = matcher.getMatch();
105  * // Perform whatever processing on the result you want.
106  * // Here we just print out all its elements to show how its
107  * // methods are used.
108  *
109  * System.out.println("Match: " + result.toString());
110  * System.out.println("Length: " + result.length());
111  * groups = result.groups();
112  * System.out.println("Groups: " + groups);
113  * System.out.println("Begin offset: " + result.beginOffset(0));
114  * System.out.println("End offset: " + result.endOffset(0));
115  * System.out.println("Saved Groups: ");
116  *
117  * // Start at 1 because we just printed out group 0
118  * for(int group = 1; group < groups; group++) {
119  * System.out.println(group + ": " + result.group(group));
120  * System.out.println("Begin: " + result.begin(group));
121  * System.out.println("End: " + result.end(group));
122  * }
123  * }
124  * </pre></blockquote>
125
126  @author <a HREF="dfs@savarese.org">Daniel F. Savarese</a>
127  @version $Id: MatchResult.java,v 1.1.1.1 2000/07/23 23:08:51 jon Exp $
128
129  * @see PatternMatcher
130  */
131
132 public interface MatchResult {
133   /**
134    * A convenience method returning the length of the entire match.
135    * If you want to get the length of a particular subgroup you should
136    * use the {@link #group(int)} method to get
137    * the string and then access its length() method as follows:
138    * <p>
139    * <blockquote><pre>
140    * int length = -1; // Use -1 to indicate group doesn't exist
141    * MatchResult result;
142    * String subgroup;
143    *
144    * // Initialization of result omitted
145    *
146    * subgroup = result.group(1);
147    * if(subgroup != null)
148    * length = subgroup.length();
149    *
150    * </pre></blockquote>
151    * <p>
152    *
153    * The length() method serves as a more a more efficient way to do:
154    * <p>
155    * <blockquote><pre>
156    * length = result.group(0).length();
157    * </pre></blockquote>
158    * <p>
159    *
160    * @return The length of the match.
161    */
162   public int length();
163
164
165   /**
166    * @return The number of groups contained in the result. This number
167    * includes the 0th group. In other words, the result refers
168    * to the number of parenthesized subgroups plus the entire match
169    * itself.
170    */
171   public int groups();
172
173   /**
174    * Returns the contents of the parenthesized subgroups of a match,
175    * counting parentheses from left to right and starting from 1.
176    * Group 0 always refers to the entire match. For example, if the
177    * pattern <code> foo(\d+) </code> is used to extract a match
178    * from the input <code> abfoo123 </code>, then <code> group(0) </code>
179    * will return <code> foo123 </code> and <code> group(1) </code> will return
180    * <code> 123 </code>. <code> group(2) </code> will return
181    * <code> null </code> because there is only one subgroup in the original
182    * pattern.
183    * <p>
184    * @param group The pattern subgroup to return.
185    * @return A string containing the indicated pattern subgroup. Group
186    * 0 always refers to the entire match. If a group was never
187    * matched, it returns null. This is not to be confused with
188    * a group matching the null string, which will return a String
189    * of length 0.
190    */
191   public String JavaDoc group(int group);
192
193
194   /**
195    * @param group The pattern subgroup.
196    * @return The offset into group 0 of the first token in the indicated
197    * pattern subgroup. If a group was never matched or does
198    * not exist, returns -1. Be aware that a group that matches
199    * the null string at the end of a match will have an offset
200    * equal to the length of the string, so you shouldn't blindly
201    * use the offset to index an array or String.
202    */
203   public int begin(int group);
204
205
206   /**
207    * @param group The pattern subgroup.
208    * @return Returns one plus the offset into group 0 of the last token in
209    * the indicated pattern subgroup. If a group was never matched
210    * or does not exist, returns -1. A group matching the null
211    * string will return its start offset.
212    */
213   public int end(int group);
214
215
216   /**
217    * Returns an offset marking the beginning of the pattern match
218    * relative to the beginning of the input from which the match
219    * was extracted.
220    * <p>
221    * @param group The pattern subgroup.
222    * @return The offset of the first token in the indicated
223    * pattern subgroup. If a group was never matched or does
224    * not exist, returns -1.
225    */
226   public int beginOffset(int group);
227
228
229   /**
230    * Returns an offset marking the end of the pattern match
231    * relative to the beginning of the input from which the match was
232    * extracted.
233    * <p>
234    * @param group The pattern subgroup.
235    * @return Returns one plus the offset of the last token in
236    * the indicated pattern subgroup. If a group was never matched
237    * or does not exist, returns -1. A group matching the null
238    * string will return its start offset.
239    */
240   public int endOffset(int group);
241
242
243   /**
244    * Returns the same as group(0).
245    *
246    * @return A string containing the entire match.
247    */
248   public String JavaDoc toString();
249 }
250
Popular Tags