001: /*
002: * $Id: MatchResult.java,v 1.7 2003/11/07 20:16:25 dfs Exp $
003: *
004: * ====================================================================
005: * The Apache Software License, Version 1.1
006: *
007: * Copyright (c) 2000 The Apache Software Foundation. All rights
008: * reserved.
009: *
010: * Redistribution and use in source and binary forms, with or without
011: * modification, are permitted provided that the following conditions
012: * are met:
013: *
014: * 1. Redistributions of source code must retain the above copyright
015: * notice, this list of conditions and the following disclaimer.
016: *
017: * 2. Redistributions in binary form must reproduce the above copyright
018: * notice, this list of conditions and the following disclaimer in
019: * the documentation and/or other materials provided with the
020: * distribution.
021: *
022: * 3. The end-user documentation included with the redistribution,
023: * if any, must include the following acknowledgment:
024: * "This product includes software developed by the
025: * Apache Software Foundation (http://www.apache.org/)."
026: * Alternately, this acknowledgment may appear in the software itself,
027: * if and wherever such third-party acknowledgments normally appear.
028: *
029: * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro"
030: * must not be used to endorse or promote products derived from this
031: * software without prior written permission. For written
032: * permission, please contact apache@apache.org.
033: *
034: * 5. Products derived from this software may not be called "Apache"
035: * or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their
036: * name, without prior written permission of the Apache Software Foundation.
037: *
038: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
039: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
040: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
041: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
042: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
043: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
044: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
045: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
046: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
047: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
048: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
049: * SUCH DAMAGE.
050: * ====================================================================
051: *
052: * This software consists of voluntary contributions made by many
053: * individuals on behalf of the Apache Software Foundation. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package org.apache.oro.text.regex;
059:
060: /**
061: * The MatchResult interface allows PatternMatcher implementors to return
062: * results storing match information in whatever format they like, while
063: * presenting a consistent way of accessing that information. However,
064: * MatchResult implementations should strictly follow the behavior
065: * described for the interface methods.
066: * <p>
067: *
068: * A MatchResult instance contains a pattern match and its saved groups.
069: * You can access the entire match directly using the
070: * {@link #group(int)} method with an argument of 0,
071: * or by the {@link #toString()} method which is
072: * defined to return the same thing. It is also possible to obtain
073: * the beginning and ending offsets of a match relative to the input
074: * producing the match by using the
075: * {@link #beginOffset(int)} and {@link #endOffset(int)} methods. The
076: * {@link #begin(int)} and {@link #end(int)} are useful in some
077: * circumstances and return the begin and end offsets of the subgroups
078: * of a match relative to the beginning of the match.
079: * <p>
080: *
081: * You might use a MatchResult as follows:
082: * <blockquote><pre>
083: * int groups;
084: * PatternMatcher matcher;
085: * PatternCompiler compiler;
086: * Pattern pattern;
087: * PatternMatcherInput input;
088: * MatchResult result;
089: *
090: * compiler = new Perl5Compiler();
091: * matcher = new Perl5Matcher();
092: *
093: * try {
094: * pattern = compiler.compile(somePatternString);
095: * } catch(MalformedPatternException e) {
096: * System.out.println("Bad pattern.");
097: * System.out.println(e.getMessage());
098: * return;
099: * }
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: * @version @version@
127: * @since 1.0
128: * @see PatternMatcher
129: */
130:
131: public interface MatchResult {
132: /**
133: * A convenience method returning the length of the entire match.
134: * If you want to get the length of a particular subgroup you should
135: * use the {@link #group(int)} method to get
136: * the string and then access its length() method as follows:
137: * <p>
138: * <blockquote><pre>
139: * int length = -1; // Use -1 to indicate group doesn't exist
140: * MatchResult result;
141: * String subgroup;
142: *
143: * // Initialization of result omitted
144: *
145: * subgroup = result.group(1);
146: * if(subgroup != null)
147: * length = subgroup.length();
148: *
149: * </pre></blockquote>
150: * <p>
151: *
152: * The length() method serves as a more a more efficient way to do:
153: * <p>
154: * <blockquote><pre>
155: * length = result.group(0).length();
156: * </pre></blockquote>
157: * <p>
158: *
159: * @return The length of the match.
160: */
161: public int length();
162:
163: /**
164: * @return The number of groups contained in the result. This number
165: * includes the 0th group. In other words, the result refers
166: * to the number of parenthesized subgroups plus the entire match
167: * itself.
168: */
169: public int groups();
170:
171: /**
172: * Returns the contents of the parenthesized subgroups of a match,
173: * counting parentheses from left to right and starting from 1.
174: * Group 0 always refers to the entire match. For example, if the
175: * pattern <code> foo(\d+) </code> is used to extract a match
176: * from the input <code> abfoo123 </code>, then <code> group(0) </code>
177: * will return <code> foo123 </code> and <code> group(1) </code> will return
178: * <code> 123 </code>. <code> group(2) </code> will return
179: * <code> null </code> because there is only one subgroup in the original
180: * pattern.
181: * <p>
182: * @param group The pattern subgroup to return.
183: * @return A string containing the indicated pattern subgroup. Group
184: * 0 always refers to the entire match. If a group was never
185: * matched, it returns null. This is not to be confused with
186: * a group matching the null string, which will return a String
187: * of length 0.
188: */
189: public String group(int group);
190:
191: /**
192: * @param group The pattern subgroup.
193: * @return The offset into group 0 of the first token in the indicated
194: * pattern subgroup. If a group was never matched or does
195: * not exist, returns -1. Be aware that a group that matches
196: * the null string at the end of a match will have an offset
197: * equal to the length of the string, so you shouldn't blindly
198: * use the offset to index an array or String.
199: */
200: public int begin(int group);
201:
202: /**
203: * @param group The pattern subgroup.
204: * @return Returns one plus the offset into group 0 of the last token in
205: * the indicated pattern subgroup. If a group was never matched
206: * or does not exist, returns -1. A group matching the null
207: * string will return its start offset.
208: */
209: public int end(int group);
210:
211: /**
212: * Returns an offset marking the beginning of the pattern match
213: * relative to the beginning of the input from which the match
214: * was extracted.
215: * <p>
216: * @param group The pattern subgroup.
217: * @return The offset of the first token in the indicated
218: * pattern subgroup. If a group was never matched or does
219: * not exist, returns -1.
220: */
221: public int beginOffset(int group);
222:
223: /**
224: * Returns an offset marking the end of the pattern match
225: * relative to the beginning of the input from which the match was
226: * extracted.
227: * <p>
228: * @param group The pattern subgroup.
229: * @return Returns one plus the offset of the last token in
230: * the indicated pattern subgroup. If a group was never matched
231: * or does not exist, returns -1. A group matching the null
232: * string will return its start offset.
233: */
234: public int endOffset(int group);
235:
236: /**
237: * Returns the same as group(0).
238: *
239: * @return A string containing the entire match.
240: */
241: public String toString();
242: }
|