This appendix contains a reference of the system data types contained in Phing.
FileLists offer a way to represent a specific list of files. Unlike FileSets, FileLists may contain files that do not exist on the filesystem. Also, FileLists can represent files in a specific order -- whereas FileSets represent files in whichever order they are returned by the filesystem.
<filelist dir="/etc" files="httpd/conf/httpd.conf,php.ini"/>
Or you can use a listfile, which is expected to contain one filename per line:
<filelist dir="conf/" listfile="ini_files.txt"/>
This will grab each file as listed in ini_files.txt. This can be useful if one task compiles a list of files to process and another task needs to read in that list and perform some action to those files.
Name | Type | Description | Default | Required |
---|---|---|---|---|
dir | String | The directory, to which the paths given in files or listfile are relative. | n/a | Yes |
files | String | Comma or space-separated list of files. | n/a | Yes (or listfile) |
listfile | String | A text file with one filename per line. | n/a | Yes (or files) |
Filesets offer a easy and straigtforward way to include files. You can include/exclude files in/from a fileset using the <include>/<exclude> tags. In patterns, one asterisk (*) maps to a part of a file/directory name within a directory level. Two asterisks (**) may include above the "border" of the directory separator.
<fileset dir="/etc" > <include name="httpd/**" /> <include name="php.ini" /> </fileset>
This will include the apache configuration and PHP configuration file from /etc.
Name | Type | Description | Default | Required |
---|---|---|---|---|
dir | String | The directory, the paths given in include/exclude are relative to. | n/a | Yes |
The only tags that are supported by Fileset are the <include> and the <exclude> tags. These tags must have a name attribute that contains the pattern to include/exclude.
The Path data type can be used to respresent path structures. In many cases the path type will be used for nested <classpath> tags. E.g.
<path id="project.class.path"> <pathelement dir="lib/"/> <pathelement dir="ext/"/> </path> <target name="blah"> <taskdef name="mytask" path="myapp.phing.tasks.MyTask"> <classpath refid="project.class.path"/> </taskdef>
</target>
Name | Type | Description | Default | Required |
---|---|---|---|---|
dir | String | Specific path to directory | n/a | No |
path | String | A path (which contains multiple locations separated by path.separator) to add. | n/a | No |
The <path> tag supports nested <fileset> and <dirset> tags.
Filters have to be defined within a <filterchain> context to work. Example:
<filterchain> <expandproperties /> </filterchain>
There are two ways to use a filter: System filters (the ones shipped with Phing) can be used with their own tag name, such as <xsltfilter>, <expandpropertyfilter> or <tabtospaces>. Another way is to use the <filterreader> tag.
The PhingFilterReader is used when you want to use filters that are not directly available through their own tag. Example:
<filterchain> <filterreader classname="phing.filter.ReplaceTokens"> <-- other way to set attributes --> <param name="begintoken" value="@@" /> <param name="endtoken" value="@@" /> <-- other way to set nested tags --> <param type="token" key="bar" value="foo" /> </filterreader> </filterchain>
In the filterreader tag you have to specify the path the class is in. The FilterReader will then load this class and pass the parameters to the loaded filter. There are two types of parameters: First, you can pass "normal" parameters to the loaded filter. That means, you can pass parameters as if they were attributes. If you want to do this, you only specify the name and value attributes in the param tag. You can also pass nested elements to the filter. Then, you have to specify the type attribute. This attribute specifies the name of the nested tag.
The result of the example above is identical with the following code:
<filterchain> <replacetokens begintoken="@@" endtoken="@@"> <token key="bar" value="foo" /> </replacetokens> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
classname | String | Name of class to use (in dot-path notation). | n/a | Yes |
classpath | String | The classpath to use when including classes. This is added to PHP's include_path. | n/a | No |
classpathref | String | Reference to classpath to use when including classes. This is added to PHP's include_path. | n/a | No |
The PhingFilterReader supports nested <classpath>.
In order to support the <filterreader ... /> sytax, your class must extend the BaseParamFilterReader class. Most of the filters that are bundled with Phing can be invoked using this syntax. The noteable exception (at time of writing) is the ReplaceRegexp filter, which expects find/replace parameters that do not fit the name/value mold. For this reason, you must always use the shorthand <replaceregexp .../> to invoke this filter.
The ExpandProperties simply replaces property names with their property values. For example, if you have the following in your build file:
<property name="description.txt" value="This is a text file" /> <copy todir="/tmp"> <filterchain> <expandproperties /> </filterchain> <fileset dir="."> <include name="**" /> </fileset> </copy>
And the string ${description.txt} it will be replaced by This is a text file.
This filter reads the first n lines of a file; the others are not further passed through the filter chain. Usage example:
<filterchain> <headfilter lines="20" /> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
lines | Integer | Number of lines to read. | 10 | No |
This filter is only "permeable" for lines that contain the expression given as parameter. For example, the following filterchain would only let all the lines pass that contain class:
<filterchain> <linecontains> <contains value="class" /> </linecontains> </filterchain>
The linecontains tag must contain one or more contains tags. Latter must have a value attribute that has to be set to the string the line has to contain to be let through.
This filter is similar to LineContains but you can specify regular expressions instead of simple strings.
<filterchain> <linecontainsregexp> <regexp pattern="foo(.*)bar" /> </linecontainsregexp> </filterchain>
The LineContains filter has to contain at least one regexp tag. This must have a pattern attribute that is set to a regular expression.
This filter adds a prefix to every line. The following example will add the string foo: in front of every line.
<filterchain> <prefixlines prefix="foo: " /> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
prefix | string | Strint to prepend to every line. | n/a | Yes |
The ReplaceTokens filter will replace certain tokens. Tokens are strings enclosed in special characters. If you want to replace ##BCHOME## by the path to the directory set in the environment variable BCHOME, you could do the following:
<property environment="env" /> <filterchain> <replacetokens begintoken="##" endtoken="##"> <token key="BCHOME" value="${env.BCHOME}" /> </replacetokens> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
begintoken | string | The string that marks the beginning of a token. | @ | No |
endtoken | string | The string that marks the end of a token. | @ | No |
The ReplaceTokens filter must contain one or more token tags. These must have a key and a value attribute.
The ReplaceRegexp filter will perform a regexp find/replace on the input stream. For example, if you want to replace ANT with Phing (ignoring case) and you want to replace references to *.java with *.php:
<filterchain> <replaceregexp> <regexp pattern="ANT" replace="Phing" ignoreCase="true"/> <regexp pattern="(\w+)\.java" replace="\1.php"/> </replaceregexp> </filterchain>
The ReplaceTokens filter must contain one or more regexp tags. These must have pattern and replace attributes -- and optionally the ignoreCase attribute.
The StripLineBreaks filter removes all linebreaks from the stream passed through the filter chain.
<filterchain> <striplinebreaks /> </filterchain>
The StripLineComments filter removes all line comments from the stream passed through the filter chain:
<filterchain> <striplinecomments> <comment value="#" /> <comment value="--" /> <comment value="//" /> </striplinecomments> </filterchain>
The striplinecomments tag must contain one or more comment tags. These must have a value attribute that specifies the character(s) that start a line comment.
The StripPhpComment filter removes all PHP comments from the stream passed through the filter.
<filterchain> <stripphpcomments /> </filterchain>
The TabToSpaces filter replaces all tab characters with a given count of space characters.
<filterchain> <tabtospaces tablength="8" /> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
tablength | Integer | The number of space characters that a tab is to represent. | 8 | No |
Similar to HeadFilter, this filter reads the last n lines of a file; the others are not further passed through the filter chain. Usage example:
<filterchain> <tailfilter lines="20" /> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
lines | Integer | Number of lines from the back to read. | 10 | No |
The XsltFilter applies a XSL template to the stream. Though you can use this filter directly, you should use XsltTask which is shortcut to the following lines:
<filterchain> <xsltfilter style="somexslt.xsl" /> </filterchain>
Name | Type | Description | Default | Required |
---|---|---|---|---|
style | String | The XSLT stylesheet to use for transformation. | n/a | Yes |
html | Boolean | Whether to parse the input as HTML (using libxml2 DOMDocument::loadHTML()). | false | No |
The XsltFilter filter may contain one or more param tags to pass any XSLT parameters to the stylesheet. These param tags must have name and expression attributes.
While filters are applied to the content of files, Mappers are applied to the filenames. All mappers have the same API, i.e. the way you use them is the same:
<mapper type="mappername" from="frompattern" to="topattern" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
type | String | Type of the mapper. | n/a | Yes |
from | String | The pattern the filename is to be matched to. The exact meaning is dependent on the implementation of the mapper. | n/a | depends on the implementation of the mapper |
to | String | The pattern according to which the filename is to be changed to. Here, the usage is dependent on the implementation of the mapper, too. | n/a | depends on the implementation of the mapper |
The FlattenMapper removes the directories from a filename and solely returns the filename.
<copy todir="/tmp"> <mapper type="flatten" /> <fileset refid="someid" /> </copy>
This code will copy all files in the fileset to /tmp. All files will be in the target directory.
<mapper type="flatten" />
Applying the mapper, you will get the following results from the following filenames:
From | To |
---|---|
test.txt | test.txt |
./foo/bar/test.bak | test.bak |
The GlobMapper works like the copy command in DOS:
<copy todir="/tmp"> <mapper type="glob" from="*.php" to="*.php.bak"/> <fileset refid="someid" /> </copy>
This will change the extension of all files matching the pattern *.php to .php.bak.
<mapper type="glob" from="*txt" to="*txt.bak"/>
Applying the mapper, you will get the following results from the following filenames:
From | To |
---|---|
test.txt | test.txt.bak |
./foo/bar/test.txt | ./foo/bar/test.txt.bak |
mytxt | mytxt.bak |
SomeClass.php | ignored, SomeClass.php |
The IdentityMapper will not change anything on the source filenames.
The MergeMapper changes all source filenames to the same filename.
<mapper type="merge" to="test.tar"/>
Applying the mapper, you will get the following results from the following filenames:
From | To |
---|---|
test.txt | test.tar |
./foo/bar/test.txt | test.tar |
mytxt | test.tar |
SomeClass.php | test.tar |
The RegexpMapper changes filenames according to a pattern defined by a regular expression. This is the most powerful mapper and you should be able to use it for every possible application.
<mapper type="regexp" from="^(.*)\.conf\.xml" to="\1.php"/>
The mapper as above will do the following mappings:
From | To |
---|---|
test.txt | ignore, test.txt |
./foo/bar/test.conf.xml | ./foo/bar/test.php |
someconf.conf.xml | someconf.php |