mirror of
https://github.com/apache/ant.git
synced 2025-05-15 12:42:44 +00:00
e967d77e02
PR: 5020 Reported By: jesse.glick@netbeans.com (Jesse Glick) git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271131 13f79535-47bb-0310-9956-ffa450edef68
178 lines
7.2 KiB
HTML
178 lines
7.2 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<title>Replace Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h2><a name="replace">Replace</a></h2>
|
|
<h3>Description</h3>
|
|
<p>Replace 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>
|
|
<h3>Parameters</h3>
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
<tr>
|
|
<td valign="top"><b>Attribute</b></td>
|
|
<td valign="top"><b>Description</b></td>
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">file</td>
|
|
<td valign="top">file for which the token should be replaced.</td>
|
|
<td align="center" rowspan="2">Exactly one of the two.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">dir</td>
|
|
<td valign="top">The base directory to use when replacing a token in
|
|
multiple files.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">encoding</td>
|
|
<td valign="top">The encoding of the files upon which replace operates.</td>
|
|
<td align="center">No - defaults to default JVM encoding</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">token</td>
|
|
<td valign="top">the token which must be replaced.</td>
|
|
<td valign="top" align="center">Yes, unless a nested <code>replacetoken</code>
|
|
element is used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">value</td>
|
|
<td valign="top">the new value for the token. When omitted, an empty string
|
|
("") is used.</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">summary</td>
|
|
<td valign="top">Indicates whether a summary of the replace operation
|
|
should be produced, detailing how many token occurrences
|
|
and files were processed
|
|
</td>
|
|
<td valign="top" align="center">No, by default no summary is produced</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">propertyFile</td>
|
|
<td valign="top">valid property file from which properties specified using nested <code><replacefilter></code> elements are drawn.</td>
|
|
<td valign="top" align="center">Yes only if <i>property</i> attribute of <code><replacefilter></code> is used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">includes</td>
|
|
<td valign="top">comma separated list of patterns of files that must be
|
|
included. All files are included when omitted.</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">includesfile</td>
|
|
<td valign="top">the name of a file. Each line of this file is
|
|
taken to be an include pattern</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">excludes</td>
|
|
<td valign="top">comma separated list of patterns of files that must be
|
|
excluded. No files (except default excludes) are excluded when omitted.</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">excludesfile</td>
|
|
<td valign="top">the name of a file. Each line of this file is
|
|
taken to be an exclude pattern</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">defaultexcludes</td>
|
|
<td valign="top">indicates whether default excludes should be used or not
|
|
("yes"/"no"). Default excludes are used when omitted.</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
</table>
|
|
<h3>Examples</h3>
|
|
<pre> <replace file="${src}/index.html" token="@@@" value="wombat"/></pre>
|
|
<p>replaces occurrences of the string "@@@" with the string
|
|
"wombat", in the file <code>${src}/index.html</code>.</p>
|
|
<h3>Parameters specified as nested elements</h3>
|
|
<p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
|
|
supports all attributes of <code><fileset></code> as well as the
|
|
nested <code><include></code>, <code><exclude></code> and
|
|
<code><patternset></code> elements.</p>
|
|
<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>
|
|
<h3>Examples</h3>
|
|
<blockquote><pre>
|
|
<replace dir="${src}" value="wombat">
|
|
<include name="**/*.html"/>
|
|
<replacetoken><![CDATA[multi line
|
|
token]]></replacetoken>
|
|
</replace>
|
|
</pre></blockquote>
|
|
<p>replaces occurrences of the string "multi
|
|
line<i>\n</i>token" with the string "wombat", in all
|
|
HTML files in the directory <code>${src}</code>.Where <i>\n</i> is
|
|
the platform specific line separator.</p>
|
|
<blockquote><pre>
|
|
<replace file="${src}/index.html">
|
|
<replacetoken><![CDATA[two line
|
|
token]]></replacetoken>
|
|
<replacevalue><![CDATA[two line
|
|
token]]></replacevalue>
|
|
</replace>
|
|
</pre></blockquote>
|
|
<h4>replacefilter</h4>
|
|
<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 <i>propertyFile</i>.
|
|
</p>
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
<tr>
|
|
<td valign="top"><b>Attribute</b></td>
|
|
<td valign="top"><b>Description</b></td>
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">token</td>
|
|
<td valign="top">The string to search for.</td>
|
|
<td align="center" valign="top">Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">value</td>
|
|
<td valign="top">The replacement string.</td>
|
|
<td align="center" rowspan="2">Either may be specified, but not both. Both can be omitted, if desired.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">property</td>
|
|
<td valign="top">Name of the property whose value is to serve as the replacement value.</td>
|
|
</tr>
|
|
</table>
|
|
<p>If neither <i>value</i> nor <i>property</i> is used, the value provided using the <code><replace></code> attribute <i>value</i> 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>
|
|
<h3>Examples</h3>
|
|
<blockquote><pre>
|
|
<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>
|
|
</pre></blockquote>
|
|
<p>In file <code>configure.sh</code>, 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 <code>src/name.properties</code>.</p>
|
|
<p><b>Note:</b> It is possible to use either the <i>token</i>/<code><replacetoken></code> and <i>value</i>/<code><replacevalue></code> attributes/elements, the nested replacefilter elements, or both in the same operation.
|
|
</p>
|
|
<hr>
|
|
<p align="center">Copyright © 2001 Apache Software Foundation. All rights
|
|
Reserved.</p>
|
|
|
|
</body>
|
|
</html>
|
|
|