NAnt -> Help -> Fundamentals -> Expressions v0.90

Expressions

Contents

1 Introduction
2 Expression syntax
3 Data types
4 Operators
4.1 Operator precedence
4.2 Operators on Numeric Values
4.2.1 Add
4.2.2 Subtract
4.2.3 Multiply
4.2.4 Divide
4.2.5 Mod
4.2.6 Equal
4.2.7 Inequal
4.2.8 Greater than
4.2.9 Greater than or equal
4.2.10 Less than
4.2.11 Less than or equal
4.2.12 Unary plus
4.2.13 Unary minus
4.3 Operators on Boolean Values
4.3.1 Equal
4.3.2 Inequal
4.3.3 Greater than
4.3.4 Greater than or equal
4.3.5 Less than
4.3.6 Less than or equal
4.3.7 Logical and
4.3.8 Logical or
4.4 Operators on String Values
4.4.1 Concat
4.4.2 Equal
4.4.3 Inequal
4.4.4 Greater than
4.4.5 Greater than or equal
4.4.6 Less than
4.4.7 Less than or equal
4.5 Operators on TimeSpan and DateTime Values
4.5.1 Add
4.5.2 Subtract
4.5.3 Equal
4.5.4 Inequal
4.5.5 Greater than
4.5.6 Greater than or equal
4.5.7 Less than
4.5.8 Less than or equal
4.6 Operators on Version Values
4.6.1 Equal
4.6.2 Inequal
4.6.3 Greater than
4.6.4 Greater than or equal
4.6.5 Less than
4.6.6 Less than or equal

1 Introduction

Expressions are simple, yet powerful mechanism that allows you to write advanced formulas to be used in task arguments and conditions that direct the build process. Expressions can access project properties and call builtin or user-defined functions.

NAnt provides a rich set of bulitin functions, that allow you to:

For a full list of supported functions, click here.

2 Expression Syntax

Expressions can be used in all task arguments, by using ${...} notation. You may use standard syntax for arithmetical (addition, subtraction, multiplication, division, modulus), logical (negation, conjunction, alternative) and relational operators (equality, inequality). To call functions, use prefix::function-name(argument1, ..., argumentN) syntax. To access properties, you simply use their names without any prefix or suffix. See the examples section below for more information.

NOTE: Expressions are often used in XML attributes. The grammar specified in this section applies to the attribute value after XML 1.0 normalization. So, for example, if the grammar uses the character <, this must not appear in the XML source as < but must be quoted according to XML 1.0 rules by, for example, entering it as &lt;.

Examples:

  1. Accessing a property:

    <property name="build.version" value="3" />
    <echo message="The current date is: ${build.version}" />

    This will output the current value of build.version property.

  2. Calling a function

    <echo message="The current date is: ${datetime::now()}" />

    This will output the current date and time.

  3. Storing the result of an expression

    To store the result of an expression in a property, use the <property> task:

    <property name="autoexec-present" value="${file::exists('c:\autoexec.bat')}" />

    This will set the property autoexec-present to either true or false depending on whether the specified file exists or not.

  4. Real-life expression use

    <property name="myprj.basedir" value="c:\" />
    <property name="filename" value="${path::combine(myprj.basedir,'version.txt')}" />

    <if test="${not file::exists(filename) or file::get-length(filename) = 0}">
        <echo message="The version file ${filename} doesn't exist or is empty!" />
    </if>

    This will check for the existence of a file version.txt in a directory specified by myprj.basedir. Note that this makes use of the short-circuit evaluation supported by NAnt, so you can test for the existence of the file and check its length in the same expression. ( ie like C, NAnt will not evaluate the second part of an 'or' expression if the first evaluates to true )

  5. Using expressions to conditionally execute tasks

    All tasks support if and unless attributes. Expressions can be used there to control which tasks get executed:

    <property name="myprj.basedir" value="c:\" unless="property::exists('myprj.basedir')" />
    <csc target="library" output="out.dll" ...
         if="${datetime::now() - file::get-last-write-time('out.dll')) > timespan::from-hours(1)}">
    ...
    </csc>

    This will rebuild the C# library only if it was last rebuilt more than an hour ago.

3 Data types

Expressions can access, pass and return values of the following types:

Type Allowed values
int 32-bit signed integer value
long 64-bit signed integer value
double 64-bit signed double precision floating point value
boolean true or false
string strings of characters of any length.
datetime values represeting date & time (range is from 00:00:00, January 1, 1 AD to 23:59:59, December 31, 9999 AD)
timespan represents a time interval.
version represents a version number consisting of two to four components.

