2
Licensed to the Apache Software Foundation (ASF) under one or more
3
contributor license agreements. See the NOTICE file distributed with
4
this work for additional information regarding copyright ownership.
5
The ASF licenses this file to You under the Apache License, Version 2.0
6
(the "License"); you may not use this file except in compliance with
7
the License. You may obtain a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS,
13
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
See the License for the specific language governing permissions and
15
limitations under the License.
20
<meta http-equiv="Content-Language" content="en-us">
21
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
27
<h2><a name="Concat">Concat</a></h2>
32
Concatenates one or more
33
<a href="../Types/resources.html">resource</a>s
34
to a single file or to the console. The destination
35
file will be created if it does not exist unless the resource
36
list is empty and ignoreempty is true.
39
<p><strong>Since Apache Ant 1.7.1</strong>, this task can be used as a
40
<a href="../Types/resources.html#collection">Resource Collection</a>
41
that will return exactly one
42
<a href="../Types/resources.html">resource</a>.
46
<a href="../Types/resources.html#collection">
47
Resource Collection</a>s are used to
48
select which resources are to be concatenated. There is no
49
singular attribute to specify a single resource to cat.
54
<table border="1" cellpadding="2" cellspacing="0">
57
<td valign="top"><b>Attribute</b></td>
58
<td valign="top"><b>Description</b></td>
59
<td align="center" valign="top"><b>Required</b></td>
63
<td valign="top">destfile</td>
65
The destination file for the concatenated stream.
66
If not specified the console will be used instead.
68
<td valign="top" align="center">
74
<td valign="top">append</td>
76
Specifies whether or not the file specified by 'destfile'
77
should be appended. Defaults to "no".
79
<td valign="top" align="center">No</td>
82
<td valign="top">force</td>
84
Specifies whether or not the file specified by 'destfile'
85
should be written to even if it is newer than all source files.
86
<strong>deprecated, use the overwrite attribute instead</strong>
87
Defaults to "yes".
89
<td valign="top" align="center">No</td>
92
<td valign="top">overwrite</td>
94
Specifies whether or not the file specified by 'destfile'
95
should be written to even if it is newer than all source files.
96
<em>since Ant 1.8.2</em>.
97
Defaults to "yes".
99
<td valign="top" align="center">No</td>
103
<td valign="top">forceReadOnly</td>
104
<td valign="top">Overwrite read-only destination
105
files. <em>since Ant 1.8.2</em></td>
106
<td valign="top" align="center">No; defaults to false.</td>
110
<td valign="top">encoding</td>
112
Specifies the encoding for the input files. Please see <a
113
href="http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">
114
http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html</a>
115
for a list of possible values. Defaults to the platform's
116
default character encoding.
118
<td valign="top" align="center">No</td>
121
<td valign="top">outputencoding</td>
123
The encoding to use when writing the output file
124
<em>since Ant 1.6</em>.
125
Defaults to the value of the encoding attribute
126
if given or the default JVM encoding otherwise.
128
<td valign="top" align="center">No</td>
131
<td valign="top">fixlastline</td>
133
Specifies whether or not to check if
134
each file concatenated is terminated by
135
a new line. If this attribute is "yes"
136
a new line will be appended to the stream if
137
the file did not end in a new line.
138
<em>since Ant 1.6</em>.
139
Defaults to "no".
140
This attribute does not apply to embedded text.
142
<td valign="top" align="center">No</td>
145
<td valign="top">eol</td>
147
Specifies what the end of line character are
148
for use by the fixlastline attribute.
149
<em>since Ant 1.6</em>
150
Valid values for this property are:
152
<li>cr: a single CR</li>
153
<li>lf: a single LF</li>
154
<li>crlf: the pair CRLF</li>
155
<li>mac: a single CR</li>
156
<li>unix: a single LF</li>
157
<li>dos: the pair CRLF</li>
159
The default is platform dependent.
160
For Unix platforms, the default is "lf".
161
For DOS based systems (including Windows),
162
the default is "crlf".
163
For Mac OS, the default is "cr".
165
<td valign="top" align="center">No</td>
168
<td valign="top">binary</td>
170
<em>since Ant 1.6.2</em>
171
If this attribute is set to true, the task concatenates the files
172
in a byte by byte fashion. If this attribute is false, concat will
173
not normally work for binary files due to character encoding
175
If this option is set to true, the destfile attribute must be
176
set, and the task cannot used nested text.
177
Also the attributes encoding, outputencoding, filelastline
179
The default is "false".
181
<td valign="top" align="center">No</td>
184
<td valign="top">ignoreempty</td>
186
<em>Since Ant 1.8.0</em>
187
Specifies whether or not the file specified by 'destfile'
188
should be created if the source resource list is
189
empty. Defaults to "true".
191
<td valign="top" align="center">No</td>
196
<h3>Parameters specified as nested elements</h3>
197
<h4>Resource Collection</h4>
198
<p><em>since Ant 1.7</em>.</p>
201
Any of the various <a href="../Types/resources.html#collection">
202
Resource Collection</a> types can specify the resources to be
207
<p><em>since Ant 1.6</em>.</p>
208
<p>The concat task supports nested
209
<a href="../Types/filterchain.html"> FilterChain</a>s.</p>
211
<h4>header, footer</h4>
212
<p><em>since Ant 1.6</em>.</p>
213
<p>Used to prepend or postpend text into the concatenated stream.</p>
214
<p>The text may be in-line or be in a file.</p>
215
<table border="1" cellpadding="2" cellspacing="0">
217
<td valign="top"><b>Attribute</b></td>
218
<td valign="top"><b>Description</b></td>
219
<td align="center" valign="top"><b>Required</b></td>
222
<td valign="top">filtering</td>
224
Whether to filter the text provided by this sub element,
226
<td valign="top" align = "center">No</td>
229
<td valign="top">file</td>
230
<td valign="top">A file to place at the head or tail of the
232
<td valign="top" align = "center">No</td>
235
<td valign="top">trim</td>
236
<td valign="top">Whether to trim the value, default is "no"</td>
237
<td valign="top" align = "center">No</td>
240
<td valign="top">trimleading</td>
242
Whether to trim leading white space on each line, default is "no"
244
<td valign="top" align = "center">No</td>
250
<p><b>Concatenate a string to a file:</b></p>
253
<concat destfile="README">Hello, World!</concat>
256
<p><b>Concatenate a series of files to the console:</b></p>
260
<fileset dir="messages" includes="*important*"/>
264
<p><b>Concatenate a single file, appending if the destination file exists:</b></p>
267
<concat destfile="NOTES" append="true">
268
<filelist dir="notes" files="note.txt"/>
272
<p><b>Concatenate a series of files, update the destination
273
file only if is older that all the source files:</b></p>
276
<concat destfile="${docbook.dir}/all-sections.xml"
277
force="no">
278
<filelist dir="${docbook.dir}/sections"
279
files="introduction.xml,overview.xml"/>
280
<fileset dir="${docbook.dir}"
281
includes="sections/*.xml"
282
excludes="introduction.xml,overview.xml"/>
286
<p><b>Concatenate a series of files, expanding ant properties</b></p>
288
<concat destfile="${build.dir}/subs">
290
<fileset dir="${src.dir}" includes="*.xml"/>
291
<pathelement location="build.xml"/>
294
<expandproperties/>
299
<p><b>Filter the lines containing project from build.xml and output
300
them to report.output, prepending with a header</b></p>
302
<concat destfile="${build.dir}/report.output">
303
<header filtering="no" trimleading="yes">
304
Lines that contain project
305
==========================
307
<path path="build.xml"/>
310
<contains value="project"/>
311
</linecontains>
316
<p><b>Concatenate a number of binary files.</b></p>
318
<concat destfile="${build.dir}/dist.bin" binary="yes">
319
<fileset file="${src.dir}/scripts/dist.sh" />
320
<fileset file="${build.dir}/dist.tar.bz2" />
added
removed
docs/manual/Tasks/concat.html
