Replace Task

## Replace

### 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.

The output file is only written if it differs from the existing file. This prevents spurious rebuilds based on unchanged files which have been regenerated by this task.

### 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.