001: /*
002: * $Id: Substitution.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 Substitution interface provides a means for you to control how
062: * a substitution is performed when using the
063: * {@link Util#substitute Util.substitute} method. Two standard
064: * implementations are provided,
065: * {@link StringSubstitution} and {@link Perl5Substitution}. To
066: * achieve custom control over the behavior of substitutions, you can
067: * create your own implementations. A common use for customization is
068: * to make a substitution a function of a match.
069: *
070: * @version @version@
071: * @since 1.1
072: * @see Util
073: * @see Util#substitute
074: * @see StringSubstitution
075: * @see Perl5Substitution
076: */
077: public interface Substitution {
078:
079: /**
080: * Appends the substitution to a buffer containing the original input
081: * with substitutions applied for the pattern matches found so far.
082: * For maximum flexibility, the original input as well as the
083: * PatternMatcher and Pattern used to find the match are included as
084: * arguments. However, you will almost never find a need to use those
085: * arguments when creating your own Substitution implementations.
086: * <p>
087: * For performance reasons, rather than provide a getSubstitution method
088: * that returns a String used by Util.substitute, we have opted to pass
089: * a StringBuffer argument from Util.substitute to which the Substitution
090: * must append data. The contract that an appendSubstitution
091: * implementation must abide by is that the appendBuffer may only be
092: * appended to. appendSubstitution() may not alter the appendBuffer in
093: * any way other than appending to it.
094: * <p>
095: * This method is invoked by Util.substitute every time it finds a match.
096: * After finding a match, Util.substitute appends to the appendBuffer
097: * all of the original input occuring between the end of the last match
098: * and the beginning of the current match. Then it invokes
099: * appendSubstitution(), passing the appendBuffer, current match, and
100: * other information as arguments. The substitutionCount keeps track
101: * of how many substitutions have been performed so far by an invocation
102: * of Util.substitute. Its value starts at 1 when the first substitution
103: * is found and appendSubstitution is invoked for the first time. It
104: * will NEVER be zero or a negative value.
105: * <p>
106: * @param appendBuffer The buffer containing the new string resulting
107: * from performing substitutions on the original input.
108: * @param match The current match causing a substitution to be made.
109: * @param substitutionCount The number of substitutions that have been
110: * performed so far by Util.substitute.
111: * @param originalInput The original input upon which the substitutions are
112: * being performed. The Substitution must treat this parameter as read only.
113: * @param matcher The PatternMatcher used to find the current match.
114: * @param pattern The Pattern used to find the current match.
115: */
116: public void appendSubstitution(StringBuffer appendBuffer,
117: MatchResult match, int substitutionCount,
118: PatternMatcherInput originalInput, PatternMatcher matcher,
119: Pattern pattern);
120: }
|