In addition, the expression evaluation engine allows you to return and pass values of any CLI type through the use of custom functions. Note that there's no support for implicit type conversions.

4 Operators

4.1 Operator precedence

NAnt expressions support standard ( c style ) operator precedence, that we're accustomed to:

NOTE: Because NAnt supports properties whose names can contain dashes, there's a possible ambiguity between the subtraction of two properties and accessing a single property with a name containing a dash:

aaa-bbb - this is ambiguous. It could either be property aaa MINUS property bbb or property aaa-bbb.

To avoid confusion, it's recommended to surround the subtraction operator (or even better, all binary operators) with spaces. The expression aaa - bbb always evaluates as a subtraction.

4.2 Operators on Numeric Values

The following operators are supported on numeric values:

4.2.1 Add

Summary

Returns the arithmetic sum of its operands.

Operands
Left Operand Right Operand Example
int int 1 + 5 evaluates to 6
int long 1 + 6666666667 evaluates to 6666666668
int double 1 + 5.0 evaluates to 6.0
long long 6666666667 + 11111111111 evaluates to 17777777778
long int 6666666667 + 1 evaluates to 6666666668
long double 6666666667 + 1.5 evaluates to 6666666668.5
double double 1.5 + 5.0 evaluates to 6.5
double int 1.0 + 5 evaluates to 6.0
double long 1.5 + 6666666667 evaluates to 6666666668.5

4.2.2 Subtract

Summary

Returns the arithmetic difference of its operands.

Operands
Left Operand Right Operand Example
int int 5 - 1 evaluates to 4
int long 5 - 6666666667 evaluates to -6666666662
int double 5.0 - 1 evaluates to 4.0
long long 11111111111 - 6666666667 evaluates to 4444444444
long int 6666666667 - 5 evaluates to 6666666662
long double 6666666667 - 1.5 evaluates to 6666666665.5
double double 5.0 - 1.0 evaluates to 4.0
double int 5.0 - 1 evaluates to 4.0
double long 1.5 - 6666666667 evaluates to -6666666665.5

4.2.3 Multiply

Summary

Returns the arithmetic product of its operands.

Operands
Left Operand Right Operand Example
int int 5 * 2 evaluates to 10
int long 2 * 6666666667 evaluates to 13333333334
int double 5 * 2.0 evaluates to 10.0
long long 6666666667 * long::parse('2') evaluates to 13333333334
long int 6666666667 * 2 evaluates to 13333333334
long double 6666666667 * 1.7 evaluates to 11333333333.9
double double 5.0 * 2.0 evaluates to 10.0
double int 5.0 * 2 evaluates to 10.0
double long 1.7 * 6666666667 evaluates to 11333333333.9

4.2.4 Divide

Summary

Returns the arithmetic quotient of its operands.

Operands
Left Operand Right Operand Example
int int 10 / 2 evaluates to 5
int long 10 / 10000000000 evaluates to 0.000000001
int double 8 / 2.0 evaluates to 4.0
long long 13333333334 / 6666666667 evaluates to 2
long int 13333333334 / 2 evaluates to 6666666667
long double 13333333334 / 2.0 evaluates to 6666666667.0
double double 9.0 / 2.0 evaluates to 4.5
double int 6.0 / 3 evaluates to 2.0
double long 20000000000.0 / 10000000000 evaluates to 2.0
Remarks

If the divisor is zero, then an error is raised.

4.2.5 Mod

Summary

Returns the remainder after dividing its first operand by its second.

Operands
Left Operand Right Operand Example
int int 5 % 3 evaluates to 2
int long 10 % 6666666667 evaluates to 10
int double 5 % 3.5 evaluates to 1.5
long long 13333333334 % 6666666667 evaluates to 0
long int 6666666667 % 10 evaluates to 7
long double 6666666667 % 3.5 evaluates to 3.0
double double 9.0 % 4.7 evaluates to 4.3
double int 8.5 % 2 evaluates to 0.5
double long 20000000000.0 % 6666666667 evaluates to 6666666666.0
Remarks

If the divisor is zero, then an error is raised.

4.2.6 Equal

Summary

Returns true if and only if the value of the first operand is equal to the value of the second operand.

Operands
Left Operand Right Operand Example
int int 5 == 3 evaluates to false
int long 5 == 6666666667 evaluates to false
int double 6 == 6.0 evaluates to true
long long 6666666667 == 6666666667 evaluates to true
long int 6666666667 == 665 evaluates to false
long double 6666666667 == 6666666667.0 evaluates to true
double double 9.5 == 6.7 evaluates to false
double int 8.5 == 8 evaluates to false
double long 8.5 == 6666666667 evaluates to false

