<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Concat</title>
</head>
<body>
<h2><a name="Concat">Concat</a></h2>
<h3>Description</h3>
<p>
Concatenates a file, or a series of files, to a single file or
the console. The destination file will be created if it does
not exist.
</p>
<p>
<a href="../CoreTypes/path.html">Path</a>s and/or
<a href="../CoreTypes/fileset.html">FileSet</a>s and/or <a
href="../CoreTypes/filelist.html">FileList</a>s are used to
select which files are to be concatenated. There is no
singular 'file' attribute to specify a single file to cat.
</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">destfile</td>
<td valign="top">
The destination file for the concatenated stream.
If not specified the console will be used instead.
</td>
<td valign="top" align="center">
No
</td>
</tr>
<tr>
<td valign="top">append</td>
<td valign="top">
Specifies whether or not the file specified by 'destfile'
should be appended. Defaults to "no".
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">force</td>
<td valign="top">
Specifies whether or not the file specified by 'destfile'
should be written to even if it is newer than all source files.
<em>since Ant 1.6</em>.
Defaults to "yes".
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">
Specifies the encoding for the input files. Please see <a
href="http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html">
http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html</a>
for a list of possible values. Defaults to the platform's
default character encoding.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">outputencoding</td>
<td valign="top">
The encoding to use when writing the output file
<em>since Ant 1.6</em>.
Defaults to the value of the encoding attribute
if given or the default JVM encoding otherwise.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">fixlastline</td>
<td valign="top">
Specifies whether or not to check if
each file concatenated is terminated by
a new line. If this attribute is "yes"
a new line will be appended to the stream if
the file did not end in a new line.
<em>since Ant 1.6</em>.
Defaults to "no".
This attribute does not apply to embedded text.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">eol</td>
<td valign="top">
Specifies what the end of line character are
for use by the fixlastline attribute.
<em>since Ant 1.6</em>
Valid values for this property are:
<ul>
<li>cr: a single CR</li>
<li>lf: a single LF</li>
<li>crlf: the pair CRLF</li>
<li>mac: a single CR</li>
<li>unix: a single LF</li>
<li>dos: the pair CRLF</li>
</ul>
The default is platform dependent.
For Unix platforms, the default is "lf".
For DOS based systems (including Windows),
the default is "crlf".
For Mac OS, the default is "cr".
</td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>path</h4>
<p><em>since Ant 1.6</em>.</p>
<p>
This is a <a href="../CoreTypes/path.html">Path</a>. This is
used to select file files to be concatenated. Note that
a file can only appear once in a path. If this is
an issue consider using multiple paths.
</p>
<h4>fileset</h4>
<p>
<a href="../CoreTypes/fileset.html">FileSet</a>s are used to
select files to be concatenated. Note that the order in which
the files selected from a fileset are concatenated is
<i>not</i> guaranteed. If this is an issue, use multiple
filesets or consider using filelists.
</p>
<h4>filelist</h4>
<p>
<a href="../CoreTypes/filelist.html">FileList</a>s are used to
select files to be concatenated. The file ordering in the
<var>files</var> attribute will be the same order in which the
files are concatenated.
</p>
<h4>filterchain</h4>
<p><em>since Ant 1.6</em>.</p>
<p>The concat task supports nested
<a href="../CoreTypes/filterchain.html"> FilterChain</a>s.</p>
<h4>header,footer</h4>
<p><em>since Ant 1.6</em>.</p>
<p>Used to prepend or postpend text into the concatenated stream.</p>
<p>The text may be in-line or be in a file.</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">filtering</td>
<td valign="top">
Whether to filter the text provided by this sub element,
default is "yes".
<td valign="top" align = "center">No</td>
</tr>
<tr>
<td valign="top">file</td>
<td valign="top">A file to place at the head or tail of the
concatenated text.
<td valign="top" align = "center">No</td>
</tr>
<tr>
<td valign="top">trim</td>
<td valign="top">Whether to trim the value, default is "no"</td>
<td valign="top" align = "center">No</td>
</tr>
<tr>
<td valign="top">trimleading</td>
<td valign="top">
Whether to trim leading white space on each line, default is "no"
</td>
<td valign="top" align = "center">No</td>
</tr>
</table>
<h3>Examples</h3>
<p><b>Concatenate a string to a file:</b></p>
<pre>
<concat destfile="README">Hello, World!</concat>
</pre>
<p><b>Concatenate a series of files to the console:</b></p>
<pre>
<concat>
<fileset dir="messages" includes="*important*"/>
</concat>
</pre>
<p><b>Concatenate a single file, appending if the destination file exists:</b></p>
<pre>
<concat destfile="NOTES" append="true">
<filelist dir="notes" files="note.txt"/>
</concat>
</pre>
<p><b>Concatenate a series of files, update the destination
file only if is older that all the source files:</b></p>
<pre>
<concat destfile="${docbook.dir}/all-sections.xml"
force="no">
<filelist dir="${docbook.dir}/sections"
files="introduction.xml,overview.xml"/>
<fileset dir="${docbook.dir}"
includes="sections/*.xml"
excludes="introduction.xml,overview.xml"/>
</concat>
</pre>
<p><b>Concatenate a series of files, expanding ant properties</b></p>
<pre>
<concat destfile="${build.dir}/subs">
<path>
<fileset dir="${src.dir}" includes="*.xml"/>
<pathelement location="build.xml"/>
</path>
<filterchain>
<expandproperties/>
</filterchain>
</concat>
</pre>
<p><b>Filter the lines containing project from build.xml and output
them to report.output, prepending with a header</b></p>
<pre>
<concat destfile="${build.dir}/report.output">
<header filtering="no" trimleading="yes">
Lines that contain project
==========================
</header>
<path path="build.xml"/>
<filterchain>
<linecontains>
<contains value="project"/>
</linecontains>
</filterchain>
</concat>
</pre>
<hr>
<p align="center">
Copyright © 2002-2003 Apache Software Foundation. All
Rights Reserved.
</p>
</body>
</html>