2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2002-02-03 22:00:42 +00:00
|
|
|
<title>Replace Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="replace">Replace</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><code>Replace</code> is a directory based task for replacing the occurrence of a given string
|
|
|
|
|
with another string in selected file.</p>
|
|
|
|
|
<p>If you want to replace a text that crosses line boundaries, you must use a
|
|
|
|
|
nested <code><replacetoken></code> element.</p>
|
2003-07-23 12:57:18 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>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.</p>
|
2003-07-23 12:57:18 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>file</td>
|
|
|
|
|
<td>file for which the token should be replaced.</td>
|
|
|
|
|
<td rowspan="2">Exactly one of the two</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>dir</td>
|
|
|
|
|
<td class="left">The base directory to use when replacing a token in multiple files.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-09-19 12:10:25 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>The encoding of the files upon which replace operates.</td>
|
|
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2001-09-19 12:10:25 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>token</td>
|
|
|
|
|
<td>the token which must be replaced.</td>
|
|
|
|
|
<td>Yes, unless a nested <code>replacetoken</code> element or the <var>replacefilterfile</var>
|
|
|
|
|
attribute is used.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>value</td>
|
|
|
|
|
<td>the new value for the token.</td>
|
|
|
|
|
<td>No; defaults to empty string (<q></q>)</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-07-30 13:35:23 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>summary</td>
|
|
|
|
|
<td>Indicates whether a summary of the replace operation should be produced, detailing how many
|
|
|
|
|
token occurrences and files were processed</td>
|
|
|
|
|
<td>No; defaults to no summary</td>
|
2001-07-30 13:35:23 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>propertyFile</td>
|
|
|
|
|
<td>valid property file from which properties specified using
|
|
|
|
|
nested <code><replacefilter></code> elements are drawn.</td>
|
|
|
|
|
<td>Yes, only if <var>property</var> attribute of <code><replacefilter></code> is
|
|
|
|
|
used.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-04-12 10:17:53 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>replacefilterfile</td>
|
|
|
|
|
<td>valid property file. Each property will be treated as a <code>replacefilter</code>
|
|
|
|
|
where <var>token</var> is the name of the property and <var>value</var> is the property's
|
|
|
|
|
value.</td>
|
|
|
|
|
<td>No</td>
|
2002-04-12 10:17:53 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be included.</td>
|
|
|
|
|
<td>No; defaults to all (<q>**</q>)</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an include pattern</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be excluded.</td>
|
|
|
|
|
<td>No; defaults to default excludes or none if <var>defaultexcludes</var> is <q>no</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an exclude pattern</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>defaultexcludes</td>
|
|
|
|
|
<td>indicates whether default excludes should be used or not (<q>yes|no</q>).</td>
|
|
|
|
|
<td>No; defaults to <q>yes</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2008-12-05 16:38:47 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>preserveLastModified</td>
|
|
|
|
|
<td>Keep the file timestamp(s) even if the file(s) is(are) modified. <em>since Apache Ant
|
|
|
|
|
1.8.0</em>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2008-12-05 16:38:47 +00:00
|
|
|
</tr>
|
2008-12-08 15:13:09 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failOnNoReplacements</td>
|
|
|
|
|
<td>Whether to fail the build if the task didn't do anything. <em>since Ant 1.8.0</em>.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2008-12-08 15:13:09 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
<h3>Examples</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><replace file="${src}/index.html" token="@@@" value="wombat"/></pre>
|
|
|
|
|
<p>replaces occurrences of the string <q>@@@</q> with the string <q>wombat</q>, in the
|
|
|
|
|
file <samp>${src}/index.html</samp>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and supports most
|
|
|
|
|
attributes of <code><fileset></code> as well as the
|
|
|
|
|
nested <code><include></code>, <code><exclude></code>
|
|
|
|
|
and <code><patternset></code> elements.</p>
|
|
|
|
|
<p><em>Since Ant 1.8.0</em>, this task supports any filesystem
|
|
|
|
|
based <a href="../Types/resources.html#collection">resource collections</a> as nested elements.</p>
|
2008-12-05 17:04:04 +00:00
|
|
|
<h4>replacetoken and replacevalue</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>If either the text you want to replace or the replacement text cross line boundaries, you can use
|
|
|
|
|
nested elements to specify them.</p>
|
2008-12-05 17:04:04 +00:00
|
|
|
<p>The elements support attributes:</p>
|
2018-03-05 21:01:42 +01:00
|
|
|
<table class="attr">
|
2008-12-05 17:04:04 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2008-12-05 17:04:04 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>expandProperties</td>
|
|
|
|
|
<td>Whether to expand properties in the nested text. <em>Since Ant 1.8.0</em>.</td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2008-12-05 17:04:04 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2001-02-13 12:32:01 +00:00
|
|
|
<replace dir="${src}" value="wombat">
|
|
|
|
|
<include name="**/*.html"/>
|
|
|
|
|
<replacetoken><![CDATA[multi line
|
2002-09-03 15:24:08 +00:00
|
|
|
token]]></replacetoken>
|
2018-02-28 07:58:59 +01:00
|
|
|
</replace></pre>
|
|
|
|
|
<p>replaces occurrences of the string <q>multi line<i>\n</i>token</q> with the string <q>wombat</q>,
|
|
|
|
|
in all HTML files in the directory <samp>${src}</samp>. Here, <q><i>\n</i></q> is the platform
|
|
|
|
|
specific line separator.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2001-02-13 12:32:01 +00:00
|
|
|
<replace file="${src}/index.html">
|
|
|
|
|
<replacetoken><![CDATA[two line
|
2002-09-03 15:24:08 +00:00
|
|
|
token]]></replacetoken>
|
2001-02-13 12:32:01 +00:00
|
|
|
<replacevalue><![CDATA[two line
|
2002-09-03 15:24:08 +00:00
|
|
|
token]]></replacevalue>
|
2018-02-28 07:58:59 +01:00
|
|
|
</replace></pre>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h4>replacefilter</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>In addition to allowing for multiple replacements, optional
|
|
|
|
|
nested <code><replacefilter></code> elements allow replacement values to be extracted from a
|
|
|
|
|
property file. The name of this file is specified using the <code><replace></code>
|
|
|
|
|
attribute <var>propertyFile</var>.</p>
|
|
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>token</td>
|
|
|
|
|
<td>The string to search for.</td>
|
|
|
|
|
<td>Yes, unless a nested <code>replacetoken</code>
|
2008-12-05 16:08:46 +00:00
|
|
|
is specified</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>value</td>
|
|
|
|
|
<td>The replacement string.</td>
|
|
|
|
|
<td rowspan="2">Either may be specified, but not both. Both can be omitted, if desired.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>property</td>
|
|
|
|
|
<td class="left">Name of the property whose value is to serve as the replacement value.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><em>Since Ant 1.8.0</em>, <var>token</var> and <var>value</var> can be specified as nested
|
|
|
|
|
elements just like in the task itself.</p>
|
|
|
|
|
<p>If neither <var>value</var> nor <var>property</var> is used, the value provided using
|
|
|
|
|
the <code><replace></code> attribute <var>value</var> and/or
|
|
|
|
|
the <code><replacevalue></code> element is used. If no value was specified using either of
|
|
|
|
|
these options, the token is replaced with an empty string.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>In file <samp>configure.sh</samp>, replace all instances of <q>@token1@</q>
|
|
|
|
|
with <q>defaultvalue</q>, all instances of <q>@token2@</q> with <q>value2</q>, and all instances
|
|
|
|
|
of <q>@token3@</q> with the value of the property <code>property.key</code>, as it appears in
|
|
|
|
|
property file <samp>src/name.properties</samp>.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<replace file="configure.sh"
|
|
|
|
|
value="defaultvalue"
|
|
|
|
|
propertyFile="src/name.properties">
|
|
|
|
|
<replacefilter token="@token1@"/>
|
|
|
|
|
<replacefilter token="@token2@"
|
|
|
|
|
value="value2"/>
|
|
|
|
|
<replacefilter token="@token3@"
|
|
|
|
|
property="property.key"/>
|
2008-12-05 16:08:46 +00:00
|
|
|
<replacefilter>
|
2018-01-22 23:52:21 +01:00
|
|
|
<replacetoken>@token4@</replacetoken>
|
2008-12-05 16:08:46 +00:00
|
|
|
<replacevalue>value4</replacevalue>
|
|
|
|
|
</replacefilter>
|
2018-02-28 07:58:59 +01:00
|
|
|
</replace></pre>
|
|
|
|
|
<p><strong>Note</strong>: It is possible to use either
|
|
|
|
|
the <var>token</var>/<code><replacetoken></code>
|
|
|
|
|
and <var>value</var>/<code><replacevalue></code> attributes/elements, the
|
|
|
|
|
nested <code>replacefilter</code> elements, or both in the same operation.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