4.2.7 Inequal

Summary

Returns true if and only if the value of the first operand is not equal to the value of the second operand.

Operands
Left Operand Right Operand Example
int int 5 != 3 evaluates to true
int long 5 != 6666666667 evaluates to true
int double 6 != 6.0 evaluates to false
long long 6666666667 != 6666666667 evaluates to false
long int 6666666667 != 665 evaluates to true
long double 6666666667 != 6666666667.0 evaluates to false
double double 9.5 != 6.7 evaluates to true
double int 8.5 != 8 evaluates to true
double long 8.5 != 6666666667 evaluates to true

4.2.8 Greater than

Summary

Returns true if and only if the first operand is greater than the second operand.

Operands
Left Operand Right Operand Example
int int 5 > 3 evaluates to false
int long 5 > 6666666667 evaluates to false
int double 6 > 4.0 evaluates to true
long long 6666666667 > 6666666667 evaluates to false
long int 6666666667 > 665 evaluates to true
long double 6666666667 > 6666666667.0 evaluates to false
double double 9.5 > 9.5 evaluates to false
double int 8.3 > 9 evaluates to false
double long 8.5 > 6666666667 evaluates to false

4.2.9 Greater than or equal

Summary

Returns true if and only if the first operand is greater than or equal to second operand.

Operands
Left Operand Right Operand Example
int int 5 >= 3 evaluates to false
int long 5 >= 6666666667 evaluates to false
int double 6 >= 4.0 evaluates to true
long long 6666666667 >= 6666666667 evaluates to true
long int 6666666667 >= 665 evaluates to true
long double 6666666667 >= 6666666667.0 evaluates to true
double double 9.5 >= 9.5 evaluates to true
double int 8.3 >= 9 evaluates to false
double long 8.5 >= 6666666667 evaluates to false

4.2.10 Less than

Summary

Returns true if and only if the first operand is less than the second operand.

Operands
Left Operand Right Operand Example
int int 5 < 3 evaluates to false
int long 5 < 6666666667 evaluates to true
int double 6 < 7.0 evaluates to true
long long 6666666667 < 6666666667 evaluates to false
long int 6666666667 < 665 evaluates to false
long double 6666666667 < 6666666667.0 evaluates to false
double double 9.5 < 9.5 evaluates to false
double int 8.3 < 9 evaluates to true
double long 8.5 < 6666666667 evaluates to true

4.2.11 Less than or equal

Summary

Returns true if and only if the first operand is less than or equal to second operand.

Operands
Left Operand Right Operand Example
int int 5 <= 3 evaluates to false
int long 5 <= 6666666667 evaluates to true
int double 6 <= 7.0 evaluates to true
long long 6666666667 <= 6666666667 evaluates to true
long int 6666666667 <= 665 evaluates to false
long double 6666666667 <= 6666666667.0 evaluates to true
double double 9.5 <= 9.5 evaluates to true
double int 8.3 <= 9 evaluates to true
double long 8.5 <= 6666666667 evaluates to true

4.2.12 Unary plus

Summary

Returns its operand with the sign unchanged. Semantically, this operation performs no operation.

Operands
Operand Example
int (+1) evaluates to 1
long (+6666666667) evaluates to 6666666667
double (+1.5) evaluates to 1.5

4.2.13 Unary minus

Summary

Returns its operand with the sign reversed.

If the operand is positive, its negative is returned; if it is negative, its positive is returned.

Operands
Operand Example
int (-1) evaluates to -1
long (-6666666667) evaluates to -6666666667
double (-9.6) evaluates to -9.6

4.3 Operators on Boolean Values

The following operators are supported on boolean values:

4.3.1 Equal

Summary

Returns true if both operands are true or if both operands are false.

Examples

4.3.2 Inequal

Summary

Returns true if the first operand is true and the second operand is false, or the first operand is false and the second operand is true.

Examples

4.3.3 Greater than

Summary

Returns true if the first operand is true and the second operand is false; otherwise, returns false.

Examples

4.3.4 Greater than or equal

Summary

Returns true if the first operand is true and the second operand is false, or both operands are either true or false.

Examples

4.3.5 Less than

Summary

Returns true if the first operand is false and the second operand is true; otherwise, returns false.

Examples

4.3.6 Less than or equal

Summary

Returns true if the first operand is false and the second operand is true, or both operands are either true or false.

Examples

4.3.7 Logical and

Summary

