youys
/
ant

 
			
			   
				 
					
						
						
							
							<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Ant User Manual</title>
</head>

<body>

<h2><a name="replace">ReplaceRegExp</a></h2>
<h3>Description</h3>
<p>ReplaceRegExp is a directory based task for replacing the
occurrence of a given regular expression with a substitution pattern
in a selected file or set of files.</p>

<p>Similar to <a href="../CoreTypes/mapper.html#regexp-mapper">regexp
type mappers</a> this task needs a supporting regular expression
library and an implementation of
<code>org.apache.tools.ant.util.regexp.Regexp</code>.  Ant comes with
implementations for
<a href="http://java.sun.com/j2se/1.4/docs/api/java/util/regex/package-summary.html" target="_top">the java.util.regex package of JDK 1.4</a>,
<a href="http://jakarta.apache.org/regexp/" target="_top">jakarta-regexp</a>
and <a href="http://jakarta.apache.org/oro/" target="_top">jakarta-ORO</a>,
but you will still need the library itself.</p>
<p>
<i>
There are cross-platform issues for matches related to line terminator.
For example if you use $ to anchor your regular expression on the end of a line
the results might be very different depending on both your platform and the regular
expression library you use. It is 'highly recommended' to tests your pattern on
Unix and Windows platforms before you rely on it.
<ul>
    <li>Jakarta Oro defines a line terminator as '\n' and is consistent with Perl.</li>
    <li>Jakarta RegExp uses a system-dependant line terminator.</li>
    <li>JDK 1.4 uses '\n', '\r\n', '\u0085', '\u2028', '\u2029' as a default
    but is configured in the wrapper to use only '\n' (UNIX_LINE)</li>
</ul>
It is <b>strongly</b> recommended to use Jakarta Oro.
</i>
</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 regular expression should be replaced.</td>
    <td align="center">Yes if no nested &lt;fileset&gt; is used</td>
  </tr>
  <tr>
    <td valign="top">match</td>
    <td valign="top">The regular expression pattern to match in the file(s)</td>
    <td align="center">Yes, if no nested &lt;regularexpression&gt; is used</td>
  </tr>
  <tr>
    <td valign="top">replace</td>
    <td valign="top">The substitution pattern to place in the file(s) in place
                     of the regular expression.</td>
    <td align="center">Yes, if no nested &lt;substitution&gt; is used</td>
  </tr>
  <tr>
    <td valign="top">flags</td>
    <td valign="top">The flags to use when matching the regular expression.  For more
                     information, consult the Perl5 syntax<br />
                     g --> Global replacement.  Replace all occurences found<br />
                     i --> Case Insensitive.  Do not consider case in the match<br />
                     m --> Multiline.  Treat the string as multiple lines of input, using "^" and "$" as the start or end of any line, respectively, rather than start or end of string.<br />
                     s --> Singleline.  Treat the string as a single line of input, using "." to match any character, including a newline, which normally, it would not match.<br />
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">byline</td>
    <td valign="top">Process the file(s) one line at a time, executing the replacement
                     on one line at a time (<i>true/false</i>).  This is useful if you
                     want to only replace the first occurence of a regular expression on
                     each line, which is not easy to do when processing the file as a whole.
                     Defaults to <i>false</i>.</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>
<h3>Examples</h3>
<pre>  &lt;replaceregexp file=&quot;${src}/build.properties&quot;
                         match=&quot;OldProperty=(.*)&quot;
                         replace=&quot;NewProperty=\1&quot;
                         byline=&quot;true&quot; /&gt;
</pre>
<p>replaces occurrences of the property name &quot;OldProperty&quot;
 with &quot;NewProperty&quot; in a properties file, preserving the existing
value, in the file <code>${src}/build.properties</code></p>
<h3>Parameters specified as nested elements</h3>
<p>This task supports a nested <a href="../CoreTypes/fileset.html">FileSet</a>
   element.</p>
<p>This task supports a nested <i>RegularExpression</i> element to specify
   the regular expression.  You can use this element to refer to a previously
   defined regular expression datatype instance.</p>
<blockquote>
     &lt;regularexpression id="id" pattern="expression" /&gt;<br />
     &lt;regularexpression refid="id" /&gt;
</blockquote>
<p>This task supports a nested <i>Substitution</i> element to specify
   the substitution pattern.  You can use this element to refer to a previously
   defined substitution pattern datatype instance.</p>
<blockquote>
     &lt;substitution id="id" pattern="expression" /&gt;<br />
     &lt;substitution refid="id" /&gt;
</blockquote>
<h3>Examples</h3>
<blockquote>
  <pre>
&lt;replaceregexp byline=&quot;true&quot;&gt;
  &lt;regularexpression expression=&quot;OldProperty=(.*)&quot; /&gt;
  &lt;substitution expression=&quot;NewProperty=\1&quot; /&gt;
  &lt;fileset dir=&quot;.&quot;&gt;
   &lt;includes=&quot;*.properties&quot; /&gt;
  &lt;/fileset&gt;
 &lt;/replaceregexp&gt;
</pre></blockquote>
<p>replaces occurrences of the property name &quot;OldProperty&quot;
 with &quot;NewProperty&quot; in a properties file, preserving the existing
value, in all files ending in <code>.properties</code> in the current directory</p>

<hr>
<p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>