# 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 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:

- manipulate strings
- manipulate date/time values
- manipulate path names
- read the properties of files/directories
- access current build information and more
- and more

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:

- `and` is evaluated before `or`, left to right. For example `false or true and true and false` evaluates as `false or ((true and true) and false)`
- multiplication,division and modulus are evaluated before addition and subtraction, left to right. For example `1 + 2 * 3 / 4` evaluates as `1 + ((2 * 3) / 4)`
- parentheses can be used to override the default operator precedence. For example `(1 + 2) * 3` evaluates as written, even though the multiplication has precedence over addition

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:

- + operator
- - operator
- * operator
- / operator
- % operator
- == operator
- != operator
- > operator
- >= operator
- < operator
- <= operator
- unary plus
- unary minus (negation)

#### 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:

- == operator
- != operator
- > operator
- >= operator
- < operator
- <= operator
- and operator
- or operator

#### 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:

- + operator
- == operator
- != operator
- > operator
- >= operator
- < operator
- <= operator

#### 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:

- + operator
- - operator
- == operator
- != operator
- > operator
- >= operator
- < operator
- <= operator

#### 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:

- == operator
- != operator
- > operator
- >= operator
- < operator
- <= operator

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