- 0001
/* - 0002
* @(#)Matcher.java 1.64 06/04/07 - 0003 *
- 0004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 0005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 0006
*/ - 0007
- 0008package java.util.regex;
- 0009
- 0010
- 0011/**
- 0012 * An engine that performs match operations on a {@link java.lang.CharSequence
- 0013 * </code>character sequence<code>} by interpreting a {@link Pattern}.
- 0014 *
- 0015 * <p> A matcher is created from a pattern by invoking the pattern's {@link
- 0016 * Pattern#matcher matcher} method. Once created, a matcher can be used to
- 0017 * perform three different kinds of match operations:
- 0018 *
- 0019 * <ul>
- 0020 *
- 0021 * <li><p> The {@link #matches matches} method attempts to match the entire
- 0022 * input sequence against the pattern. </p></li>
- 0023 *
- 0024 * <li><p> The {@link #lookingAt lookingAt} method attempts to match the
- 0025 * input sequence, starting at the beginning, against the pattern. </p></li>
- 0026 *
- 0027 * <li><p> The {@link #find find} method scans the input sequence looking for
- 0028 * the next subsequence that matches the pattern. </p></li>
- 0029 *
- 0030 * </ul>
- 0031 *
- 0032 * <p> Each of these methods returns a boolean indicating success or failure.
- 0033 * More information about a successful match can be obtained by querying the
- 0034 * state of the matcher.
- 0035 *
- 0036 * <p> A matcher finds matches in a subset of its input called the
- 0037 * <i>region</i>. By default, the region contains all of the matcher's input.
- 0038 * The region can be modified via the{@link #region region} method and queried
- 0039 * via the {@link #regionStart regionStart} and {@link #regionEnd regionEnd}
- 0040 * methods. The way that the region boundaries interact with some pattern
- 0041 * constructs can be changed. See {@link #useAnchoringBounds
- 0042 * useAnchoringBounds} and {@link #useTransparentBounds useTransparentBounds}
- 0043 * for more details.
- 0044 *
- 0045 * <p> This class also defines methods for replacing matched subsequences with
- 0046 * new strings whose contents can, if desired, be computed from the match
- 0047 * result. The {@link #appendReplacement appendReplacement} and {@link
- 0048 * #appendTail appendTail} methods can be used in tandem in order to collect
- 0049 * the result into an existing string buffer, or the more convenient {@link
- 0050 * #replaceAll replaceAll} method can be used to create a string in which every
- 0051 * matching subsequence in the input sequence is replaced.
- 0052 *
- 0053 * <p> The explicit state of a matcher includes the start and end indices of
- 0054 * the most recent successful match. It also includes the start and end
- 0055 * indices of the input subsequence captured by each <a
- 0056 * href="Pattern.html#cg">capturing group</a> in the pattern as well as a total
- 0057 * count of such subsequences. As a convenience, methods are also provided for
- 0058 * returning these captured subsequences in string form.
- 0059 *
- 0060 * <p> The explicit state of a matcher is initially undefined; attempting to
- 0061 * query any part of it before a successful match will cause an {@link
- 0062 * IllegalStateException} to be thrown. The explicit state of a matcher is
- 0063 * recomputed by every match operation.
- 0064 *
- 0065 * <p> The implicit state of a matcher includes the input character sequence as
- 0066 * well as the <i>append position</i>, which is initially zero and is updated
- 0067 * by the {@link #appendReplacement appendReplacement} method.
- 0068 *
- 0069 * <p> A matcher may be reset explicitly by invoking its {@link #reset()}
- 0070 * method or, if a new input sequence is desired, its {@link
- 0071 * #reset(java.lang.CharSequence) reset(CharSequence)} method. Resetting a
- 0072 * matcher discards its explicit state information and sets the append position
- 0073 * to zero.
- 0074 *
- 0075 * <p> Instances of this class are not safe for use by multiple concurrent
- 0076 * threads. </p>
- 0077 *
- 0078 *
- 0079 * @author Mike McCloskey
- 0080 * @author Mark Reinhold
- 0081 * @author JSR-51 Expert Group
- 0082 * @version 1.64, 06/04/07
- 0083 * @since 1.4
- 0084 * @spec JSR-51
- 0085 */
- 0086
- 0087public final class Matcher implements MatchResult {
- 0088
- 0089 /**
- 0090 * The Pattern object that created this Matcher.
- 0091 */
- 0092 Pattern parentPattern;
- 0093
- 0094 /**
- 0095 * The storage used by groups. They may contain invalid values if
- 0096 * a group was skipped during the matching.
- 0097 */
- 0098 int[] groups;
- 0099
- 0100 /**
- 0101 * The range within the sequence that is to be matched. Anchors
- 0102 * will match at these "hard" boundaries. Changing the region
- 0103 * changes these values.
- 0104 */
- 0105 int from, to;
- 0106
- 0107 /**
- 0108 * Lookbehind uses this value to ensure that the subexpression
- 0109 * match ends at the point where the lookbehind was encountered.
- 0110 */
- 0111 int lookbehindTo;
- 0112
- 0113 /**
- 0114 * The original string being matched.
- 0115 */
- 0116 CharSequence text;
- 0117
- 0118 /**
- 0119 * Matcher state used by the last node. NOANCHOR is used when a
- 0120 * match does not have to consume all of the input. ENDANCHOR is
- 0121 * the mode used for matching all the input.
- 0122 */
- 0123 static final int ENDANCHOR = 1;
- 0124 static final int NOANCHOR = 0;
- 0125 int acceptMode = NOANCHOR;
- 0126
- 0127 /**
- 0128 * The range of string that last matched the pattern. If the last
- 0129 * match failed then first is -1; last initially holds 0 then it
- 0130 * holds the index of the end of the last match (which is where the
- 0131 * next search starts).
- 0132 */
- 0133 int first = -1, last = 0;
- 0134
- 0135 /**
- 0136 * The end index of what matched in the last match operation.
- 0137 */
- 0138 int oldLast = -1;
- 0139
- 0140 /**
- 0141 * The index of the last position appended in a substitution.
- 0142 */
- 0143 int lastAppendPosition = 0;
- 0144
- 0145 /**
- 0146 * Storage used by nodes to tell what repetition they are on in
- 0147 * a pattern, and where groups begin. The nodes themselves are stateless,
- 0148 * so they rely on this field to hold state during a match.
- 0149 */
- 0150 int[] locals;
- 0151
- 0152 /**
- 0153 * Boolean indicating whether or not more input could change
- 0154 * the results of the last match.
- 0155 *
- 0156 * If hitEnd is true, and a match was found, then more input
- 0157 * might cause a different match to be found.
- 0158 * If hitEnd is true and a match was not found, then more
- 0159 * input could cause a match to be found.
- 0160 * If hitEnd is false and a match was found, then more input
- 0161 * will not change the match.
- 0162 * If hitEnd is false and a match was not found, then more
- 0163 * input will not cause a match to be found.
- 0164 */
- 0165 boolean hitEnd;
- 0166
- 0167 /**
- 0168 * Boolean indicating whether or not more input could change
- 0169 * a positive match into a negative one.
- 0170 *
- 0171 * If requireEnd is true, and a match was found, then more
- 0172 * input could cause the match to be lost.
- 0173 * If requireEnd is false and a match was found, then more
- 0174 * input might change the match but the match won't be lost.
- 0175 * If a match was not found, then requireEnd has no meaning.
- 0176 */
- 0177 boolean requireEnd;
- 0178
- 0179 /**
- 0180 * If transparentBounds is true then the boundaries of this
- 0181 * matcher's region are transparent to lookahead, lookbehind,
- 0182 * and boundary matching constructs that try to see beyond them.
- 0183 */
- 0184 boolean transparentBounds = false;
- 0185
- 0186 /**
- 0187 * If anchoringBounds is true then the boundaries of this
- 0188 * matcher's region match anchors such as ^ and $.
- 0189 */
- 0190 boolean anchoringBounds = true;
- 0191
- 0192 /**
- 0193 * No default constructor.
- 0194 */
- 0195 Matcher() {
- 0196 }
- 0197
- 0198 /**
- 0199 * All matchers have the state used by Pattern during a match.
- 0200 */
- 0201 Matcher(Pattern parent, CharSequence text) {
- 0202 this.parentPattern = parent;
- 0203 this.text = text;
- 0204
- 0205 // Allocate state storage
- 0206 int parentGroupCount = Math.max(parent.capturingGroupCount, 10);
- 0207 groups = new int[parentGroupCount * 2];
- 0208 locals = new int[parent.localCount];
- 0209
- 0210 // Put fields into initial states
- 0211 reset();
- 0212 }
- 0213
- 0214 /**
- 0215 * Returns the pattern that is interpreted by this matcher.
- 0216 *
- 0217 * @return The pattern for which this matcher was created
- 0218 */
- 0219 public Pattern pattern() {
- 0220 return parentPattern;
- 0221 }
- 0222
- 0223 /**
- 0224 * Returns the match state of this matcher as a {@link MatchResult}.
- 0225 * The result is unaffected by subsequent operations performed upon this
- 0226 * matcher.
- 0227 *
- 0228 * @return a <code>MatchResult</code> with the state of this matcher
- 0229 * @since 1.5
- 0230 */
- 0231 public MatchResult toMatchResult() {
- 0232 Matcher result = new Matcher(this.parentPattern, text.toString());
- 0233 result.first = this.first;
- 0234 result.last = this.last;
- 0235 result.groups = (int[])(this.groups.clone());
- 0236 return result;
- 0237 }
- 0238
- 0239 /**
- 0240 * Changes the <tt>Pattern</tt> that this <tt>Matcher</tt> uses to
- 0241 * find matches with.
- 0242 *
- 0243 * <p> This method causes this matcher to lose information
- 0244 * about the groups of the last match that occurred. The
- 0245 * matcher's position in the input is maintained and its
- 0246 * last append position is unaffected.</p>
- 0247 *
- 0248 * @param newPattern
- 0249 * The new pattern used by this matcher
- 0250 * @return This matcher
- 0251 * @throws IllegalArgumentException
- 0252 * If newPattern is <tt>null</tt>
- 0253 * @since 1.5
- 0254 */
- 0255 public Matcher usePattern(Pattern newPattern) {
- 0256 if (newPattern == null)
- 0257 throw new IllegalArgumentException("Pattern cannot be null");
- 0258 parentPattern = newPattern;
- 0259
- 0260 // Reallocate state storage
- 0261 int parentGroupCount = Math.max(newPattern.capturingGroupCount, 10);
- 0262 groups = new int[parentGroupCount * 2];
- 0263 locals = new int[newPattern.localCount];
- 0264 for (int i = 0; i < groups.length; i++)
- 0265 groups[i] = -1;
- 0266 for (int i = 0; i < locals.length; i++)
- 0267 locals[i] = -1;
- 0268 return this;
- 0269 }
- 0270
- 0271 /**
- 0272 * Resets this matcher.
- 0273 *
- 0274 * <p> Resetting a matcher discards all of its explicit state information
- 0275 * and sets its append position to zero. The matcher's region is set to the
- 0276 * default region, which is its entire character sequence. The anchoring
- 0277 * and transparency of this matcher's region boundaries are unaffected.
- 0278 *
- 0279 * @return This matcher
- 0280 */
- 0281 public Matcher reset() {
- 0282 first = -1;
- 0283 last = 0;
- 0284 oldLast = -1;
- 0285 for(int i=0; i<groups.length; i++)
- 0286 groups[i] = -1;
- 0287 for(int i=0; i<locals.length; i++)
- 0288 locals[i] = -1;
- 0289 lastAppendPosition = 0;
- 0290 from = 0;
- 0291 to = getTextLength();
- 0292 return this;
- 0293 }
- 0294
- 0295 /**
- 0296 * Resets this matcher with a new input sequence.
- 0297 *
- 0298 * <p> Resetting a matcher discards all of its explicit state information
- 0299 * and sets its append position to zero. The matcher's region is set to
- 0300 * the default region, which is its entire character sequence. The
- 0301 * anchoring and transparency of this matcher's region boundaries are
- 0302 * unaffected.
- 0303 *
- 0304 * @param input
- 0305 * The new input character sequence
- 0306 *
- 0307 * @return This matcher
- 0308 */
- 0309 public Matcher reset(CharSequence input) {
- 0310 text = input;
- 0311 return reset();
- 0312 }
- 0313
- 0314 /**
- 0315 * Returns the start index of the previous match. </p>
- 0316 *
- 0317 * @return The index of the first character matched
- 0318 *
- 0319 * @throws IllegalStateException
- 0320 * If no match has yet been attempted,
- 0321 * or if the previous match operation failed
- 0322 */
- 0323 public int start() {
- 0324 if (first < 0)
- 0325 throw new IllegalStateException("No match available");
- 0326 return first;
- 0327 }
- 0328
- 0329 /**
- 0330 * Returns the start index of the subsequence captured by the given group
- 0331 * during the previous match operation.
- 0332 *
- 0333 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
- 0334 * to right, starting at one. Group zero denotes the entire pattern, so
- 0335 * the expression <i>m.</i><tt>start(0)</tt> is equivalent to
- 0336 * <i>m.</i><tt>start()</tt>. </p>
- 0337 *
- 0338 * @param group
- 0339 * The index of a capturing group in this matcher's pattern
- 0340 *
- 0341 * @return The index of the first character captured by the group,
- 0342 * or <tt>-1</tt> if the match was successful but the group
- 0343 * itself did not match anything
- 0344 *
- 0345 * @throws IllegalStateException
- 0346 * If no match has yet been attempted,
- 0347 * or if the previous match operation failed
- 0348 *
- 0349 * @throws IndexOutOfBoundsException
- 0350 * If there is no capturing group in the pattern
- 0351 * with the given index
- 0352 */
- 0353 public int start(int group) {
- 0354 if (first < 0)
- 0355 throw new IllegalStateException("No match available");
- 0356 if (group > groupCount())
- 0357 throw new IndexOutOfBoundsException("No group " + group);
- 0358 return groups[group * 2];
- 0359 }
- 0360
- 0361 /**
- 0362 * Returns the offset after the last character matched. </p>
- 0363 *
- 0364 * @return The offset after the last character matched
- 0365 *
- 0366 * @throws IllegalStateException
- 0367 * If no match has yet been attempted,
- 0368 * or if the previous match operation failed
- 0369 */
- 0370 public int end() {
- 0371 if (first < 0)
- 0372 throw new IllegalStateException("No match available");
- 0373 return last;
- 0374 }
- 0375
- 0376 /**
- 0377 * Returns the offset after the last character of the subsequence
- 0378 * captured by the given group during the previous match operation.
- 0379 *
- 0380 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
- 0381 * to right, starting at one. Group zero denotes the entire pattern, so
- 0382 * the expression <i>m.</i><tt>end(0)</tt> is equivalent to
- 0383 * <i>m.</i><tt>end()</tt>. </p>
- 0384 *
- 0385 * @param group
- 0386 * The index of a capturing group in this matcher's pattern
- 0387 *
- 0388 * @return The offset after the last character captured by the group,
- 0389 * or <tt>-1</tt> if the match was successful
- 0390 * but the group itself did not match anything
- 0391 *
- 0392 * @throws IllegalStateException
- 0393 * If no match has yet been attempted,
- 0394 * or if the previous match operation failed
- 0395 *
- 0396 * @throws IndexOutOfBoundsException
- 0397 * If there is no capturing group in the pattern
- 0398 * with the given index
- 0399 */
- 0400 public int end(int group) {
- 0401 if (first < 0)
- 0402 throw new IllegalStateException("No match available");
- 0403 if (group > groupCount())
- 0404 throw new IndexOutOfBoundsException("No group " + group);
- 0405 return groups[group * 2 + 1];
- 0406 }
- 0407
- 0408 /**
- 0409 * Returns the input subsequence matched by the previous match.
- 0410 *
- 0411 * <p> For a matcher <i>m</i> with input sequence <i>s</i>,
- 0412 * the expressions <i>m.</i><tt>group()</tt> and
- 0413 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(),</tt> <i>m.</i><tt>end())</tt>
- 0414 * are equivalent. </p>
- 0415 *
- 0416 * <p> Note that some patterns, for example <tt>a*</tt>, match the empty
- 0417 * string. This method will return the empty string when the pattern
- 0418 * successfully matches the empty string in the input. </p>
- 0419 *
- 0420 * @return The (possibly empty) subsequence matched by the previous match,
- 0421 * in string form
- 0422 *
- 0423 * @throws IllegalStateException
- 0424 * If no match has yet been attempted,
- 0425 * or if the previous match operation failed
- 0426 */
- 0427 public String group() {
- 0428 return group(0);
- 0429 }
- 0430
- 0431 /**
- 0432 * Returns the input subsequence captured by the given group during the
- 0433 * previous match operation.
- 0434 *
- 0435 * <p> For a matcher <i>m</i>, input sequence <i>s</i>, and group index
- 0436 * <i>g</i>, the expressions <i>m.</i><tt>group(</tt><i>g</i><tt>)</tt> and
- 0437 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(</tt><i>g</i><tt>),</tt> <i>m.</i><tt>end(</tt><i>g</i><tt>))</tt>
- 0438 * are equivalent. </p>
- 0439 *
- 0440 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
- 0441 * to right, starting at one. Group zero denotes the entire pattern, so
- 0442 * the expression <tt>m.group(0)</tt> is equivalent to <tt>m.group()</tt>.
- 0443 * </p>
- 0444 *
- 0445 * <p> If the match was successful but the group specified failed to match
- 0446 * any part of the input sequence, then <tt>null</tt> is returned. Note
- 0447 * that some groups, for example <tt>(a*)</tt>, match the empty string.
- 0448 * This method will return the empty string when such a group successfully
- 0449 * matches the empty string in the input. </p>
- 0450 *
- 0451 * @param group
- 0452 * The index of a capturing group in this matcher's pattern
- 0453 *
- 0454 * @return The (possibly empty) subsequence captured by the group
- 0455 * during the previous match, or <tt>null</tt> if the group
- 0456 * failed to match part of the input
- 0457 *
- 0458 * @throws IllegalStateException
- 0459 * If no match has yet been attempted,
- 0460 * or if the previous match operation failed
- 0461 *
- 0462 * @throws IndexOutOfBoundsException
- 0463 * If there is no capturing group in the pattern
- 0464 * with the given index
- 0465 */
- 0466 public String group(int group) {
- 0467 if (first < 0)
- 0468 throw new IllegalStateException("No match found");
- 0469 if (group < 0 || group > groupCount())
- 0470 throw new IndexOutOfBoundsException("No group " + group);
- 0471 if ((groups[group*2] == -1) || (groups[group*2+1] == -1))
- 0472 return null;
- 0473 return getSubSequence(groups[group * 2], groups[group * 2 + 1]).toString();
- 0474 }
- 0475
- 0476 /**
- 0477 * Returns the number of capturing groups in this matcher's pattern.
- 0478 *
- 0479 * <p> Group zero denotes the entire pattern by convention. It is not
- 0480 * included in this count.
- 0481 *
- 0482 * <p> Any non-negative integer smaller than or equal to the value
- 0483 * returned by this method is guaranteed to be a valid group index for
- 0484 * this matcher. </p>
- 0485 *
- 0486 * @return The number of capturing groups in this matcher's pattern
- 0487 */
- 0488 public int groupCount() {
- 0489 return parentPattern.capturingGroupCount - 1;
- 0490 }
- 0491
- 0492 /**
- 0493 * Attempts to match the entire region against the pattern.
- 0494 *
- 0495 * <p> If the match succeeds then more information can be obtained via the
- 0496 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
- 0497 *
- 0498 * @return <tt>true</tt> if, and only if, the entire region sequence
- 0499 * matches this matcher's pattern
- 0500 */
- 0501 public boolean matches() {
- 0502 return match(from, ENDANCHOR);
- 0503 }
- 0504
- 0505 /**
- 0506 * Attempts to find the next subsequence of the input sequence that matches
- 0507 * the pattern.
- 0508 *
- 0509 * <p> This method starts at the beginning of this matcher's region, or, if
- 0510 * a previous invocation of the method was successful and the matcher has
- 0511 * not since been reset, at the first character not matched by the previous
- 0512 * match.
- 0513 *
- 0514 * <p> If the match succeeds then more information can be obtained via the
- 0515 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
- 0516 *
- 0517 * @return <tt>true</tt> if, and only if, a subsequence of the input
- 0518 * sequence matches this matcher's pattern
- 0519 */
- 0520 public boolean find() {
- 0521 int nextSearchIndex = last;
- 0522 if (nextSearchIndex == first)
- 0523 nextSearchIndex++;
- 0524
- 0525 // If next search starts before region, start it at region
- 0526 if (nextSearchIndex < from)
- 0527 nextSearchIndex = from;
- 0528
- 0529 // If next search starts beyond region then it fails
- 0530 if (nextSearchIndex > to) {
- 0531 for (int i = 0; i < groups.length; i++)
- 0532 groups[i] = -1;
- 0533 return false;
- 0534 }
- 0535 return search(nextSearchIndex);
- 0536 }
- 0537
- 0538 /**
- 0539 * Resets this matcher and then attempts to find the next subsequence of
- 0540 * the input sequence that matches the pattern, starting at the specified
- 0541 * index.
- 0542 *
- 0543 * <p> If the match succeeds then more information can be obtained via the
- 0544 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods, and subsequent
- 0545 * invocations of the {@link #find()} method will start at the first
- 0546 * character not matched by this match. </p>
- 0547 *
- 0548 * @throws IndexOutOfBoundsException
- 0549 * If start is less than zero or if start is greater than the
- 0550 * length of the input sequence.
- 0551 *
- 0552 * @return <tt>true</tt> if, and only if, a subsequence of the input
- 0553 * sequence starting at the given index matches this matcher's
- 0554 * pattern
- 0555 */
- 0556 public boolean find(int start) {
- 0557 int limit = getTextLength();
- 0558 if ((start < 0) || (start > limit))
- 0559 throw new IndexOutOfBoundsException("Illegal start index");
- 0560 reset();
- 0561 return search(start);
- 0562 }
- 0563
- 0564 /**
- 0565 * Attempts to match the input sequence, starting at the beginning of the
- 0566 * region, against the pattern.
- 0567 *
- 0568 * <p> Like the {@link #matches matches} method, this method always starts
- 0569 * at the beginning of the region; unlike that method, it does not
- 0570 * require that the entire region be matched.
- 0571 *
- 0572 * <p> If the match succeeds then more information can be obtained via the
- 0573 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
- 0574 *
- 0575 * @return <tt>true</tt> if, and only if, a prefix of the input
- 0576 * sequence matches this matcher's pattern
- 0577 */
- 0578 public boolean lookingAt() {
- 0579 return match(from, NOANCHOR);
- 0580 }
- 0581
- 0582 /**
- 0583 * Returns a literal replacement <code>String</code> for the specified
- 0584 * <code>String</code>.
- 0585 *
- 0586 * This method produces a <code>String</code> that will work
- 0587 * as a literal replacement <code>s</code> in the
- 0588 * <code>appendReplacement</code> method of the {@link Matcher} class.
- 0589 * The <code>String</code> produced will match the sequence of characters
- 0590 * in <code>s</code> treated as a literal sequence. Slashes ('\') and
- 0591 * dollar signs ('$') will be given no special meaning.
- 0592 *
- 0593 * @param s The string to be literalized
- 0594 * @return A literal string replacement
- 0595 * @since 1.5
- 0596 */
- 0597 public static String quoteReplacement(String s) {
- 0598 if ((s.indexOf('\\') == -1) && (s.indexOf('$') == -1))
- 0599 return s;
- 0600 StringBuffer sb = new StringBuffer();
- 0601 for (int i=0; i<s.length(); i++) {
- 0602 char c = s.charAt(i);
- 0603 if (c == '\\') {
- 0604 sb.append('\\'); sb.append('\\');
- 0605 } else if (c == '$') {
- 0606 sb.append('\\'); sb.append('$');
- 0607 } else {
- 0608 sb.append(c);
- 0609 }
- 0610 }
- 0611 return sb.toString();
- 0612 }
- 0613
- 0614 /**
- 0615 * Implements a non-terminal append-and-replace step.
- 0616 *
- 0617 * <p> This method performs the following actions: </p>
- 0618 *
- 0619 * <ol>
- 0620 *
- 0621 * <li><p> It reads characters from the input sequence, starting at the
- 0622 * append position, and appends them to the given string buffer. It
- 0623 * stops after reading the last character preceding the previous match,
- 0624 * that is, the character at index {@link
- 0625 * #start()} <tt>-</tt> <tt>1</tt>. </p></li>
- 0626 *
- 0627 * <li><p> It appends the given replacement string to the string buffer.
- 0628 * </p></li>
- 0629 *
- 0630 * <li><p> It sets the append position of this matcher to the index of
- 0631 * the last character matched, plus one, that is, to {@link #end()}.
- 0632 * </p></li>
- 0633 *
- 0634 * </ol>
- 0635 *
- 0636 * <p> The replacement string may contain references to subsequences
- 0637 * captured during the previous match: Each occurrence of
- 0638 * <tt>$</tt><i>g</i><tt></tt> will be replaced by the result of
- 0639 * evaluating {@link #group(int) group}<tt>(</tt><i>g</i><tt>)</tt>.
- 0640 * The first number after the <tt>$</tt> is always treated as part of
- 0641 * the group reference. Subsequent numbers are incorporated into g if
- 0642 * they would form a legal group reference. Only the numerals '0'
- 0643 * through '9' are considered as potential components of the group
- 0644 * reference. If the second group matched the string <tt>"foo"</tt>, for
- 0645 * example, then passing the replacement string <tt>"$2bar"</tt> would
- 0646 * cause <tt>"foobar"</tt> to be appended to the string buffer. A dollar
- 0647 * sign (<tt>$</tt>) may be included as a literal in the replacement
- 0648 * string by preceding it with a backslash (<tt>\$</tt>).
- 0649 *
- 0650 * <p> Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
- 0651 * the replacement string may cause the results to be different than if it
- 0652 * were being treated as a literal replacement string. Dollar signs may be
- 0653 * treated as references to captured subsequences as described above, and
- 0654 * backslashes are used to escape literal characters in the replacement
- 0655 * string.
- 0656 *
- 0657 * <p> This method is intended to be used in a loop together with the
- 0658 * {@link #appendTail appendTail} and {@link #find find} methods. The
- 0659 * following code, for example, writes <tt>one dog two dogs in the
- 0660 * yard</tt> to the standard-output stream: </p>
- 0661 *
- 0662 * <blockquote><pre>
- 0663 * Pattern p = Pattern.compile("cat");
- 0664 * Matcher m = p.matcher("one cat two cats in the yard");
- 0665 * StringBuffer sb = new StringBuffer();
- 0666 * while (m.find()) {
- 0667 * m.appendReplacement(sb, "dog");
- 0668 * }
- 0669 * m.appendTail(sb);
- 0670 * System.out.println(sb.toString());</pre></blockquote>
- 0671 *
- 0672 * @param sb
- 0673 * The target string buffer
- 0674 *
- 0675 * @param replacement
- 0676 * The replacement string
- 0677 *
- 0678 * @return This matcher
- 0679 *
- 0680 * @throws IllegalStateException
- 0681 * If no match has yet been attempted,
- 0682 * or if the previous match operation failed
- 0683 *
- 0684 * @throws IndexOutOfBoundsException
- 0685 * If the replacement string refers to a capturing group
- 0686 * that does not exist in the pattern
- 0687 */
- 0688 public Matcher appendReplacement(StringBuffer sb, String replacement) {
- 0689
- 0690 // If no match, return error
- 0691 if (first < 0)
- 0692 throw new IllegalStateException("No match available");
- 0693
- 0694 // Process substitution string to replace group references with groups
- 0695 int cursor = 0;
- 0696 String s = replacement;
- 0697 StringBuffer result = new StringBuffer();
- 0698
- 0699 while (cursor < replacement.length()) {
- 0700 char nextChar = replacement.charAt(cursor);
- 0701 if (nextChar == '\\') {
- 0702 cursor++;
- 0703 nextChar = replacement.charAt(cursor);
- 0704 result.append(nextChar);
- 0705 cursor++;
- 0706 } else if (nextChar == '$') {
- 0707 // Skip past $
- 0708 cursor++;
- 0709
- 0710 // The first number is always a group
- 0711 int refNum = (int)replacement.charAt(cursor) - '0';
- 0712 if ((refNum < 0)||(refNum > 9))
- 0713 throw new IllegalArgumentException(
- 0714 "Illegal group reference");
- 0715 cursor++;
- 0716
- 0717 // Capture the largest legal group string
- 0718 boolean done = false;
- 0719 while (!done) {
- 0720 if (cursor >= replacement.length()) {
- 0721 break;
- 0722 }
- 0723 int nextDigit = replacement.charAt(cursor) - '0';
- 0724 if ((nextDigit < 0)||(nextDigit > 9)) { // not a number
- 0725 break;
- 0726 }
- 0727 int newRefNum = (refNum * 10) + nextDigit;
- 0728 if (groupCount() < newRefNum) {
- 0729 done = true;
- 0730 } else {
- 0731 refNum = newRefNum;
- 0732 cursor++;
- 0733 }
- 0734 }
- 0735
- 0736 // Append group
- 0737 if (group(refNum) != null)
- 0738 result.append(group(refNum));
- 0739 } else {
- 0740 result.append(nextChar);
- 0741 cursor++;
- 0742 }
- 0743 }
- 0744
- 0745 // Append the intervening text
- 0746 sb.append(getSubSequence(lastAppendPosition, first));
- 0747 // Append the match substitution
- 0748 sb.append(result.toString());
- 0749
- 0750 lastAppendPosition = last;
- 0751 return this;
- 0752 }
- 0753
- 0754 /**
- 0755 * Implements a terminal append-and-replace step.
- 0756 *
- 0757 * <p> This method reads characters from the input sequence, starting at
- 0758 * the append position, and appends them to the given string buffer. It is
- 0759 * intended to be invoked after one or more invocations of the {@link
- 0760 * #appendReplacement appendReplacement} method in order to copy the
- 0761 * remainder of the input sequence. </p>
- 0762 *
- 0763 * @param sb
- 0764 * The target string buffer
- 0765 *
- 0766 * @return The target string buffer
- 0767 */
- 0768 public StringBuffer appendTail(StringBuffer sb) {
- 0769 sb.append(getSubSequence(lastAppendPosition, getTextLength()).toString());
- 0770 return sb;
- 0771 }
- 0772
- 0773 /**
- 0774 * Replaces every subsequence of the input sequence that matches the
- 0775 * pattern with the given replacement string.
- 0776 *
- 0777 * <p> This method first resets this matcher. It then scans the input
- 0778 * sequence looking for matches of the pattern. Characters that are not
- 0779 * part of any match are appended directly to the result string; each match
- 0780 * is replaced in the result by the replacement string. The replacement
- 0781 * string may contain references to captured subsequences as in the {@link
- 0782 * #appendReplacement appendReplacement} method.
- 0783 *
- 0784 * <p> Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
- 0785 * the replacement string may cause the results to be different than if it
- 0786 * were being treated as a literal replacement string. Dollar signs may be
- 0787 * treated as references to captured subsequences as described above, and
- 0788 * backslashes are used to escape literal characters in the replacement
- 0789 * string.
- 0790 *
- 0791 * <p> Given the regular expression <tt>a*b</tt>, the input
- 0792 * <tt>"aabfooaabfooabfoob"</tt>, and the replacement string
- 0793 * <tt>"-"</tt>, an invocation of this method on a matcher for that
- 0794 * expression would yield the string <tt>"-foo-foo-foo-"</tt>.
- 0795 *
- 0796 * <p> Invoking this method changes this matcher's state. If the matcher
- 0797 * is to be used in further matching operations then it should first be
- 0798 * reset. </p>
- 0799 *
- 0800 * @param replacement
- 0801 * The replacement string
- 0802 *
- 0803 * @return The string constructed by replacing each matching subsequence
- 0804 * by the replacement string, substituting captured subsequences
- 0805 * as needed
- 0806 */
- 0807 public String replaceAll(String replacement) {
- 0808 reset();
- 0809 boolean result = find();
- 0810 if (result) {
- 0811 StringBuffer sb = new StringBuffer();
- 0812 do {
- 0813 appendReplacement(sb, replacement);
- 0814 result = find();
- 0815 } while (result);
- 0816 appendTail(sb);
- 0817 return sb.toString();
- 0818 }
- 0819 return text.toString();
- 0820 }
- 0821
- 0822 /**
- 0823 * Replaces the first subsequence of the input sequence that matches the
- 0824 * pattern with the given replacement string.
- 0825 *
- 0826 * <p> This method first resets this matcher. It then scans the input
- 0827 * sequence looking for a match of the pattern. Characters that are not
- 0828 * part of the match are appended directly to the result string; the match
- 0829 * is replaced in the result by the replacement string. The replacement
- 0830 * string may contain references to captured subsequences as in the {@link
- 0831 * #appendReplacement appendReplacement} method.
- 0832 *
- 0833 * <p>Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
- 0834 * the replacement string may cause the results to be different than if it
- 0835 * were being treated as a literal replacement string. Dollar signs may be
- 0836 * treated as references to captured subsequences as described above, and
- 0837 * backslashes are used to escape literal characters in the replacement
- 0838 * string.
- 0839 *
- 0840 * <p> Given the regular expression <tt>dog</tt>, the input
- 0841 * <tt>"zzzdogzzzdogzzz"</tt>, and the replacement string
- 0842 * <tt>"cat"</tt>, an invocation of this method on a matcher for that
- 0843 * expression would yield the string <tt>"zzzcatzzzdogzzz"</tt>. </p>
- 0844 *
- 0845 * <p> Invoking this method changes this matcher's state. If the matcher
- 0846 * is to be used in further matching operations then it should first be
- 0847 * reset. </p>
- 0848 *
- 0849 * @param replacement
- 0850 * The replacement string
- 0851 * @return The string constructed by replacing the first matching
- 0852 * subsequence by the replacement string, substituting captured
- 0853 * subsequences as needed
- 0854 */
- 0855 public String replaceFirst(String replacement) {
- 0856 if (replacement == null)
- 0857 throw new NullPointerException("replacement");
- 0858 StringBuffer sb = new StringBuffer();
- 0859 reset();
- 0860 if (find())
- 0861 appendReplacement(sb, replacement);
- 0862 appendTail(sb);
- 0863 return sb.toString();
- 0864 }
- 0865
- 0866 /**
- 0867 * Sets the limits of this matcher's region. The region is the part of the
- 0868 * input sequence that will be searched to find a match. Invoking this
- 0869 * method resets the matcher, and then sets the region to start at the
- 0870 * index specified by the <code>start</code> parameter and end at the
- 0871 * index specified by the <code>end</code> parameter.
- 0872 *
- 0873 * <p>Depending on the transparency and anchoring being used (see
- 0874 * {@link #useTransparentBounds useTransparentBounds} and
- 0875 * {@link #useAnchoringBounds useAnchoringBounds}), certain constructs such
- 0876 * as anchors may behave differently at or around the boundaries of the
- 0877 * region.
- 0878 *
- 0879 * @param start
- 0880 * The index to start searching at (inclusive)
- 0881 * @param end
- 0882 * The index to end searching at (exclusive)
- 0883 * @throws IndexOutOfBoundsException
- 0884 * If start or end is less than zero, if
- 0885 * start is greater than the length of the input sequence, if
- 0886 * end is greater than the length of the input sequence, or if
- 0887 * start is greater than end.
- 0888 * @return this matcher
- 0889 * @since 1.5
- 0890 */
- 0891 public Matcher region(int start, int end) {
- 0892 if ((start < 0) || (start > getTextLength()))
- 0893 throw new IndexOutOfBoundsException("start");
- 0894 if ((end < 0) || (end > getTextLength()))
- 0895 throw new IndexOutOfBoundsException("end");
- 0896 if (start > end)
- 0897 throw new IndexOutOfBoundsException("start > end");
- 0898 reset();
- 0899 from = start;
- 0900 to = end;
- 0901 return this;
- 0902 }
- 0903
- 0904 /**
- 0905 * Reports the start index of this matcher's region. The
- 0906 * searches this matcher conducts are limited to finding matches
- 0907 * within {@link #regionStart regionStart} (inclusive) and
- 0908 * {@link #regionEnd regionEnd} (exclusive).
- 0909 *
- 0910 * @return The starting point of this matcher's region
- 0911 * @since 1.5
- 0912 */
- 0913 public int regionStart() {
- 0914 return from;
- 0915 }
- 0916
- 0917 /**
- 0918 * Reports the end index (exclusive) of this matcher's region.
- 0919 * The searches this matcher conducts are limited to finding matches
- 0920 * within {@link #regionStart regionStart} (inclusive) and
- 0921 * {@link #regionEnd regionEnd} (exclusive).
- 0922 *
- 0923 * @return the ending point of this matcher's region
- 0924 * @since 1.5
- 0925 */
- 0926 public int regionEnd() {
- 0927 return to;
- 0928 }
- 0929
- 0930 /**
- 0931 * Queries the transparency of region bounds for this matcher.
- 0932 *
- 0933 * <p> This method returns <tt>true</tt> if this matcher uses
- 0934 * <i>transparent</i> bounds, <tt>false</tt> if it uses <i>opaque</i>
- 0935 * bounds.
- 0936 *
- 0937 * <p> See {@link #useTransparentBounds useTransparentBounds} for a
- 0938 * description of transparent and opaque bounds.
- 0939 *
- 0940 * <p> By default, a matcher uses opaque region boundaries.
- 0941 *
- 0942 * @return <tt>true</tt> iff this matcher is using transparent bounds,
- 0943 * <tt>false</tt> otherwise.
- 0944 * @see java.util.regex.Matcher#useTransparentBounds(boolean)
- 0945 * @since 1.5
- 0946 */
- 0947 public boolean hasTransparentBounds() {
- 0948 return transparentBounds;
- 0949 }
- 0950
- 0951 /**
- 0952 * Sets the transparency of region bounds for this matcher.
- 0953 *
- 0954 * <p> Invoking this method with an argument of <tt>true</tt> will set this
- 0955 * matcher to use <i>transparent</i> bounds. If the boolean
- 0956 * argument is <tt>false</tt>, then <i>opaque</i> bounds will be used.
- 0957 *
- 0958 * <p> Using transparent bounds, the boundaries of this
- 0959 * matcher's region are transparent to lookahead, lookbehind,
- 0960 * and boundary matching constructs. Those constructs can see beyond the
- 0961 * boundaries of the region to see if a match is appropriate.
- 0962 *
- 0963 * <p> Using opaque bounds, the boundaries of this matcher's
- 0964 * region are opaque to lookahead, lookbehind, and boundary matching
- 0965 * constructs that may try to see beyond them. Those constructs cannot
- 0966 * look past the boundaries so they will fail to match anything outside
- 0967 * of the region.
- 0968 *
- 0969 * <p> By default, a matcher uses opaque bounds.
- 0970 *
- 0971 * @param b a boolean indicating whether to use opaque or transparent
- 0972 * regions
- 0973 * @return this matcher
- 0974 * @see java.util.regex.Matcher#hasTransparentBounds
- 0975 * @since 1.5
- 0976 */
- 0977 public Matcher useTransparentBounds(boolean b) {
- 0978 transparentBounds = b;
- 0979 return this;
- 0980 }
- 0981
- 0982 /**
- 0983 * Queries the anchoring of region bounds for this matcher.
- 0984 *
- 0985 * <p> This method returns <tt>true</tt> if this matcher uses
- 0986 * <i>anchoring</i> bounds, <tt>false</tt> otherwise.
- 0987 *
- 0988 * <p> See {@link #useAnchoringBounds useAnchoringBounds} for a
- 0989 * description of anchoring bounds.
- 0990 *
- 0991 * <p> By default, a matcher uses anchoring region boundaries.
- 0992 *
- 0993 * @return <tt>true</tt> iff this matcher is using anchoring bounds,
- 0994 * <tt>false</tt> otherwise.
- 0995 * @see java.util.regex.Matcher#useAnchoringBounds(boolean)
- 0996 * @since 1.5
- 0997 */
- 0998 public boolean hasAnchoringBounds() {
- 0999 return anchoringBounds;
- 1000 }
- 1001
- 1002 /**
- 1003 * Sets the anchoring of region bounds for this matcher.
- 1004 *
- 1005 * <p> Invoking this method with an argument of <tt>true</tt> will set this
- 1006 * matcher to use <i>anchoring</i> bounds. If the boolean
- 1007 * argument is <tt>false</tt>, then <i>non-anchoring</i> bounds will be
- 1008 * used.
- 1009 *
- 1010 * <p> Using anchoring bounds, the boundaries of this
- 1011 * matcher's region match anchors such as ^ and $.
- 1012 *
- 1013 * <p> Without anchoring bounds, the boundaries of this
- 1014 * matcher's region will not match anchors such as ^ and $.
- 1015 *
- 1016 * <p> By default, a matcher uses anchoring region boundaries.
- 1017 *
- 1018 * @param b a boolean indicating whether or not to use anchoring bounds.
- 1019 * @return this matcher
- 1020 * @see java.util.regex.Matcher#hasAnchoringBounds
- 1021 * @since 1.5
- 1022 */
- 1023 public Matcher useAnchoringBounds(boolean b) {
- 1024 anchoringBounds = b;
- 1025 return this;
- 1026 }
- 1027
- 1028 /**
- 1029 * <p>Returns the string representation of this matcher. The
- 1030 * string representation of a <code>Matcher</code> contains information
- 1031 * that may be useful for debugging. The exact format is unspecified.
- 1032 *
- 1033 * @return The string representation of this matcher
- 1034 * @since 1.5
- 1035 */
- 1036 public String toString() {
- 1037 StringBuffer sb = new StringBuffer();
- 1038 sb.append("java.util.regex.Matcher");
- 1039 sb.append("[pattern=" + pattern());
- 1040 sb.append(" region=");
- 1041 sb.append(regionStart() + "," + regionEnd());
- 1042 sb.append(" lastmatch=");
- 1043 if ((first >= 0) && (group() != null)) {
- 1044 sb.append(group());
- 1045 }
- 1046 sb.append("]");
- 1047 return sb.toString();
- 1048 }
- 1049
- 1050 /**
- 1051 * <p>Returns true if the end of input was hit by the search engine in
- 1052 * the last match operation performed by this matcher.
- 1053 *
- 1054 * <p>When this method returns true, then it is possible that more input
- 1055 * would have changed the result of the last search.
- 1056 *
- 1057 * @return true iff the end of input was hit in the last match; false
- 1058 * otherwise
- 1059 * @since 1.5
- 1060 */
- 1061 public boolean hitEnd() {
- 1062 return hitEnd;
- 1063 }
- 1064
- 1065 /**
- 1066 * <p>Returns true if more input could change a positive match into a
- 1067 * negative one.
- 1068 *
- 1069 * <p>If this method returns true, and a match was found, then more
- 1070 * input could cause the match to be lost. If this method returns false
- 1071 * and a match was found, then more input might change the match but the
- 1072 * match won't be lost. If a match was not found, then requireEnd has no
- 1073 * meaning.
- 1074 *
- 1075 * @return true iff more input could change a positive match into a
- 1076 * negative one.
- 1077 * @since 1.5
- 1078 */
- 1079 public boolean requireEnd() {
- 1080 return requireEnd;
- 1081 }
- 1082
- 1083 /**
- 1084 * Initiates a search to find a Pattern within the given bounds.
- 1085 * The groups are filled with default values and the match of the root
- 1086 * of the state machine is called. The state machine will hold the state
- 1087 * of the match as it proceeds in this matcher.
- 1088 *
- 1089 * Matcher.from is not set here, because it is the "hard" boundary
- 1090 * of the start of the search which anchors will set to. The from param
- 1091 * is the "soft" boundary of the start of the search, meaning that the
- 1092 * regex tries to match at that index but ^ won't match there. Subsequent
- 1093 * calls to the search methods start at a new "soft" boundary which is
- 1094 * the end of the previous match.
- 1095 */
- 1096 boolean search(int from) {
- 1097 this.hitEnd = false;
- 1098 this.requireEnd = false;
- 1099 from = from < 0 ? 0 : from;
- 1100 this.first = from;
- 1101 this.oldLast = oldLast < 0 ? from : oldLast;
- 1102 for (int i = 0; i < groups.length; i++)
- 1103 groups[i] = -1;
- 1104 acceptMode = NOANCHOR;
- 1105 boolean result = parentPattern.root.match(this, from, text);
- 1106 if (!result)
- 1107 this.first = -1;
- 1108 this.oldLast = this.last;
- 1109 return result;
- 1110 }
- 1111
- 1112 /**
- 1113 * Initiates a search for an anchored match to a Pattern within the given
- 1114 * bounds. The groups are filled with default values and the match of the
- 1115 * root of the state machine is called. The state machine will hold the
- 1116 * state of the match as it proceeds in this matcher.
- 1117 */
- 1118 boolean match(int from, int anchor) {
- 1119 this.hitEnd = false;
- 1120 this.requireEnd = false;
- 1121 from = from < 0 ? 0 : from;
- 1122 this.first = from;
- 1123 this.oldLast = oldLast < 0 ? from : oldLast;
- 1124 for (int i = 0; i < groups.length; i++)
- 1125 groups[i] = -1;
- 1126 acceptMode = anchor;
- 1127 boolean result = parentPattern.matchRoot.match(this, from, text);
- 1128 if (!result)
- 1129 this.first = -1;
- 1130 this.oldLast = this.last;
- 1131 return result;
- 1132 }
- 1133
- 1134 /**
- 1135 * Returns the end index of the text.
- 1136 *
- 1137 * @return the index after the last character in the text
- 1138 */
- 1139 int getTextLength() {
- 1140 return text.length();
- 1141 }
- 1142
- 1143 /**
- 1144 * Generates a String from this Matcher's input in the specified range.
- 1145 *
- 1146 * @param beginIndex the beginning index, inclusive
- 1147 * @param endIndex the ending index, exclusive
- 1148 * @return A String generated from this Matcher's input
- 1149 */
- 1150 CharSequence getSubSequence(int beginIndex, int endIndex) {
- 1151 return text.subSequence(beginIndex, endIndex);
- 1152 }
- 1153
- 1154 /**
- 1155 * Returns this Matcher's input character at index i.
- 1156 *
- 1157 * @return A char from the specified index
- 1158 */
- 1159 char charAt(int i) {
- 1160 return text.charAt(i);
- 1161 }
- 1162
- 1163}
