The Substitution interface provides a means for you to control how
a substitution is performed when using the
Util.substitute method. Two standard
implementations are provided,
StringSubstitution and Perl5Substitution. To
achieve custom control over the behavior of substitutions, you can
create your own implementations. A common use for customization is
to make a substitution a function of a match.
Appends the substitution to a buffer containing the original input
with substitutions applied for the pattern matches found so far.
For maximum flexibility, the original input as well as the
PatternMatcher and Pattern used to find the match are included as
arguments. However, you will almost never find a need to use those
arguments when creating your own Substitution implementations.
For performance reasons, rather than provide a getSubstitution method
that returns a String used by Util.substitute, we have opted to pass
a StringBuffer argument from Util.substitute to which the Substitution
must append data. The contract that an appendSubstitution
implementation must abide by is that the appendBuffer may only be
appended to. appendSubstitution() may not alter the appendBuffer in
any way other than appending to it.
This method is invoked by Util.substitute every time it finds a match.
After finding a match, Util.substitute appends to the appendBuffer
all of the original input occuring between the end of the last match
and the beginning of the current match. Then it invokes
appendSubstitution(), passing the appendBuffer, current match, and
other information as arguments. The substitutionCount keeps track
of how many substitutions have been performed so far by an invocation
of Util.substitute. Its value starts at 1 when the first substitution
is found and appendSubstitution is invoked for the first time. It
will NEVER be zero or a negative value.
appendBuffer - The buffer containing the new string resulting
from performing substitutions on the original input.
match - The current match causing a substitution to be made.
substitutionCount - The number of substitutions that have been
performed so far by Util.substitute.
originalInput - The original input upon which the substitutions are
being performed. The Substitution must treat this parameter as read only.
matcher - The PatternMatcher used to find the current match.
pattern - The Pattern used to find the current match.