Expressions

[This is preliminary documentation and subject to change.]

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 Devide
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.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

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.

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
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.

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 double 1 + 5.0 evaluates to 6.0
double double 1.5 + 5.0 evaluates to 6.5
double int 1.0 + 5 evaluates to 6.0

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 double 5.0 - 1 evaluates to 4.0
double double 5.0 - 1.0 evaluates to 4.0
double int 5.0 - 1 evaluates to 4.0

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 double 5 * 2.0 evaluates to 10.0
double double 5.0 * 2.0 evaluates to 10.0
double int 5.0 * 2 evaluates to 10.0

4.2.4 Devide

Summary

Returns the arithmetic quotient of its operands.

Operands
Left Operand Right Operand Example
int int 10 / 2 evaluates to 5
int double 8 / 2.0 evaluates to 4.0
double double 9.0 / 2.0 evaluates to 4.5
double int 6.0 / 3 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 double 5 % 3.5 evaluates to 1.5
double double 9.0 % 4.7 evaluates to 4.3
double int 8.5 % 2 evaluates to 0.5
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 double 6 = 6.0 evaluates to true
double double 9.5 = 6.7 evaluates to false
double int 8.5 = 8 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 double 6 <> 6.0 evaluates to false
double double 9.5 <> 6.7 evaluates to true
double int 8.5 <> 8 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 double 6 > 4.0 evaluates to true
double double 9.5 > 9.5 evaluates to false
double int 8.3 > 9 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 double 6 >= 4.0 evaluates to true
double double 9.5 >= 9.5 evaluates to true
double int 8.3 >= 9 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 double 6 < 7.0 evaluates to true
double double 9.5 < 9.5 evaluates to false
double int 8.3 < 9 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 double 6 <= 7.0 evaluates to true
double double 9.5 <= 9.5 evaluates to true
double int 8.3 <= 9 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
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
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.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 timespan::from-seconds(30) - timespan::from-seconds(10) evaluates to a timespan representing a duration of 20 seconds
timespan timespan timespan::from-seconds(30) + timespan::from-minutes(10) evaluates to a timespan representing 10 minutes and 30 seconds

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 false

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 false
timespan timespan timespan::from-seconds(30) <= timespan::from-seconds(30) evaluates to true