<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Scriptdef Task</title>
</head>
<body>
<h2><a name="script">Scriptdef</a></h2>
<h3>Description</h3>
<p>Scriptdef can be used to define an Ant task using a scripting language. Ant
scripting languages supported by
<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> may be
used to define the script. Scriptdef provides a mechanism to encapsulate
control logic from a build within an Ant task minimizing the need for
providing control style tasks in Ant itself. Complex logic can be made
available while retaining the simple structure of an Ant build file. Scriptdef
is also useful for prototyping new custom tasks. Certainly as the complexity
of the script increases it would be better to migrate the task definition
into a Java based custom task.
</p>
<p><b>Note:</b> This task depends on external libraries not included in the
Ant distribution. See
<a href="../install.html#librarydependencies">Library Dependencies</a>
for more information.</p>
<p>The attributes and nested elements supported by the task may be defined
using <code><attribute></code> and <code><element></code> nested elements. These are
available to the script that implements the task as two collection style
script variables <code>attributes</code> and <code>elements</code>. The
elements in the <code>attributes</code> collection may be accessed by the
attribute name. The <code>elements</code> collection is accessed by the nested
element name. This will return a list of all instances of the nested element.
The instances in this list may be accessed by an integer index.
</p>
<p><b>Note:</b> Ant will turn all attribute and element names into all
lowercase names, so even if you use name="SomeAttribute", you'll have
to use "someattribute" to retrieve the attribute's value from the
<code>attributes</code> collection.</p>
<p>The name "self" (<i>since Ant 1.6.3</i>) is a pre-defined reference to the script def task instance.
It can be used for logging purposes</p>
<p>The name "project" is a pre-defined reference to the Ant Project. For
more information on writing scripts, please refer to the
<a href="script.html"><code><script></code></a> task
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">the name of the task to be created using the script</td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">language</td>
<td valign="top">The programming language the script is written in.
Must be a supported Apache BSF language</td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">The location of the script as a file, if not inline</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">uri</td>
<td valign="top">
The XML namespace uri that this definition should live in.
</td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3>Nested elements</h3>
<h4>attribute</h4>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">the name of the attribute</td>
<td valign="top" align="center">Yes</td>
</tr>
</table>
<h4>element</h4>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">the name of the nested element to be supported by the
task defined by the script</td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">classname</td>
<td valign="top">the classname of the class to be used for the nested element.
This specifies the class directly and is an alternative to specifying
the Ant type name.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">type</td>
<td valign="top">This is the name of an Ant task or type which is to
be used when this element is to be created. This is an alternative
to specifying the class name directly</td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3>Examples</h3>
<p>
The following definition creates a task which supports an attribute called
attr and two nested elements, one being a fileset and the other a path. When
executed, the resulting task logs the value of the attribute and the basedir
of the first fileset.
</p>
<pre>
<scriptdef name="scripttest" language="javascript">
<attribute name="attr1"/>
<element name="fileset" type="fileset"/>
<element name="path" type="path"/>
<![CDATA[
self.log("Hello from script");
self.log("Attribute attr1 = " + attributes.get("attr1"));
self.log("First fileset basedir = "
+ elements.get("fileset").get(0).getDir(project));
]]>
</scriptdef>
<scripttest attr1="test">
<path>
<pathelement location="src"/>
</path>
<fileset dir="src"/>
<fileset dir="main"/>
</scripttest>
</pre>
<p>
The following variation on the above script lists the number of fileset elements
and iterates through them
</p>
<pre>
<scriptdef name="scripttest2" language="javascript">
<element name="fileset" type="fileset"/>
<![CDATA[
filesets = elements.get("fileset");
self.log("Number of filesets = " + filesets.size());
for (i = 0; i < filesets.size(); ++i) {
self.log("fileset " + i + " basedir = "
+ filesets.get(i).getDir(project));
}
]]>
</scriptdef>
<scripttest2>
<fileset dir="src"/>
<fileset dir="main"/>
</scripttest2>
</pre>
<p>
When a script has a syntax error, the scriptdef name will be listed in the
error. For example in the above script, removing the closing curly bracket
would result in this error
</p>
<p><code>build.xml:15: SyntaxError: missing } in compound
statement (scriptdef <code><scripttest2></code>; line 10)</code></p>
<p>
Script errors are only detected when a script task is actually executed.
</p>
<hr>
<p align="center">Copyright © 2000-2005 The Apache Software Foundation. All rights
Reserved.</p>
</body>
</html>