| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Concat</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="Concat">Concat</a></h2> |
| |
| <h3>Description</h3> |
| |
| <p> |
| Concatenates one or more |
| <a href="../Types/resources.html">resource</a>s |
| to a single file or to the console. The destination |
| file will be created if it does not exist unless the resource |
| list is empty and ignoreempty is true. |
| </p> |
| |
| <p><strong>Since Apache Ant 1.7.1</strong>, this task can be used as a |
| <a href="../Types/resources.html#collection">Resource Collection</a> |
| that will return exactly one |
| <a href="../Types/resources.html">resource</a>. |
| </p> |
| |
| <p> |
| <a href="../Types/resources.html#collection"> |
| Resource Collection</a>s are used to |
| select which resources are to be concatenated. There is no |
| singular attribute to specify a single resource 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. |
| <strong>deprecated, use the overwrite attribute instead</strong> |
| Defaults to "yes". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">overwrite</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.8.2</em>. |
| Defaults to "yes". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">forceReadOnly</td> |
| <td valign="top">Overwrite read-only destination |
| files. <em>since Ant 1.8.2</em></td> |
| <td valign="top" align="center">No; defaults to false.</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">encoding</td> |
| <td valign="top"> |
| Specifies the encoding for the input files. Please see <a |
| href="http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html"> |
| Supported Encodings</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> |
| <tr> |
| <td valign="top">binary</td> |
| <td valign="top"> |
| <em>since Ant 1.6.2</em> |
| If this attribute is set to true, the task concatenates the files |
| in a byte by byte fashion. If this attribute is false, concat will |
| not normally work for binary files due to character encoding |
| issues. |
| If this option is set to true, the destfile attribute must be |
| set, and the task cannot used nested text. |
| Also the attributes encoding, outputencoding, filelastline |
| cannot be used. |
| The default is "false". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">ignoreempty</td> |
| <td valign="top"> |
| <em>Since Ant 1.8.0</em> |
| Specifies whether or not the file specified by 'destfile' |
| should be created if the source resource list is |
| empty. Defaults to "true". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">resourcename</td> |
| <td valign="top"> |
| <em>Since Ant 1.8.3</em> |
| Specifies the name reported if this task is exposed |
| as a <a href="../Types/resources.html">resource</a>. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| <h4>Resource Collection</h4> |
| <p><em>since Ant 1.7</em>.</p> |
| |
| <p> |
| Any of the various <a href="../Types/resources.html#collection"> |
| Resource Collection</a> types can specify the resources to be |
| concatenated. |
| </p> |
| |
| <h4>filterchain</h4> |
| <p><em>since Ant 1.6</em>.</p> |
| <p>The concat task supports nested |
| <a href="../Types/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> |
| |
| <p><b>Concatenate a number of binary files.</b></p> |
| <pre> |
| <concat destfile="${build.dir}/dist.bin" binary="yes"> |
| <fileset file="${src.dir}/scripts/dist.sh" /> |
| <fileset file="${build.dir}/dist.tar.bz2" /> |
| </concat> |
| </pre> |
| |
| |
| |
| </body> |
| |
| </html> |
