youys
/
ant

<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 &quot;no&quot;.
	  </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 &quot;yes&quot;.
	  </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>

      </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
        if 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>
  &lt;concat destfile=&quot;README&quot;&gt;Hello, World!&lt;/concat&gt;
      </pre>

      <p><b>Concatenate a series of files to the console:</b></p>

      <pre>
  &lt;concat&gt;
    &lt;fileset dir=&quot;messages&quot; includes=&quot;*important*&quot;/&gt;
  &lt;/concat&gt;
      </pre>

      <p><b>Concatenate a single file, appending if the destination file exists:</b></p>

      <pre>
  &lt;concat destfile=&quot;NOTES&quot; append=&quot;true&quot;&gt;
    &lt;filelist dir=&quot;notes&quot; files=&quot;note.txt&quot;/&gt;
  &lt;/concat&gt;
      </pre>

      <p><b>Concatenate a series of files, update the destination
      file only if is older that all the source files:</b></p>

      <pre>
  &lt;concat destfile=&quot;${docbook.dir}/all-sections.xml&quot;
          force=&quot;no&quot;&gt;
    &lt;filelist dir=&quot;${docbook.dir}/sections&quot; 
         files=&quot;introduction.xml,overview.xml&quot;/&gt;
    &lt;fileset dir=&quot;${docbook.dir}&quot; 
         includes=&quot;sections/*.xml&quot; 
         excludes=&quot;introduction.xml,overview.xml&quot;/&gt;
  &lt;/concat&gt;
      </pre>

      <p><b>Concatenate a series of files, expanding ant properties</b></p>
        <pre>
   &lt;concat destfile="${build.dir}/subs"&gt;
      &lt;path&gt;
        &lt;fileset dir="${src.dir}" includes="*.xml"/&gt;
        &lt;pathelement location="build.xml"/&gt;
      &lt;/path&gt;
      &lt;filterchain&gt;
        &lt;expandproperties/&gt;
      &lt;/filterchain&gt;
   &lt;/concat&gt;
        </pre>

      <p><b>Filter the lines containing project from build.xml and output
           them to report.output, prepending with a header</b></p>
        <pre>
   &lt;concat destfile="${build.dir}/report.output"&gt;
      &lt;header filtering="no" trimleading="yes"&gt;
          Lines that contain project
          ==========================
      &lt;/header&gt;
      &lt;path path="build.xml"/&gt;
      &lt;filterchain&gt;
         &lt;linecontains&gt;
           &lt;contains value="project"/&gt;
         &lt;/linecontains&gt;
      &lt;/filterchain&gt;
   &lt;/concat&gt;
        </pre>

      <hr>

      <p align="center">
	Copyright &copy; 2002-2003 Apache Software Foundation. All
	Rights Reserved.
      </p>

    </body>

  </html>