<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Language" content="en-ca" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="Functions" />
<link rel="stylesheet" type="text/css" href="../style.css" />
<title>NAnt - Functions</title>
</head>
<body>
<table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
<tr>
<td class="NavBar-Cell">
<a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="->" width="13" height="9" />
<a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif" /> <a href="index.html">
Fundamentals</a> <img height="9" alt="->" src="../images/arrow.gif" width="13" />
Functions
</td>
<td class="NavBar-Cell" align="right">
v0.92
</td>
</tr>
</table>
<h1>Functions</h1>
<p>NAnt provides a rich set of bulitin functions, that allow you to:</p>
<ul>
<li>
manipulate strings</li>
<li>
manipulate date/time values</li>
<li>
manipulate path names</li>
<li>
read the properties of files/directories</li>
<li>
access current build information and more</li>
<li>
and more</li>
</ul>
<p>For a full list of supported functions, click <a href="../functions/index.html">here</a>.</p>
<h3><a id="syntax" />Function Call Syntax</h3>
<p>
To call functions, use <code>prefix::function-name(argument1, ..., argumentN)</code>
syntax within expressions. NAnt will (implicitly) try to convert the arguments
you pass to functions to correct types and will report an error in case of
failure.
</p>
<p>
For example, assuming you would like to call <code>string::contains('0123456789',1)</code>
which expects two <code>string</code> parameters, but you want to pass the
second parameter which is an integer. NAnt would attempt to convert the second
parameter from <code>int</code> to <code>string</code>, which succeeds and
function is called as if it was written as <code>string::contains('0123456789','1')</code>.
</p>
<p>The following table shows the possible type conversions:</p>
<div class="table">
<table>
<tr>
<th>
From Type</th>
<th>
To Type</th>
<th>
Allowed</th>
<th>
Remarks</th>
</tr>
<tr>
<td><code>int</code></td>
<td><code>string</code></td>
<td>Yes</td>
<td>The conversion is always possible.</td>
</tr>
<tr>
<td><code>int</code></td>
<td><code>double</code></td>
<td>Yes</td>
<td>The conversion is always possible.</td>
</tr>
<tr>
<td><code>int</code></td>
<td><code>boolean</code></td>
<td>No</td>
<td>Can be done with the <code>if()</code> conditional operator or simply as <code>(value
<> 0)</code></td>
</tr>
<tr>
<td><code>int</code></td>
<td><code>datetime</code></td>
<td>No</td>
<td>You cannot convert from <code>int</code> to <code>datetime</code>.</td>
</tr>
<tr>
<td><code>int</code></td>
<td><code>timespan</code></td>
<td>No</td>
<td>You can use the <code>timespan::from-xxx</code> functions to construct a <code>timespan</code> from a given number of days, months, ....</td>
</tr>
<tr>
<th colspan="4">
</th>
</tr>
<tr>
<td><code>string</code></td>
<td><code>int</code></td>
<td>Yes</td>
<td>If the string doesn't represent an integer value, an error is reported.</td>
</tr>
<tr>
<td><code>string</code></td>
<td><code>double</code></td>
<td>Yes</td>
<td>If the string doesn't represent a floating point value, an error is reported.</td>
</tr>
<tr>
<td><code>string</code></td>
<td><code>boolean</code></td>
<td>Yes</td>
<td>If the string isn't either <code>true</code> or <code>false</code> (case
insensitive), an error is reported.</td>
</tr>
<tr>
<td><code>string</code></td>
<td><code>datetime</code></td>
<td>Yes</td>
<td>If the string doesn't represent a valid date/time, an error is reported.
Date/time string format is <code>MM/DD/YYYY HH:MI:SS</code></td>
</tr>
<tr>
<td><code>string</code></td>
<td><code>timespan</code></td>
<td>No</td>
<td>
You can use <code>timespan::parse</code> to construct a <code>timespan</code>
from a time indicated by a given string. If the string doesn't represent a valid
timespan, an error is reported.
</td>
</tr>
<tr>
<th colspan="4">
</th>
</tr>
<tr>
<td><code>double</code></td>
<td><code>int</code></td>
<td>Yes</td>
<td>If the string doesn't represent an integer value, an error is reported.</td>
</tr>
<tr>
<td><code>double</code></td>
<td><code>string</code></td>
<td>Yes</td>
<td>The converted string uses dot as a fractional part separator so the result
looks like <code>0.1234567</code></td>
</tr>
<tr>
<td><code>double</code></td>
<td><code>boolean</code></td>
<td>No</td>
<td>You cannot convert from <code>double</code> to <code>boolean</code>.</td>
</tr>
<tr>
<td><code>double</code></td>
<td><code>datetime</code></td>
<td>No</td>
<td>You cannot convert from <code>double</code> to <code>datetime</code>.</td>
</tr>
<tr>
<td><code>double</code></td>
<td><code>timespan</code></td>
<td>No</td>
<td>You can use the <code>timespan::from-xxx</code> functions to construct a <code>timespan</code> from a given number of days, months, ....</td>
</tr>
<tr>
<th colspan="4">
</th>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>int</code></td>
<td>No</td>
<td>You cannot convert from <code>boolean</code> to <code>int</code>. You may
want to use <code>if(boolvalue,1,0)</code> instead.</td>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>string</code></td>
<td>Yes</td>
<td>The result is <code>'True'</code> or <code>'False'</code> string.</td>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>double</code></td>
<td>No</td>
<td>You cannot convert from <code>boolean</code> to <code>double</code>.</td>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>datetime</code></td>
<td>No</td>
<td>You cannot convert from <code>boolean</code> to <code>datetime</code>.</td>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>timespan</code></td>
<td>No</td>
<td>You cannot convert from <code>boolean</code> to <code>timespan</code>.</td>
</tr>
<tr>
<th colspan="4">
</th>
</tr>
<tr>
<td><code>datetime</code></td>
<td><code>int</code></td>
<td>No</td>
<td>You cannot convert from <code>datetime</code> to <code>int</code>.</td>
</tr>
<tr>
<td><code>datetime</code></td>
<td><code>string</code></td>
<td>Yes</td>
<td>The result is a datetime string with the following format: <code>MM/DD/YYYY HH:MI:SS</code></td>
</tr>
<tr>
<td><code>datetime</code></td>
<td><code>double</code></td>
<td>No</td>
<td>You cannot convert from <code>datetime</code> to <code>double</code>.</td>
</tr>
<tr>
<td><code>datetime</code></td>
<td><code>boolean</code></td>
<td>No</td>
<td>You cannot convert from <code>datetime</code> to <code>boolean</code>.</td>
</tr>
<tr>
<td><code>datetime</code></td>
<td><code>timespan</code></td>
<td>No</td>
<td>You can use the value of <code>datetime::get-ticks</code> to construct a <code>timespan</code> using <code>timespan::from-ticks</code>.</td>
</tr>
<tr>
<th colspan="4">
</th>
</tr>
<tr>
<td><code>timespan</code></td>
<td><code>int</code></td>
<td>No</td>
<td>You cannot convert from <code>timespan</code> to <code>int</code>.</td>
</tr>
<tr>
<td><code>timespan</code></td>
<td><code>double</code></td>
<td>No</td>
<td>You can use <code>timespan::get-ticks</code> to convert from <code>timespan</code> to <code>double</code>.</td>
</tr>
<tr>
<td><code>timespan</code></td>
<td><code>boolean</code></td>
<td>No</td>
<td>You cannot convert from <code>timespan</code> to <code>boolean</code>.</td>
</tr>
<tr>
<td><code>timespan</code></td>
<td><code>string</code></td>
<td>No</td>
<td>You can use <code>timespan::to-string</code> to obtain the string representation of a <code>timespan</code>.</td>
</tr>
<tr>
<td><code>timespan</code></td>
<td><code>datetime</code></td>
<td>No</td>
<td>You cannot convert from <code>timespan</code> to <code>datetime</code>.</td>
</tr>
</table>
</div>
<h3><a id="custom" />Custom Functions</h3>
<p>
Just as you can extend NAnt with your own tasks it is also possible to
implement your own functions for use in build files.</p>
<p>Functions can be implemented in any .NET language and are loaded in the same
manner as tasks. ie either by locating your custom function assembly in the
NAnt bin directory or using the <code><a href="../tasks/loadtasks.html"><loadtasks></a></code>
task. Example C# code for a Hello World function :
</p>
<p>Define a custom function using C#.</p>
<pre class="code">
[FunctionSet("hello", "Hello")]
public class HelloFunctions : FunctionSetBase {
public HelloFunctions(Project project, PropertyDictionary properties) : base(project, properties) {
}
[Function("hello-world")]
public static string HelloWorldfunc() {
return "Hello World!!";
}
}
</pre>
<p>and call that function from a build file.</p>
<pre class="code">
<echo message="${hello::hello-world()}" />
</pre>
<p>A quick and easy way to develop new functions is to use the <code><a href="../tasks/script.html">
<script></a></code> task. This allows you to create and test new functions
without the overhead of building an external assembly. The <code><a href="../tasks/script.html">
<script></a></code> task documentation contains examples of custom function
definitions.</p>
</body>
</html>
