5.7 Basic Types
Prev | Chapter 5 Project components | Next

## 5.7 Basic Types

The following section gives you a quick introduction into the basic Phing types. For a complete reference see Appendix D, Core Types.

### 5.7.1 `FileSet`

FileSets are groups of files. You can include or exclude specific files and patterns to/from a FileSet. The use of patterns is explained below. For a start, look at the following example:

    <fileset dir="/tmp" id="fileset1">
      <include name="sometemp/file.txt" />
      <include name="othertemp/**" />
      <exclude name="othertemp/file.txt" />
    </fileset>

    <fileset dir="/home" id="fileset2">
      <include name="foo/**" />
      <include name="bar/**/*.php" />
      <exclude name="foo/tmp/**" />
    </fileset>

The use of patterns is quite straightforward: If you simply want to match a part of a filename or dirname, you use *. If you want to include multiple directories and/or files, you use **. This way, filesets provide an easy but powerful way to include files.

### 5.7.2 `FileList`

FileLists, like FileSets, are collections of files; however, a FileList is an explicitly defined list of files -- and the files don't necessarily have to exist on the filesystem.

Besides being able to refer to nonexistent files, another thing that `FileLists` allow you to do is specify files `in a certain order`. Files in `FileSets` are ordered based on the OS-level directory listing functions, in some cases you may want to specify a list of files to be processed in a certain order -- e.g. when concatenating files using the `<append>` task.

    <filelist dir="base/" files="file1.txt,file2.txt,file3.txt"/>

    <!-- OR: -->
    <filelist dir="basedir/" listfile="files_to_process.txt"/>

### 5.7.3 `FilterChains` and Filters

`FilterChains` can be compared to Unix pipes. Unix pipes add a great deal of flexibility to command line operations; for example, if you wanted to copy just those lines that contained the string `blee` from the first 10 lines of a file called `foo` to a file called `bar`, you could do:

    cat foo | head -n10 | grep blee > bar

Something like this is not possible with the tasks and types that we have learned about thus far, and this is where the incredible usefulness of `FilterChains` becomes apparent. They emulate Unix pipes and provide a powerful dimension of file/stream manipulation for the tasks that support them.

`FilterChain` usage is quite straightforward: you pass the complex Phing type `filterchain` to a task that supports FilterChains and add individual filters to the FilterChain. In the course of executing the task, the filters are applied (in the order in which they appear in the XML) to the contents of the files that are being manipulated by your task.

    <filterchain>
      <replacetokens>
        <token key="BC_PATH" value="${top.builddir}/"/>
        <token key="BC_PATH_USER" value="${top.builddir}/testsite/user/${lang}/"/>
      </replacetokens>

      <filterreader classname="phing.filters.TailFilter">
        <param name="lines" value="10"/>
      </filterreader>
    </filterchain>

The code listing above shows you some example of how to use filter chains. For a complete reference see Appendix D, Core Types. This filter chain would replace all occurrences of `BC_PATH` and `BC_PATH_USER` with the values assigned to them in lines 4 and 5. Additionally, it will only return the last 10 lines of the files.

Notice above that `FilterChain` filters have a "shorthand" notation and a long, generic notation. Most filters can be described using both of these forms:

    <replacetokens>
      <token key="BC_PATH" value="${top.builddir}/"/>
      <token key="BC_PATH_USER" value="${top.builddir}/testsite/user/${lang}/"/>
    </replacetokens>

    <!-- OR: -->

    <filterreader classname="phing.filters.ReplaceTokens">
      <param type="token" name="BC_PATH" value="${top.builddir}/"/>
      <param type="token" name="BC_PATH" value="${top.builddir}/testsite/user/${lang}/"/>
    </filterreader>

As the pipe concept in Unix, the filter concept is quite complex but powerful. To get a better understanding of different filters and how they can be used, take a look at any of the many uses of FilterChains in the build files for the binarycloud Bibliography project.

### 5.7.4 File Mappers

With `FilterChains` and filters provide a powerful tool for changing contents of files, `mappers` provide a powerful tool for changing the names of files.

To use a Mapper, you must specify a pattern to match on and a replacement pattern that describes how the matched pattern should be transformed. The simplest form is basically no different from the DOS `copy` command:

    copy *.bat *.txt

In Phing this is the `glob` Mapper:

    <mapper type="glob" from="*.bat" to="*.txt"/>

Phing also provides support for more complex mapping using regular expressions:

    <mapper type="regexp" from="^(.*)\.conf\.xml$$" to="\1.php"/>

Consider the example below to see how Mappers can be used in a build file. This example includes some of the other concepts introduced in this chapter, such as `FilterChains` and `FileSets`. If you don't understand everything, don't worry. The important point is that Mappers are types too, which can be used in tasks that support them.

    <copy>
      <fileset dir=".">
        <include name="*.ent.xml"/>
      </fileset>

      <mapper type="regexp" from="^(.*)\.ent\.xml$" to="\1.php"/>

      <filterchain>
        <filterreader classname="phing.filters.XsltFilter">
          <param name="style" value="ent2php.xsl"/>
        </filterreader>
      </filterchain>
    </copy>

For a complete reference, see Appendix D, Core Types

Prev | Up | Next
5.6 Types | Home | 5.8 Conditions