2001-11-12 11:26:48 +00:00
< html >
< head >
< meta http-equiv = "Content-Language" content = "en-us" >
2002-02-03 22:11:39 +00:00
< title > ReplaceRegeExp Task< / title >
2001-11-12 11:26:48 +00:00
< / 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
2002-01-30 21:32:08 +00:00
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 >
2001-11-12 11:26:48 +00:00
and < a href = "http://jakarta.apache.org/oro/" target = "_top" > jakarta-ORO< / a > ,
but you will still need the library itself.< / p >
2002-01-30 21:32:08 +00:00
< 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
2002-02-22 06:45:09 +00:00
expression library you use. It is 'highly recommended' that you test your pattern on
both Unix and Windows platforms before you rely on it.
2002-01-30 21:32:08 +00:00
< 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 >
2002-02-22 06:45:09 +00:00
We < b > strongly< / b > recommend that you use Jakarta Oro.
2002-01-30 21:32:08 +00:00
< / i >
< / p >
2001-11-12 11:26:48 +00:00
< 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 < fileset> is used< / td >
< / tr >
< tr >
< td valign = "top" > match< / td >
< td valign = "top" > The regular expression pattern to match in the file(s)< / td >
2002-02-19 16:48:47 +00:00
< td align = "center" > Yes, if no nested < regexp> is used< / td >
2001-11-12 11:26:48 +00:00
< / tr >
< tr >
< td valign = "top" > replace< / td >
2002-02-03 21:26:18 +00:00
< td valign = "top" > The substitution pattern to place in the file(s) in place
2001-11-12 11:26:48 +00:00
of the regular expression.< / td >
< td align = "center" > Yes, if no nested < substitution> 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 / >
2002-02-03 21:26:18 +00:00
g --> Global replacement. Replace all occurences found< br / >
2001-11-12 11:26:48 +00:00
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
2002-02-03 21:26:18 +00:00
want to only replace the first occurence of a regular expression on
2001-11-12 11:26:48 +00:00
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 >
2002-01-30 21:32:08 +00:00
< pre > < replaceregexp file=" ${src}/build.properties"
2001-11-12 11:26:48 +00:00
match=" OldProperty=(.*)"
replace=" NewProperty=\1"
byline=" true" />
< / pre >
< p > replaces occurrences of the property name " OldProperty"
with " NewProperty" in a properties file, preserving the existing
value, in the file < code > ${src}/build.properties< / code > < / p >
< h3 > Parameters specified as nested elements< / h3 >
2002-01-30 21:32:08 +00:00
< p > This task supports a nested < a href = "../CoreTypes/fileset.html" > FileSet< / a >
2001-11-12 11:26:48 +00:00
element.< / p >
2002-02-19 16:48:47 +00:00
< p > This task supports a nested < i > Regexp< / i > element to specify
2001-11-12 11:26:48 +00:00
the regular expression. You can use this element to refer to a previously
defined regular expression datatype instance.< / p >
< blockquote >
2002-02-19 16:48:47 +00:00
< regexp id="id" pattern="expression" /> < br / >
< regexp refid="id" />
2001-11-12 11:26:48 +00:00
< / 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
2002-02-03 21:26:18 +00:00
defined substitution pattern datatype instance.< / p >
2001-11-12 11:26:48 +00:00
< blockquote >
< substitution id="id" pattern="expression" /> < br / >
< substitution refid="id" />
< / blockquote >
< h3 > Examples< / h3 >
< blockquote >
< pre >
< replaceregexp byline=" true" >
2002-02-19 16:48:47 +00:00
< regexp expression=" OldProperty=(.*)" />
2001-11-12 11:26:48 +00:00
< substitution expression=" NewProperty=\1" />
< fileset dir=" ." >
< includes=" *.properties" />
< /fileset>
< /replaceregexp>
< / pre > < / blockquote >
< p > replaces occurrences of the property name " OldProperty"
with " NewProperty" in a properties file, preserving the existing
value, in all files ending in < code > .properties< / code > in the current directory< / p >
< hr >
2002-01-31 09:24:16 +00:00
< p align = "center" > Copyright © 2001-2002 Apache Software Foundation. All rights
2001-11-12 11:26:48 +00:00
Reserved.< / p >
< / body >
< / html >
