5.8 Conditions

Conditions are nested elements of the condition, if and waitfor tasks.

5.8.1 not

The <not> element expects exactly one other condition to be nested into this element, negating the result of the condition. It doesn't have any attributes and accepts all nested elements of the condition task as nested elements as well.

5.8.2 and

The <and> element doesn't have any attributes and accepts an arbitrary number of conditions as nested elements. This condition is true if all of its contained conditions are, conditions will be evaluated in the order they have been specified in the build file.

The <and> condition has the same shortcut semantics as the && operator in some programming languages, as soon as one of the nested conditions is false, no other condition will be evaluated.

5.8.3 or

The <or> element doesn't have any attributes and accepts an arbitrary number of conditions as nested elements. This condition is true if at least one of its contained conditions is, conditions will be evaluated in the order they have been specified in the build file.

The <or> condition has the same shortcut semantics as the || operator in some programming languages, as soon as one of the nested conditions is true, no other condition will be evaluated.

5.8.4 xor

The <xor> element performs an exclusive or on all nested elements, similar to the ^ operator in PHP. It only evaluates to true if an odd number of nested conditions are true. There is no shortcutting of evaluation, unlike the <and> and <or> tests. It doesn't have any attributes and accepts all nested elements of the condition task as nested elements as well.

5.8.5 os

Test whether the current operating system is of a given type.

Table 5.1: OS Attributes

AttributeDescriptionRequired
familyThe name of the operating system family to expect.Yes

Supported values for the family attribute are:

  • windows (for all versions of Microsoft Windows)

  • mac (for all Apple Macintosh systems)

  • unix (for all Unix and Unix-like operating systems)

Note: machines running OSX match on the mac and unix families! To test for Macs that don't run a Unix-like OS, use the following code:

<condition property="isMacOsButNotMacOsX">
    <and>
        <os family="mac"/>
        <not>
            <os family="unix"/>
        </not>
    </and>
</condition>

5.8.6 equals

Tests whether the two given Strings are identical

Table 5.2: equals Attributes

AttributeDescriptionRequired
arg1First string to test.Yes
arg2Second string to test.Yes
casesensitivePerform a case sensitive comparison. Default is true.No
trimTrim whitespace from arguments before comparing them. Default is false.No

5.8.7 versioncompare

Compares two given versions

Table 5.3: versioncompare Attributes

AttributeDescriptionRequired
versionThe version you want to compareYes
desiredVersionThe version you want to compare againstYes
operatorThe operator to use for version comparison. Default is >=.No
debugTurns on debug mode, that echoes the comparion message. Default is false.No

<versioncompare version="${aProperty}" desiredVersion="1.3" operator="gt" />

This condition internally uses PHP version_compare(). Operators and behavior are the same.

5.8.8 http

Condition to wait for a HTTP request to succeed.

Attributes are:

  • url - the URL of the request.
  • errorsBeginAt - number at which errors begin at.
  • quiet - Set quiet mode, which suppresses warnings and errors.

Table 5.4: http Attributes

AttributeDescriptionRequired
urlThe URL of the request.Yes
errorsBeginAtNumber at which errors begin at. - Default: 400No
requestMethodSets the method to be used when issuing the HTTP request. - Default: GETNo
followRedirectsWhether redirects sent by the server should be followed. - Default: trueNo
quietSet quiet mode, which suppresses warnings and errors. Default is falseNo

<http url="http://url.to.test" errorsBeginAt="404" />

5.8.9 PDOSQLExec

PDOSQLExecTask can also be used as condition. Returns true when the connection to a database succeeds, and false otherwise. This condition requires the PDO extension to work properly.

Table 5.5: PDOSQLExec condition attributes

AttributeDescriptionRequired
url The PDO Data Source Name (DSN). Yes
userid The username for current DSN. No
password The password for current DSN. No

This is a typical use case for PDOSQLExec condition:

<target name="wait-for-mysql">
    <waitfor timeoutproperty="mysql.timeout" maxwait="60" maxwaitunit="second">
        <pdosqlexec url="mysql:host=localhost;port=3306"
                  userid="${db.username}"
                  password="${db.password}"/>
    </waitfor>
    <fail if="mysql.timeout">Cannot reach database</fail>
</target>

If you also want to check if a specific schema exists, you can include the schema's name in your url:

<pdosqlexec url="mysql:host=127.0.0.1;port=3306;dbname=foo"
          userid="${db.username}"
          password="${db.password}"/>

This condition uses PDO behind the scenes. Therefore, if you have installed the appropriate driver you should also be able to reach many other DBMS. For example, for a PostgreSQL database:

<pdosqlexec url="pgsql:host=localhost;port=5432;dbname=bar"
          userid="${db.username}"
          password="${db.password}"/>

You should never hard-code sensitive data in your buildfile, you could use an unversioned property file instead. Also, be careful when using verbose or debug mode since you can expose sensitive data.

5.8.10 socket

Condition to test for a (tcp) listener on a specified host and port.

