Appendix D-4: Selectors

Selectors are a specific subset of Phing data types that allow you to fine-tune matching in a FileSet (or DirSet).

Phing supports the following core selectors, which typically match on both files and directories in a <fileset>:

Additionally, to create more complex selections, a variety of selectors that contain other selectors are available for your use. They combine the selections of their child selectors in various ways.

Phing supports the following selector containers:

Contains

The <contains> tag selects files that contain the string specified by the text attribute.

<fileset dir="${src}" includes="**/*.php">
  <contains text="PHP"/>
</fileset>

Attributes

Attributes for the <contains> selector
Name Description Default Required
text Specifies the text that every file must contain n/a Yes
casesensitive Whether to pay attention to case when looking for the string in the text attribute. true No

Date

The <date> tag selects files whose last modified date meet the date limits specified by the selector.

<fileset dir="${src}" includes="**/*.php">
  <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

Attributes

Attributes for the <date> selector
Name Description Default Required
datetime Specifies the date and time to test for. It should be in a format parsable by PHP's strtotime() function. n/a One of the two
seconds The number of seconds since 1970 that should be tested for. n/a
when Indicates how to interpret the date, whether the files to be selected are those whose last modified times should be before, after, or equal to the specified value. Accepted values are:
  • before - select files whose last modified date is before the indicated date
  • after - select files whose last modified date is after the indicated date
  • equal - select files whose last modified date is this exact date
equal No
granularity The number of milliseconds leeway to use when comparing file modification times. This is needed because not every file system supports tracking the last modified time to the millisecond level. 0 No
checkdirs Indicates whether or not to check dates on directories. false No

Depend

The <depend> tag selects files whose last modified date is later than another, equivalent file in another location.

The <depend> tag supports the use of a contained Mapper element to define the location of the file to be compared against. If no mapper element is specified, the identity type mapper is used.

The <depend> tag is case-sensitive.

<fileset dir="phing-2.4.5/classes" includes="**/*.php">
  <depend targetdir="phing-2.4.6/classes"/>
</fileset>

Attributes

Attributes for the <depend> selector
Name Description Default Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the mapper element, if any. n/a Yes
granularity The number of milliseconds leeway to give before deciding a file is out of date. This is needed because not every file system supports tracking the last modified time to the millisecond level. 0 No

Depth

The <depth> tag selects files based on how many directory levels deep they are in relation to the base directory of the fileset.

<fileset dir="phing/classes" includes="**/*.php">
  <depth max="1"/>
</fileset>

Attributes

Attributes for the <depth> selector
Name Description Default Required
min The minimum number of directory levels below the base directory that a file must be in order to be selected. 0 One of the two
max The maximum number of directory levels below the base directory that a file can be and still be selected. 0

Filename

The <filename> tag acts like the <include> and <exclude> tags within a fileset. By using a selector instead, however, one can combine it with all the other selectors using whatever selector container is desired.

<fileset dir="${src}" includes="**/*">
  <filename name="**/*.php">
</fileset>

Attributes

Attributes for the <filename> selector
Name Description Default Required
name The name of files to select. The name parameter can contain the standard Ant wildcard characters. n/a Yes
casesensitive Whether to pay attention to case when looking at file names. true No
negate Whether to reverse the effects of this filename selection, therefore emulating an exclude rather than include tag. false No

Present

The <present> tag selects files that have an equivalent file in another directory tree.

The <present> tag supports the use of a contained Mapper element to define the location of the file to be compared against. If no mapper element is specified, the identity type mapper is used.

The <present> tag is case-sensitive.

<fileset dir="phing-2.4.6/classes" includes="**/*.php">
  <present present="srconly" targetdir="phing-2.4.5/classes">
</fileset>

Attributes

Attributes for the <present> selector
Name Description Default Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. n/a Yes
present Whether we are requiring that a file is present in the src directory tree only, or in both the src and the target directory tree. Valid values are:
  • srconly - select files only if they are in the src directory tree but not in the target directory tree
  • both - select files only if they are present both in the src and target directory trees
both No

Containsregexp

The <containsregexp> tag selects the files whose contents contain a match to the regular expression specified by the expression attribute.

<fileset dir="${src}" includes="*.txt">
  <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

Attributes

Attributes for the <containsregexp> selector
Name Description Default Required
expression Specifies the regular expression that must match true in every file. n/a Yes
casesensitive Perform a case sensitive match. true No

Size

The <size> tag selects files matching a specified size limit.

<fileset dir="${src}">
  <size value="4" when="more"/>
</fileset>

Attributes

Attributes for the <size> selector
Name Description Default Required
value The size of the file which should be tested for. n/a Yes
units The units that the value attribute is expressed in. When using the standard single letter SI designations, such as "k","M", or "G", multiples of 1000 are used. If you want to use power of 2 units, use the IEC standard: "Ki" for 1024, "Mi" for 1048576, and so on. The default is no units, which means the value attribute expresses the exact number of bytes. n/a No
when Indicates how to interpret the size, whether the files to be selected should be larger, smaller, or equal to that value. Accepted values are:
  • less - select files less than the indicated size
  • more - select files greater than the indicated size
  • equal - select files this exact size
equal No

Type

The <type> tag selects files of a certain type: directory or regular.

<fileset dir="${src}">
  <type type="dir"/>
</fileset>

Attributes

Attributes for the <type> selector
Name Description Default Required
type The type of file which should be tested for. Either file or dir. n/a Yes

And

The <and> tag selects files that are selected by all of the elements it contains. It returns as soon as it finds a selector that does not select the file, so it is not guaranteed to check every selector.

<fileset dir="${src}" includes="**/*.php">
  <and>
    <size value="1000" when="more"/>
    <date datetime="01/01/2011 12:00 AM" when="before"/>
  </and>
</fileset>

Majority

The <majority> tag selects files provided that a majority of the contained elements also select it. Ties are dealt with as specified by the allowtie attribute.

<fileset dir="${src}" includes="**/*.php">
  <majority>
    <contains text="project" casesensitive="false"/>
    <contains text="taskdef" casesensitive="false"/>
    <contains text="BaseSelector" casesensitive="true"/>
  </majority>
</fileset>

Attributes

Attributes for the <majority> selector container
Name Description Default Required
allowtie Whether files should be selected if there are an even number of selectors selecting them as are not selecting them. true No

None

The <none> tag selects files that are not selected by any of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

<fileset dir="${src}" includes="**/*.php">
  <none>
    <size value="1000" when="more"/>
    <date datetime="01/01/2011 12:00 AM" when="before"/>
  </none>
</fileset>

Not

The <not> tag reverses the meaning of the single selector it contains.

<fileset dir="${src}" includes="**/*.php">
  <not>
    <contains text="Phing"/>
  </not>
</fileset>

Or

The <or> tag selects files that are selected by any one of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

<fileset dir="${src}">
  <and>
    <depth max="0"/>
    <filename name="*.png"/>
    <filename name="*.gif"/>
    <filename name="*.jpg"/>
  </and>
</fileset>

Selector

The <selector> tag is used to create selectors that can be reused through references. It is the only selector which can be used outside of any target, as an element of the <project> tag. It can contain only one other selector, but of course that selector can be a container.