Scriptdef

Scriptdef

Description

Scriptdef can be used to define an Apache Ant task using a scripting language. Antscripting languages supported byApache BSF or JSR 223may beused to define the script. Scriptdef provides a mechanism to encapsulatecontrol logic from a build within an Ant task minimizing the need forproviding control style tasks in Ant itself. Complex logic can be madeavailable while retaining the simple structure of an Ant build file. Scriptdefis also useful for prototyping new custom tasks. Certainly as the complexityof the script increases it would be better to migrate the task definitioninto a Java based custom task.

Note: This task depends on external libraries not included in theAnt distribution. SeeLibrary Dependenciesfor more information.

The attributes and nested elements supported by the task may be definedusing <attribute> and <element> nested elements. These areavailable to the script that implements the task as two collection stylescript variables attributes and elements. Theelements in the attributes collection may be accessed by theattribute name. The elements collection is accessed by the nestedelement 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.

Note: Ant will turn all attribute and element names into alllowercase names, so even if you use name="SomeAttribute", you'll haveto use "someattribute" to retrieve the attribute's value from theattributes collection.

The name "self" (since Ant 1.6.3) is a pre-defined reference to the script def task instance. It can be used for logging, or for integration with the rest of ant. the self.text attribute contains any nested text passed to the script

If an attribute or element is not passed in, then attributes.get() or elements.get() will return null. It is up to the script to perform any checks and validation. self.fail(String message)can be used to raise a BuildException.

The name "project" is a pre-defined reference to the Ant Project. Formore information on writing scripts, please refer to the<script> task

Parameters

Nested elements

attribute

element

classpath

See the script task for using this nested element.

Examples

The following definition creates a task which supports an attribute calledattr and two nested elements, one being a fileset and the other a path. Whenexecuted, the resulting task logs the value of the attribute and the basedirof the first fileset.

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

The following variation on the above script lists the number of fileset elementsand iterates through them

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

When a script has a syntax error, the scriptdef name will be listed in theerror. For example in the above script, removing the closing curly bracketwould result in this error

build.xml:15: SyntaxError: missing } in compoundstatement (scriptdef <scripttest2>; line 10)

Script errors are only detected when a script task is actually executed.

The next example does uses nested text in Jython. It also declares the script in a new xml namespace, which must be used to refer to the task. Declaring scripts in a new namespace guarantees that Ant will not create a task of the same (namespace,localname) name pair.

<target name="echo-task-jython">  <scriptdef language="jython"  name="echo"  uri="http://example.org/script">  <![CDATA[self.log("text: " +self.text) ]]> </scriptdef></target><target name="testEcho" depends="echo-task-jython" xmlns:s="http://example.org/script">  <s:echo>nested text</s:echo></target>

 <scriptdef name="b1" language="beanshell"   loaderref="beanshell-ref">  <attribute name="a"/>  <classpath path="${user.home}/scripting/beanshell/bsh-1.3b1.jar"/>  self.log("attribute a is " + attributes.get("a")); </scriptdef> <scriptdef name="b2" language="beanshell"   loaderref="beanshell-ref">  <attribute name="a2"/>  self.log("attribute a2 is " + attributes.get("a2")); </scriptdef> <b1 a="this is an 'a'"/> <b2 a2="this is an 'a2' for b2"/>

Testing Scripts

The easiest way to test scripts is to use the AntUnit ant library.This will run all targets in a script that begin with "test" (and their dependencies).