Source code: org/apache/oro/text/regex/MatchResult.java
1 /*
2 * $Id: MatchResult.java,v 1.7 2003/11/07 20:16:25 dfs Exp $
3 *
4 * ====================================================================
5 * The Apache Software License, Version 1.1
6 *
7 * Copyright (c) 2000 The Apache Software Foundation. All rights
8 * reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 *
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
16 *
17 * 2. Redistributions in binary form must reproduce the above copyright
18 * notice, this list of conditions and the following disclaimer in
19 * the documentation and/or other materials provided with the
20 * distribution.
21 *
22 * 3. The end-user documentation included with the redistribution,
23 * if any, must include the following acknowledgment:
24 * "This product includes software developed by the
25 * Apache Software Foundation (http://www.apache.org/)."
26 * Alternately, this acknowledgment may appear in the software itself,
27 * if and wherever such third-party acknowledgments normally appear.
28 *
29 * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro"
30 * must not be used to endorse or promote products derived from this
31 * software without prior written permission. For written
32 * permission, please contact apache@apache.org.
33 *
34 * 5. Products derived from this software may not be called "Apache"
35 * or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their
36 * name, without prior written permission of the Apache Software Foundation.
37 *
38 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
39 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
40 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
41 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
42 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
44 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
45 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
46 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
47 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
48 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49 * SUCH DAMAGE.
50 * ====================================================================
51 *
52 * This software consists of voluntary contributions made by many
53 * individuals on behalf of the Apache Software Foundation. For more
54 * information on the Apache Software Foundation, please see
55 * <http://www.apache.org/>.
56 */
57
58
59 package org.apache.oro.text.regex;
60
61
62 /**
63 * The MatchResult interface allows PatternMatcher implementors to return
64 * results storing match information in whatever format they like, while
65 * presenting a consistent way of accessing that information. However,
66 * MatchResult implementations should strictly follow the behavior
67 * described for the interface methods.
68 * <p>
69 *
70 * A MatchResult instance contains a pattern match and its saved groups.
71 * You can access the entire match directly using the
72 * {@link #group(int)} method with an argument of 0,
73 * or by the {@link #toString()} method which is
74 * defined to return the same thing. It is also possible to obtain
75 * the beginning and ending offsets of a match relative to the input
76 * producing the match by using the
77 * {@link #beginOffset(int)} and {@link #endOffset(int)} methods. The
78 * {@link #begin(int)} and {@link #end(int)} are useful in some
79 * circumstances and return the begin and end offsets of the subgroups
80 * of a match relative to the beginning of the match.
81 * <p>
82 *
83 * You might use a MatchResult as follows:
84 * <blockquote><pre>
85 * int groups;
86 * PatternMatcher matcher;
87 * PatternCompiler compiler;
88 * Pattern pattern;
89 * PatternMatcherInput input;
90 * MatchResult result;
91 *
92 * compiler = new Perl5Compiler();
93 * matcher = new Perl5Matcher();
94 *
95 * try {
96 * pattern = compiler.compile(somePatternString);
97 * } catch(MalformedPatternException e) {
98 * System.out.println("Bad pattern.");
99 * System.out.println(e.getMessage());
100 * return;
101 * }
102 *
103 * input = new PatternMatcherInput(someStringInput);
104 *
105 * while(matcher.contains(input, pattern)) {
106 * result = matcher.getMatch();
107 * // Perform whatever processing on the result you want.
108 * // Here we just print out all its elements to show how its
109 * // methods are used.
110 *
111 * System.out.println("Match: " + result.toString());
112 * System.out.println("Length: " + result.length());
113 * groups = result.groups();
114 * System.out.println("Groups: " + groups);
115 * System.out.println("Begin offset: " + result.beginOffset(0));
116 * System.out.println("End offset: " + result.endOffset(0));
117 * System.out.println("Saved Groups: ");
118 *
119 * // Start at 1 because we just printed out group 0
120 * for(int group = 1; group < groups; group++) {
121 * System.out.println(group + ": " + result.group(group));
122 * System.out.println("Begin: " + result.begin(group));
123 * System.out.println("End: " + result.end(group));
124 * }
125 * }
126 * </pre></blockquote>
127 *
128 * @version @version@
129 * @since 1.0
130 * @see PatternMatcher
131 */
132
133 public interface MatchResult {
134 /**
135 * A convenience method returning the length of the entire match.
136 * If you want to get the length of a particular subgroup you should
137 * use the {@link #group(int)} method to get
138 * the string and then access its length() method as follows:
139 * <p>
140 * <blockquote><pre>
141 * int length = -1; // Use -1 to indicate group doesn't exist
142 * MatchResult result;
143 * String subgroup;
144 *
145 * // Initialization of result omitted
146 *
147 * subgroup = result.group(1);
148 * if(subgroup != null)
149 * length = subgroup.length();
150 *
151 * </pre></blockquote>
152 * <p>
153 *
154 * The length() method serves as a more a more efficient way to do:
155 * <p>
156 * <blockquote><pre>
157 * length = result.group(0).length();
158 * </pre></blockquote>
159 * <p>
160 *
161 * @return The length of the match.
162 */
163 public int length();
164
165
166 /**
167 * @return The number of groups contained in the result. This number
168 * includes the 0th group. In other words, the result refers
169 * to the number of parenthesized subgroups plus the entire match
170 * itself.
171 */
172 public int groups();
173
174 /**
175 * Returns the contents of the parenthesized subgroups of a match,
176 * counting parentheses from left to right and starting from 1.
177 * Group 0 always refers to the entire match. For example, if the
178 * pattern <code> foo(\d+) </code> is used to extract a match
179 * from the input <code> abfoo123 </code>, then <code> group(0) </code>
180 * will return <code> foo123 </code> and <code> group(1) </code> will return
181 * <code> 123 </code>. <code> group(2) </code> will return
182 * <code> null </code> because there is only one subgroup in the original
183 * pattern.
184 * <p>
185 * @param group The pattern subgroup to return.
186 * @return A string containing the indicated pattern subgroup. Group
187 * 0 always refers to the entire match. If a group was never
188 * matched, it returns null. This is not to be confused with
189 * a group matching the null string, which will return a String
190 * of length 0.
191 */
192 public String group(int group);
193
194
195 /**
196 * @param group The pattern subgroup.
197 * @return The offset into group 0 of the first token in the indicated
198 * pattern subgroup. If a group was never matched or does
199 * not exist, returns -1. Be aware that a group that matches
200 * the null string at the end of a match will have an offset
201 * equal to the length of the string, so you shouldn't blindly
202 * use the offset to index an array or String.
203 */
204 public int begin(int group);
205
206
207 /**
208 * @param group The pattern subgroup.
209 * @return Returns one plus the offset into group 0 of the last token in
210 * the indicated pattern subgroup. If a group was never matched
211 * or does not exist, returns -1. A group matching the null
212 * string will return its start offset.
213 */
214 public int end(int group);
215
216
217 /**
218 * Returns an offset marking the beginning of the pattern match
219 * relative to the beginning of the input from which the match
220 * was extracted.
221 * <p>
222 * @param group The pattern subgroup.
223 * @return The offset of the first token in the indicated
224 * pattern subgroup. If a group was never matched or does
225 * not exist, returns -1.
226 */
227 public int beginOffset(int group);
228
229
230 /**
231 * Returns an offset marking the end of the pattern match
232 * relative to the beginning of the input from which the match was
233 * extracted.
234 * <p>
235 * @param group The pattern subgroup.
236 * @return Returns one plus the offset of the last token in
237 * the indicated pattern subgroup. If a group was never matched
238 * or does not exist, returns -1. A group matching the null
239 * string will return its start offset.
240 */
241 public int endOffset(int group);
242
243
244 /**
245 * Returns the same as group(0).
246 *
247 * @return A string containing the entire match.
248 */
249 public String toString();
250 }