Top Description Fields Constructors Methods
org.apache.tools.ant.taskdefs.optional

public Class ReplaceRegExp

extends Task
Class Inheritance
Imports
java.io.BufferedReader, .BufferedWriter, .File, .IOException, .InputStream, .InputStreamReader, .OutputStream, .OutputStreamWriter, .Reader, .Writer, java.nio.charset.Charset, java.nio.file.Files, org.apache.tools.ant.BuildException, .Project, .Task, org.apache.tools.ant.types.FileSet, .RegularExpression, .Resource, .ResourceCollection, .Substitution, org.apache.tools.ant.types.resources.FileProvider, .Union, org.apache.tools.ant.util.FileUtils, org.apache.tools.ant.util.regexp.Regexp, .RegexpUtil
Performs regular expression string replacements in a text file. The input file(s) must be able to be properly processed by a Reader instance. That is, they must be text only, no binary. The syntax of the regular expression depends on the implementation that you choose to use. The system property ant.regexp.regexpimpl will be the classname of the implementation that will be used (the default is org.apache.tools.ant.util.regexp.JakartaOroRegexp and requires the Jakarta Oro Package). 
Available implementations:

  org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp (default)
       Uses Java's built-in regular expression package

  org.apache.tools.ant.util.regexp.JakartaOroRegexp
       Requires  the jakarta-oro package

  org.apache.tools.ant.util.regexp.JakartaRegexpRegexp
       Requires the jakarta-regexp package

Usage:

  Call Syntax:

    <replaceregexp file="file"
                   match="pattern"
                   replace="pattern"
                   flags="options"?
                   byline="true|false"? >
      regexp?
      substitution?
      fileset*
    </replaceregexp>

   NOTE: You must have either the file attribute specified, or at least one fileset subelement
   to operation on.  You may not have the file attribute specified if you nest fileset elements
   inside this task.  Also, you cannot specify both match and a regular expression subelement at
   the same time, nor can you specify the replace attribute and the substitution subelement at
   the same time.

  Attributes:

    file    --> A single file to operation on (mutually exclusive
                   with the fileset subelements)
    match   --> The Regular expression to match
    replace --> The Expression replacement string
    flags   --> The options to give to the replacement
                g = Substitute all occurrences. default is to replace only the first one
                i = Case insensitive match

    byline  --> Should this file be processed a single line at a time (default is false)
                "true" indicates to perform replacement on a line by line basis
                "false" indicates to perform replacement on the whole file at once.

 Example:

    The following call could be used to replace an old property name in a ".properties"
    file with a new name.  In the replace attribute, you can refer to any part of the
    match expression in parenthesis using backslash followed by a number like '\1'.

    <replaceregexp file="test.properties"
                   match="MyProperty=(.*)"
                   replace="NewProperty=\1"
                   byline="true" />

Field Summary

Modifier and TypeField and Description
private boolean
byline

private String
encoding

Encoding to assume for the files

private File
file

private static final FileUtils
FILE_UTILS

private String
flags

private boolean
preserveLastModified

private RegularExpression
regex

private Union
resources

private Substitution
subs

Inherited from org.apache.tools.ant.Task:
targettaskNametaskTypewrapper

Constructor Summary

AccessConstructor and Description
public
ReplaceRegExp()

Default Constructor

Method Summary

Modifier and TypeMethod and Description
public void
addConfigured(ResourceCollection
ResourceCollection
rc)

Support arbitrary file system based resource collections.

public void
addFileset(FileSet
the fileset element
set)

list files to apply the replacement to

public RegularExpression

Returns:

the regular expression object to be configured as an element
createRegexp()

A regular expression.

public Substitution

Returns:

the substitution pattern object to be configured as an element
createSubstitution()

A substitution pattern.

protected String

Returns:

the replacement result
doReplace(RegularExpression
a regular expression
r, Substitution
a Substitution
s, String
the string to do the replacement on
input, int
The options for the regular expression
options)

Invoke a regular expression (r) on a string (input) using substitutions (s) for a matching regex.

protected void
doReplace(File
the file to perform the replacement on
f, int
the regular expressions options
options)

Perform the replacement on a file

public void
execute()

Overrides org.apache.tools.ant.Task.execute.

Execute the task
private boolean
multilineReplace(Reader r, Writer w, int options)

private boolean
replaceAndWrite(String s, Writer w, int options)

public void
setByLine(String
the byline attribute as a string
byline)

Deprecated since 1.6.x. Use setByLine(boolean).
Process the file(s) one line at a time, executing the replacement on one line at a time.
public void
setByLine(boolean
the byline attribute
byline)

Process the file(s) one line at a time, executing the replacement on one line at a time.

public void
setEncoding(String
the encoding attribute
encoding)

Specifies the encoding Ant expects the files to be in - defaults to the platforms default encoding.

public void
setFile(File
The file for which the reg exp should be replaced.
file)

file for which the regular expression should be replaced; required unless a nested fileset is supplied.

public void
setFlags(String
the flags attribute
flags)

The flags to use when matching the regular expression.