Returns true if both operands are true, otherwise returns false.

Examples

<if test="${A and B}">

4.3.8 Logical or

Summary

Returns true if either operand is true, otherwise returns false.

Examples

<if test="${A or B}">

4.4 Operators on String Values

The following operators are supported on string values:

4.4.1 Concat

Summary

Returns the concatenation of both string operands.

Examples

4.4.2 Equal

Summary

Returns true if the value of the left operand is the same as the value of the right operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.4.3 Inequal

Summary

Returns true if the value of the first operand is not the same as the value of the second operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.4.4 Greater than

Summary

Returns true if the first operand is greater than the seconds operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.4.5 Greater than or equal

Summary

Returns true if the first operand is greater than or equal to the seconds operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.4.6 Less than

Summary

Returns true if the first operand is less than the seconds operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.4.7 Less than or equal

Summary

Returns true if the first operand is less than or equal to the seconds operand.

Remarks

The comparison is case-sensitive and culture-insensitive.

4.5 Operators on TimeSpan and DateTime Values

The following operators are supported on timespan and datetime values:

4.5.1 Add

Summary

Returns the result of adding the value of the left operand to the value of the right operand.

Operands
Left Operand Right Operand Example
datetime timespan datetime::now() + timespan::from-days(10) evaluates to a datetime 10 days in the future
timespan timespan timespan::from-seconds(30) + timespan::from-minutes(10) evaluates to a timespan representing a duratio of 10 minutes and 30 seconds

4.5.2 Subtract

Summary

Returns the result of subtracting the value of the right operand from the value of the left operand.

Operands
Left Operand Right Operand Example
datetime datetime (datetime::now() + timespan::from-days(10)) - datetime::now evaluates to a timespan representing a duration of 10 days
datetime timespan datetime::now() - timespan::from-days(3) evaluates to a datetime 3 days in the past
timespan timespan timespan::from-minutes(15) - timespan::from-minutes(10) evaluates to a timespan representing 5 minutes

4.5.3 Equal

Summary

Returns true if the value of the left operand is the same as the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() == (datetime::now() + timespan::from-days(10)) evaluates to false
timespan timespan timespan::from-seconds(30) == timespan::from-seconds(30) evaluates to true

4.5.4 Inequal

Summary

Returns true if the value of the left operand is not the same as the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() != (datetime::now() + timespan::from-days(10)) evaluates to true
timespan timespan timespan::from-seconds(30) != timespan::from-seconds(30) evaluates to false

4.5.5 Greater than

Summary

Returns true if the value of the left operand is greater than the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() > (datetime::now() + timespan::from-days(10)) evaluates to false
timespan timespan timespan::from-seconds(30) > timespan::from-seconds(30) evaluates to false

4.5.6 Greater than or equal

Summary

Returns true if the value of the left operand is greater than or equal to the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() >= (datetime::now() + timespan::from-days(10)) evaluates to false
timespan timespan timespan::from-seconds(30) >= timespan::from-seconds(30) evaluates to true

4.5.7 Less than

Summary

Returns true if the value of the left operand is less than the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() < (datetime::now() + timespan::from-days(10)) evaluates to true
timespan timespan timespan::from-seconds(30) < timespan::from-seconds(30) evaluates to false

4.5.8 Less than or equal

Summary

Returns true if the value of the left operand is less than the value of the right operand.

Operands
Left Operand Right Operand Example
datetime datetime datetime::now() <= (datetime::now() + timespan::from-days(10)) evaluates to true
timespan timespan timespan::from-seconds(30) <= timespan::from-seconds(30) evaluates to true

4.6 Operators on Version Values

The following operators are supported on version values:

4.6.1 Equal

Summary

Returns true if the value of the left operand is the same as the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') == version::parse('1.2') evaluates to true

4.6.2 Inequal

Summary

Returns true if the value of the left operand is not the same as the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') != version::parse('1.3.1') evaluates to true

4.6.3 Greater than

Summary

Returns true if the value of the left operand is greater than the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') > version::parse('1.3.1') evaluates to false

4.6.4 Greater than or equal

Summary

Returns true if the value of the left operand is greater than or equal to the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') >= version::parse('1.2') evaluates to true

4.6.5 Less than

Summary

Returns true if the value of the left operand is less than the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') < version::parse('1.3.1') evaluates to true

4.6.6 Less than or equal

Summary

Returns true if the value of the left operand is less than or equal to the value of the right operand.

Operands
Left Operand Right Operand Example
version version version::parse('1.2') <= version::parse('1.2') evaluates to true