Table 5.6: socket Attributes

AttributeDescriptionRequired
serverThe hostname or ip address of the server.Yes
portThe port number of the server.Yes

<socket server="localhost" port="80" />

5.8.11 hasfreespace

Condition returns true if selected partition has the requested space, false otherwise.

Table 5.7: hasfreespace Attributes

AttributeDescriptionRequired
partitionAbsolute path to the partition/device to check.Yes
neededThe amount of free space required. Examples: 250M, 10G, 1T.Yes

Note

File size can be written using IEC and SI suffixes, bytes are assumed when suffix is not specified. The following suffixes (case-insensitive) are supported:

Table 5.8: Supported file size suffixes

StandardSuffixesEquivalence
IECB. 1 byte
K, Ki, KiB, kibi, kibibyte. 1024 bytes
M, Mi, MiB, mebi, mebibyte. 1024 kibibytes
G, Gi, GiB, gibi, gibibyte. 1024 mebibytes
T, Ti, TiB, tebi, tebibyte. 1024 gibibytes
SI kB, kilo, kilobyte. 1000 bytes
MB, mega, megabyte. 1000 kilobytes
GB, giga, gigabyte. 1000 megabytes
TB, tera, terabyte. 1000 gigabytes

On Unix-like platforms:

<hasfreespace partition="/" needed="250M" />

On Windows:

<hasfreespace partition="c:" needed="10M" />

This condition internally uses PHP disk_free_space().

5.8.12 isset

Test whether a given property has been set in this project.

Table 5.9: isset Attributes

AttributeDescriptionRequired
propertyThe name of the property to test.Yes

5.8.13 contains

Tests whether a string contains another one.

Table 5.10: contains Attributes

AttributeDescriptionRequired
stringThe string to search in.Yes
substringThe string to search for.Yes
casesensitivePerform a case sensitive comparison. Default is true.No

5.8.14 istrue

Tests whether a string evaluates to true.

Table 5.11: istrue Attributes

AttributeDescriptionRequired
valuevalue to testYes

<istrue value="${someproperty}"/>
<istrue value="false"/>

5.8.15 isfalse

Tests whether a string evaluates to not true, the negation of <istrue>

Table 5.12: isfalse Attributes

AttributeDescriptionRequired
valuevalue to testYes

<isfalse value="${someproperty}"/>
<isfalse value="false"/>

5.8.16 ispropertytrue

Tests whether a property evaluates to true.

Table 5.13: ispropertytrue Attributes

AttributeDescriptionRequired
propertyproperty to testYes

<ispropertytrue property="someproperty"/>

5.8.17 ispropertyfalse

Tests whether a property evaluates to not true, the negation of <ispropertytrue>

Table 5.14: ispropertyfalse Attributes

AttributeDescriptionRequired
propertyproperty name to testYes

<ispropertyfalse property="someproperty"/>

5.8.18 referenceexists

Tests whether a specified reference exists.

Table 5.15: referenceexists Attributes

AttributeDescriptionRequired
refreference to test forYes

<referenceexists ref="${someid}"/>

5.8.19 available

This condition is identical to the Available task, all attributes and nested elements of that task are supported, the property and value attributes are redundant and will be ignored.

<if>
    <available file="README.md"/>
    <then>
        <echo message="Please read README.md"/>
    </then>
</if>

5.8.20 filesmatch

Test two files for matching. Nonexistence of one file results in "false", although if neither exists they are considered equal in terms of content. This test does a byte for byte comparison, so test time scales with byte size. NB: if the files are different sizes, one of them is missing or the filenames match the answer is so obvious the detailed test is omitted.

Table 5.16: filesmatch Attributes

AttributeDescriptionRequired
file1First file to test.Yes
file2Second file to test.Yes

<filesmatch file1="${file1}" file2="${file2}"/>

5.8.21 isfileselected

Test whether a file passes an embedded selector.

Table 5.17: isfileselected Attributes

AttributeDescriptionRequired
fileThe file to check if is passes the embedded selector.Yes
basedirThe base directory to use for name based selectors. It this is not set, the project's basedirectory will be used.No

<isfileselected file="a.xml">
  <date datetime="06/28/2000 2:02 pm" when="equal"/>
</isfileselected>

5.8.22 isfailure

Test the return code of an executable for failure.

Table 5.18: isfailure Attributes

AttributeDescriptionRequired
codeThe return code to test.Yes

<exec command="test" returnProperty="return.code"/>
<if>
    <isfailure code="${return.code}"/>
    <then><echo msg="${return.code}"/></then>
</if>

5.8.23 matches

Test if the specified string matches the specified regular expression pattern.

Table 5.19: matches Attributes

AttributeDescriptionRequired
stringThe string to test.Yes
patternThe regular expression pattern used to test.Yes
casesensitivePerform a case sensitive match. Default is true.No
multilinePerform a multi line match. Default is false.No
modifiersThe regular expression modifiers used to test.No