Description
Replace is a directory based task for replacing the occurrence of a given string with another string
in selected file.
If you want to replace a text that crosses line boundaries, you
must use a nested <replacetoken> element.
Parameters
Attribute |
Description |
Required |
file |
file for which the token should be replaced. |
Exactly one of the two. |
dir |
The base directory to use when replacing a token in
multiple files. |
encoding |
The encoding of the files upon which replace operates. |
No - defaults to default JVM encoding |
token |
the token which must be replaced. |
Yes, unless a nested
replacetoken element or the replacefilterfile
attribute is used. |
value |
the new value for the token. When omitted, an empty string
("") is used. |
No |
summary |
Indicates whether a summary of the replace operation
should be produced, detailing how many token occurrences
and files were processed
|
No, by default no summary is produced |
propertyFile |
valid property file from which properties specified using nested <replacefilter> elements are drawn. |
Yes only if property attribute of <replacefilter> is used. |
replacefilterfile |
valid property file. Each property will be
treated as a replacefilter where token is the name of
the property and value is the properties value.
| No. |
includes |
comma- or space-separated list of patterns of files that must be
included. All files are included when omitted. |
No |
includesfile |
the name of a file. Each line of this file is
taken to be an include pattern |
No |
excludes |
comma- or space-separated list of patterns of files that must be
excluded. No files (except default excludes) are excluded when omitted. |
No |
excludesfile |
the name of a file. Each line of this file is
taken to be an exclude pattern |
No |
defaultexcludes |
indicates whether default excludes should be used or not
("yes"/"no"). Default excludes are used when omitted. |
No |
Examples
<replace file="${src}/index.html" token="@@@" value="wombat"/>
replaces occurrences of the string "@@@" with the string
"wombat", in the file ${src}/index.html .
Parameters specified as nested elements
This task forms an implicit FileSet and
supports all attributes of <fileset> as well as the
nested <include> , <exclude> and
<patternset> elements.
If either the text you want to replace or the replacement text
cross line boundaries, you can use nested elements to specify
them.
Examples
<replace dir="${src}" value="wombat">
<include name="**/*.html"/>
<replacetoken><![CDATA[multi line
token]]></replacetoken>
</replace>
replaces occurrences of the string "multi
line\ntoken" with the string "wombat", in all
HTML files in the directory ${src} .Where \n is
the platform specific line separator.
<replace file="${src}/index.html">
<replacetoken><![CDATA[two line
token]]></replacetoken>
<replacevalue><![CDATA[two line
token]]></replacevalue>
</replace>
replacefilter
In addition to allowing for multiple replacements, optional nested <replacefilter> elements allow replacement values to be extracted from a property file. The name of this file is specified using the <replace> attribute propertyFile.
Attribute |
Description |
Required |
token |
The string to search for. |
Yes |
value |
The replacement string. |
Either may be specified, but not both. Both can be omitted, if desired. |
property |
Name of the property whose value is to serve as the replacement value. |
If neither value nor property is used, the value provided using the <replace> attribute value and/or the <replacevalue> element is used. If no value was specified using either of these options, the token is replaced with an empty string.
Examples
<replace
file="configure.sh"
value="defaultvalue"
propertyFile="source/name.properties">
<replacefilter
token="@token1@"/>
<replacefilter
token="@token2@"
value="value2"/>
<replacefilter
token="@token3@"
property="property.key"/>
</replace>
In file configure.sh , replace all instances of "@token1@" with "defaultvalue", all instances of "@token2@" with "value2", and all instances of "@token3@" with the value of the property "property.key", as it appears in property file src/name.properties .
Note: It is possible to use either the token/<replacetoken> and value/<replacevalue> attributes/elements, the nested replacefilter elements, or both in the same operation.
Copyright © 2000-2002 Apache Software Foundation. All rights
Reserved.
|