Perl5Substitution implements a Substitution consisting of a literal string, but allowing Perl5 variable interpolation referencing saved groups in a match. This class is intended for use with {@link Util#substitute Util.substitute}.
The substitution string may contain variable interpolations referring to the saved parenthesized groups of the search pattern. A variable interpolation is denoted by $1, or $2, or $3, etc. If you want such expressions to be interpreted literally, you should set the numInterpolations parameter to INTERPOLATE_NONE . It is easiest to explain what an interpolated variable does by giving an example:
Suppose you have the pattern b\d+: and you want to substitute the b's for a's and the colon for a dash in parts of your input matching the pattern. You can do this by changing the pattern to b(\d+): and using the substitution expression a$1-. When a substitution is made, the $1 means "Substitute whatever was matched by the first saved group of the matching pattern." An input of b123: after substitution would yield a result of a123-. But there's a little more to be aware of. If you set the numInterpolations parameter to INTERPOLATE_ALL, then every time a match is found, the interpolation variables are computed relative to that match. But if numInterpolations is set to some positive integer, then only the interpolation variables for the first numInterpolations matches are computed relative to the most recent match. After that, the remaining substitutions have their variable interpolations performed relative to the numInterpolations 'th match. So using the previously mentioned pattern and substitution expression, if you have an input of
Tank b123: 85 Tank b256: 32 Tank b78: 22
and use a
numInterpolations value of
INTERPOLATE_ALL and
numSubs value (see {@link Util#substitute Util.substitute}) of
SUBSTITUTE_ALL, then your result will be:
Tank a123- 85 Tank a256- 32 Tank a78- 22
But if you set
numInterpolations to 2 and keep
numSubs with a value of
SUBSTITUTE_ALL, your result is:
Tank a123- 85 Tank a256- 32 Tank a256- 22
Notice how the last substitution uses the same value for
$1 as the second substitution.
A final thing to keep in mind is that if you use an interpolation variable that corresponds to a group not contained in the match, then it is interpreted as the empty string. So given the regular expression from the example, and a substitution expression of a$2-, the result of the last sample input would be:
Tank a- 85 Tank a- 32 Tank a- 22
The special substitution
$& will interpolate the entire portion of the input matched by the regular expression.
$0 will do the same, but it is recommended that it be avoided because the latest versions of Perl use
$0 to store the program name rather than duplicate the behavior of
$&. Also, the result of substituting $ followed by a non-positive integer is undefined. In order to include a $ in a substitution, it should be escaped with a backslash (e.g.,
"\\$0").
Perl5 double-quoted string case modification is also supported in the substitution. The following escape sequences are supported:
- \\U
- make substitution uppercase until end of substitution or \\E
- \\u
- make next character uppercase
- \\L
- make substitution uppercase until end of substitution or \\E
- \\l
- make next character uppercase
- \\E
- mark the end of the case modification
The double backslashes are shown to remind you that to make a backslash get past Java's string handling and appear as a backslash to the substitution, you must escape the backslash.
@version @version@
@since 1.1
@see Substitution
@see Util
@see Util#substitute
@see Substitution
@see StringSubstitution