source: release-kits/lirk3/bin/ant-installer/web/manual1.6.2/manual/OptionalTasks/scriptdef.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 6.6 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<title>Scriptdef Task</title>
6<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
7</head>
8
9<body>
10
11<h2><a name="script">Script</a></h2>
12<h3>Description</h3>
13<p>Scriptdef can be used to define an Ant task using a scripting language. Ant
14scripting languages supported by
15<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> may be
16used to define the script. Scriptdef provides a mechanism to encapsulate
17control logic from a build within an Ant task minimizing the need for
18proviuding control style tasks in Ant itself. Complex logic can be made
19available while retaining the simple structure of an Ant build file. Scriptdef
20is also useful for prototyping new custom tasks. Certainly as the complexity
21of the script increases it would be better to migrate the task definition
22into a Java based custom task.
23</p>
24
25<p><b>Note:</b> This task depends on external libraries not included in the
26Ant distribution. See
27<a href="../install.html#librarydependencies">Library Dependencies</a>
28for more information.</p>
29
30<p>The attributes and nested elements supported by the task may be defined
31using &lt;attribute&gt; and &lt;element&gt; nested elements. These are
32available to the script that implements the task as two collection style
33script variables <code>attributes</code> and <code>elements</code>. The
34elements in the <code>attributes</code> collection may be accessed by the
35attribute name. The <code>elements</code> collection is accessed by the nested
36element name. This will return a list of all instances of the nested element.
37The instances in this list may be accessed by an integer index.
38</p>
39
40<p><b>Note:</b> Ant will turn all attribute and element names into all
41lowercase names, so even if you use name="SomeAttribute", you'll have
42to use "someattribute" to retrieve the attribute's value from the
43<code>attributes</code> collection.</p>
44
45<p>The name "project" is a pre-defined reference to the Ant Project. For
46more information on writing scripts, please refer to the
47<a href="script.html">&lt;script&gt;</a> task
48</p>
49
50<h3>Parameters</h3>
51<table border="1" cellpadding="2" cellspacing="0">
52 <tr>
53 <td valign="top"><b>Attribute</b></td>
54 <td valign="top"><b>Description</b></td>
55 <td align="center" valign="top"><b>Required</b></td>
56 </tr>
57 <tr>
58 <td valign="top">name</td>
59 <td valign="top">the name of the task to be created using the script</td>
60 <td valign="top" align="center">Yes</td>
61 </tr>
62 <tr>
63 <td valign="top">language</td>
64 <td valign="top">The programming language the script is written in.
65 Must be a supported Apache BSF language</td>
66 <td valign="top" align="center">Yes</td>
67 </tr>
68 <tr>
69 <td valign="top">src</td>
70 <td valign="top">The location of the script as a file, if not inline</td>
71 <td valign="top" align="center">No</td>
72 </tr>
73</table>
74
75<h3>Nested elements</h3>
76<h4>attribute</h4>
77<table border="1" cellpadding="2" cellspacing="0">
78 <tr>
79 <td valign="top"><b>Attribute</b></td>
80 <td valign="top"><b>Description</b></td>
81 <td align="center" valign="top"><b>Required</b></td>
82 </tr>
83 <tr>
84 <td valign="top">name</td>
85 <td valign="top">the name of the attribute</td>
86 <td valign="top" align="center">Yes</td>
87 </tr>
88</table>
89
90<h4>element</h4>
91<table border="1" cellpadding="2" cellspacing="0">
92 <tr>
93 <td valign="top"><b>Attribute</b></td>
94 <td valign="top"><b>Description</b></td>
95 <td align="center" valign="top"><b>Required</b></td>
96 </tr>
97 <tr>
98 <td valign="top">name</td>
99 <td valign="top">the name of the nested element to be supported by the
100 task defined by the script</td>
101 <td valign="top" align="center">Yes</td>
102 </tr>
103 <tr>
104 <td valign="top">classname</td>
105 <td valign="top">the classname of the class to be used for the nested element.
106 This specifies the class directly and is an alternative to specifying
107 the Ant type name.</td>
108 <td valign="top" align="center">No</td>
109 </tr>
110 <tr>
111 <td valign="top">type</td>
112 <td valign="top">This is the name of an Ant task or type which is to
113 be used when this element is to be created. This is an alternative
114 to specifying the class name directly</td>
115 <td valign="top" align="center">No</td>
116 </tr>
117</table>
118
119
120
121<h3>Examples</h3>
122
123<p>
124The following definition creates a task which supprts an attribute called
125attr and two nested elements, one being a fileset and the other a path. When
126executed, the resulting task logs the value of the attribute and the basedir
127of the first fileset.
128</p>
129
130<pre>
131 &lt;scriptdef name=&quot;scripttest&quot; language=&quot;javascript&quot;&gt;
132 &lt;attribute name=&quot;attr1&quot;/&gt;
133 &lt;element name=&quot;fileset&quot; type=&quot;fileset&quot;/&gt;
134 &lt;element name=&quot;path&quot; type=&quot;path&quot;/&gt;
135 &lt;![CDATA[
136
137 project.log(&quot;Hello from script&quot;);
138 project.log(&quot;Attribute attr1 = &quot; + attributes.get(&quot;attr1&quot;));
139 project.log(&quot;First fileset basedir = &quot;
140 + elements.get(&quot;fileset&quot;).get(0).getDir(project));
141
142 ]]&gt;
143 &lt;/scriptdef&gt;
144
145 &lt;scripttest attr1=&quot;test&quot;&gt;
146 &lt;path&gt;
147 &lt;pathelement location=&quot;src&quot;/&gt;
148 &lt;/path&gt;
149 &lt;fileset dir=&quot;src&quot;/&gt;
150 &lt;fileset dir=&quot;main&quot;/&gt;
151 &lt;/scripttest&gt;
152</pre>
153
154<p>
155The following variation on the above script lists the number of fileset elements
156and iterates through them
157</p>
158<pre>
159 &lt;scriptdef name=&quot;scripttest2&quot; language=&quot;javascript&quot;&gt;
160 &lt;element name=&quot;fileset&quot; type=&quot;fileset&quot;/&gt;
161 &lt;![CDATA[
162 filesets = elements.get(&quot;fileset&quot;);
163 project.log(&quot;Number of filesets = &quot; + filesets.size());
164 for (i = 0; i &lt; filesets.size(); ++i) {
165 project.log(&quot;fileset &quot; + i + &quot; basedir = &quot;
166 + filesets.get(i).getDir(project));
167 }
168 ]]&gt;
169 &lt;/scriptdef&gt
170
171 &lt;scripttest2&gt;
172 &lt;fileset dir=&quot;src&quot;/&gt;
173 &lt;fileset dir=&quot;main&quot;/&gt;
174 &lt;/scripttest2&gt;
175</pre>
176
177<p>
178When a script has a syntax error, the scriptdef name will be listed in the
179error. For example in the above script, removing the closing curly bracket
180would result in this error
181</p>
182
183<p><code>build.xml:15: SyntaxError: missing } in compound
184statement (scriptdef &lt;scripttest2&gt;; line 10)</code></p>
185
186<p>
187Script errors are only detected when a script task is actually executed.
188</p>
189
190
191<hr>
192<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
193Reserved.</p>
194
195</body>
196</html>
Note: See TracBrowser for help on using the repository browser.