public void
setMatch(String
the match attribute.
match)

the regular expression pattern to match in the file(s); required if no nested <regexp> is used

public void
setPreserveLastModified(boolean
boolean
b)

Whether the file timestamp shall be preserved even if the file is modified.

public void
setReplace(String
the replace attribute
replace)

The substitution pattern to place in the file(s) in place of the regular expression.

Inherited from org.apache.tools.ant.Task:
bindToOwnergetOwningTargetgetRuntimeConfigurableWrappergetTaskNamegetTaskTypegetWrapperhandleErrorFlushhandleErrorOutputhandleFlushhandleInputhandleOutputinitisInvalidloglogloglogmaybeConfigureperformreconfiguresetOwningTargetsetRuntimeConfigurableWrappersetTaskNamesetTaskType

Field Detail

bylineback to summary
private boolean byline
encodingback to summary
private String encoding

Encoding to assume for the files

fileback to summary
private File file
FILE_UTILSback to summary
private static final FileUtils FILE_UTILS
flagsback to summary
private String flags
preserveLastModifiedback to summary
private boolean preserveLastModified
regexback to summary
private RegularExpression regex
resourcesback to summary
private Union resources
subsback to summary
private Substitution subs

Constructor Detail

ReplaceRegExpback to summary
public ReplaceRegExp()

Default Constructor

Method Detail

addConfiguredback to summary
public void addConfigured(ResourceCollection rc)

Support arbitrary file system based resource collections.

Parameters
rc:ResourceCollection

ResourceCollection

Since
Ant 1.8.0
addFilesetback to summary
public void addFileset(FileSet set)

list files to apply the replacement to

Parameters
set:FileSet

the fileset element

createRegexpback to summary
public RegularExpression createRegexp()

A regular expression. You can use this element to refer to a previously defined regular expression datatype instance

Returns:RegularExpression

the regular expression object to be configured as an element

createSubstitutionback to summary
public Substitution createSubstitution()

A substitution pattern. You can use this element to refer to a previously defined substitution pattern datatype instance.

Returns:Substitution

the substitution pattern object to be configured as an element

doReplaceback to summary
protected String doReplace(RegularExpression r, Substitution s, String input, int options)

Invoke a regular expression (r) on a string (input) using substitutions (s) for a matching regex.

Parameters
r:RegularExpression

a regular expression

s:Substitution

a Substitution

input:String

the string to do the replacement on

options:int

The options for the regular expression

Returns:String

the replacement result

doReplaceback to summary
protected void doReplace(File f, int options) throws IOException

Perform the replacement on a file

Parameters
f:File

the file to perform the replacement on

options:int

the regular expressions options

Exceptions
IOException:
if an error occurs
executeback to summary
public void execute() throws BuildException

Overrides org.apache.tools.ant.Task.execute.

Execute the task

Annotations
@Override
Exceptions
BuildException:
is there is a problem in the task execution.
multilineReplaceback to summary
private boolean multilineReplace(Reader r, Writer w, int options) throws IOException
replaceAndWriteback to summary
private boolean replaceAndWrite(String s, Writer w, int options) throws IOException
setByLineback to summary
public void setByLine(String byline)

Deprecated

since 1.6.x. Use setByLine(boolean).

Process the file(s) one line at a time, executing the replacement on one line at a time. This is useful if you want to only replace the first occurrence of a regular expression on each line, which is not easy to do when processing the file as a whole. Defaults to false.

Parameters
byline:String

the byline attribute as a string

Annotations
@Deprecated
setByLineback to summary
public void setByLine(boolean byline)

Process the file(s) one line at a time, executing the replacement on one line at a time. This is useful if you want to only replace the first occurrence of a regular expression on each line, which is not easy to do when processing the file as a whole. Defaults to false.

Parameters
byline:boolean

the byline attribute

setEncodingback to summary
public void setEncoding(String encoding)

Specifies the encoding Ant expects the files to be in - defaults to the platforms default encoding.

Parameters
encoding:String

the encoding attribute

Since
Ant 1.6
setFileback to summary
public void setFile(File file)

file for which the regular expression should be replaced; required unless a nested fileset is supplied.

Parameters
file:File

The file for which the reg exp should be replaced.

setFlagsback to summary
public void setFlags(String flags)

The flags to use when matching the regular expression. For more information, consult the Perl5 syntax.

  • g : Global replacement. Replace all occurrences found
  • i : Case Insensitive. Do not consider case in the match
  • 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.
  • 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.
Parameters
flags:String

the flags attribute

setMatchback to summary
public void setMatch(String match)

the regular expression pattern to match in the file(s); required if no nested <regexp> is used

Parameters
match:String

the match attribute.

setPreserveLastModifiedback to summary
public void setPreserveLastModified(boolean b)

Whether the file timestamp shall be preserved even if the file is modified.

Parameters
b:boolean

boolean

Since
Ant 1.8.0
setReplaceback to summary
public void setReplace(String replace)

The substitution pattern to place in the file(s) in place of the regular expression. Required if no nested <substitution> is used

Parameters
replace:String

the replace attribute