source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual/manual/OptionalTasks/scriptdef.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 11.0 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Scriptdef Task</title>
23</head>
24
25<body>
26
27<h2><a name="script">Scriptdef</a></h2>
28<h3>Description</h3>
29<p>Scriptdef can be used to define an Ant task using a scripting language. Ant
30scripting languages supported by
31<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a>
32or
33 <a href="https://scripting.dev.java.net">JSR 223</a>
34may be
35used to define the script. Scriptdef provides a mechanism to encapsulate
36control logic from a build within an Ant task minimizing the need for
37providing control style tasks in Ant itself. Complex logic can be made
38available while retaining the simple structure of an Ant build file. Scriptdef
39is also useful for prototyping new custom tasks. Certainly as the complexity
40of the script increases it would be better to migrate the task definition
41into a Java based custom task.
42</p>
43
44<p><b>Note:</b> This task depends on external libraries not included in the
45Ant distribution. See
46<a href="../install.html#librarydependencies">Library Dependencies</a>
47for more information.</p>
48
49
50
51<p>The attributes and nested elements supported by the task may be defined
52using <code>&lt;attribute&gt;</code> and <code>&lt;element&gt;</code> nested elements. These are
53available to the script that implements the task as two collection style
54script variables <code>attributes</code> and <code>elements</code>. The
55elements in the <code>attributes</code> collection may be accessed by the
56attribute name. The <code>elements</code> collection is accessed by the nested
57element name. This will return a list of all instances of the nested element.
58The instances in this list may be accessed by an integer index.
59</p>
60
61<p><b>Note:</b> Ant will turn all attribute and element names into all
62lowercase names, so even if you use name="SomeAttribute", you'll have
63to use "someattribute" to retrieve the attribute's value from the
64<code>attributes</code> collection.</p>
65
66<p>The name "self" (<i>since Ant 1.6.3</i>) is a pre-defined reference to the
67 script def task instance.
68 It can be used for logging, or for integration with the rest of
69 ant. the <code>self.text attribute</code> contains
70 any nested text passed to the script</p>
71
72<p>If an attribute or element is not passed in,
73then <code>attributes.get()</code> or <code>elements.get()</code> will
74return null. It is up to the script to perform any checks and validation.
75<code>self.fail(String message)</code>can be used to raise a
76<code>BuildException</code>.
77</p>
78
79
80<p>The name "project" is a pre-defined reference to the Ant Project. For
81more information on writing scripts, please refer to the
82<a href="script.html"><code>&lt;script&gt;</code></a> task
83</p>
84
85
86<h3>Parameters</h3>
87<table border="1" cellpadding="2" cellspacing="0">
88 <tr>
89 <td valign="top"><b>Attribute</b></td>
90 <td valign="top"><b>Description</b></td>
91 <td align="center" valign="top"><b>Required</b></td>
92 </tr>
93 <tr>
94 <td valign="top">name</td>
95 <td valign="top">the name of the task to be created using the script</td>
96 <td valign="top" align="center">Yes</td>
97 </tr>
98 <tr>
99 <td valign="top">language</td>
100 <td valign="top">The programming language the script is written in.
101 Must be a supported Apache BSF or JSR 223 language</td>
102 <td valign="top" align="center">Yes</td>
103 </tr>
104 <tr>
105 <td valign="top">manager</td>
106 <td valign="top">
107 The script engine manager to use.
108 See the <a href="../OptionalTasks/script.html">script</a> task
109 for using this attribute.
110 </td>
111 <td valign="top" align="center">No - default is "auto"</td>
112 </tr>
113 <tr>
114 <td valign="top">src</td>
115 <td valign="top">The location of the script as a file, if not inline</td>
116 <td valign="top" align="center">No</td>
117 </tr>
118 <tr>
119 <td valign="top">uri</td>
120 <td valign="top">
121 The XML namespace uri that this definition should live in.
122 </td>
123 <td valign="top" align="center">No</td>
124 </tr>
125 <tr>
126 <td valign="top">classpath</td>
127 <td valign="top">
128 The classpath to pass into the script.
129 </td>
130 <td align="center" valign="top">No</td>
131 </tr>
132 <tr>
133 <td valign="top">classpathref</td>
134 <td valign="top">The classpath to use, given as a
135 <a href="../using.html#references">reference</a> to a path defined elsewhere.
136 <td align="center" valign="top">No</td>
137 </tr>
138 <tr>
139 <td valign="top">loaderRef</td>
140 <td valign="top">the name of the loader that is
141 used to load the script, constructed from the specified
142 classpath. This allows multiple script defintions
143 to reuse the same class loader.
144 </td>
145 <td align="center" valign="top">No</td>
146 </tr>
147 </table>
148
149<h3>Nested elements</h3>
150<h4>attribute</h4>
151<table border="1" cellpadding="2" cellspacing="0">
152 <tr>
153 <td valign="top"><b>Attribute</b></td>
154 <td valign="top"><b>Description</b></td>
155 <td align="center" valign="top"><b>Required</b></td>
156 </tr>
157 <tr>
158 <td valign="top">name</td>
159 <td valign="top">the name of the attribute</td>
160 <td valign="top" align="center">Yes</td>
161 </tr>
162</table>
163
164<h4>element</h4>
165<table border="1" cellpadding="2" cellspacing="0">
166 <tr>
167 <td valign="top"><b>Attribute</b></td>
168 <td valign="top"><b>Description</b></td>
169 <td align="center" valign="top"><b>Required</b></td>
170 </tr>
171 <tr>
172 <td valign="top">name</td>
173 <td valign="top">the name of the nested element to be supported by the
174 task defined by the script</td>
175 <td valign="top" align="center">Yes</td>
176 </tr>
177 <tr>
178 <td valign="top">classname</td>
179 <td valign="top">the classname of the class to be used for the nested element.
180 This specifies the class directly and is an alternative to specifying
181 the Ant type name.</td>
182 <td valign="top" align="center">No</td>
183 </tr>
184 <tr>
185 <td valign="top">type</td>
186 <td valign="top">This is the name of an Ant task or type which is to
187 be used when this element is to be created. This is an alternative
188 to specifying the class name directly. If the type is in a namespace,
189 the URI and a : must be prefixed to the type. For example
190 <code>type="antlib:example.org:newtype"</code></td>
191 <td valign="top" align="center">No</td>
192 </tr>
193</table>
194
195 <h4>classpath</h4>
196 <p>
197 See the <a href="../OptionalTasks/script.html">script</a> task
198 for using this nested element.
199 </p>
200
201<h3>Examples</h3>
202
203<p>
204The following definition creates a task which supports an attribute called
205attr and two nested elements, one being a fileset and the other a path. When
206executed, the resulting task logs the value of the attribute and the basedir
207of the first fileset.
208</p>
209
210<pre>
211 &lt;scriptdef name=&quot;scripttest&quot; language=&quot;javascript&quot;&gt;
212 &lt;attribute name=&quot;attr1&quot;/&gt;
213 &lt;element name=&quot;fileset&quot; type=&quot;fileset&quot;/&gt;
214 &lt;element name=&quot;path&quot; type=&quot;path&quot;/&gt;
215 &lt;![CDATA[
216
217 self.log(&quot;Hello from script&quot;);
218 self.log(&quot;Attribute attr1 = &quot; + attributes.get(&quot;attr1&quot;));
219 self.log(&quot;First fileset basedir = &quot;
220 + elements.get(&quot;fileset&quot;).get(0).getDir(project));
221
222 ]]&gt;
223 &lt;/scriptdef&gt;
224
225 &lt;scripttest attr1=&quot;test&quot;&gt;
226 &lt;path&gt;
227 &lt;pathelement location=&quot;src&quot;/&gt;
228 &lt;/path&gt;
229 &lt;fileset dir=&quot;src&quot;/&gt;
230 &lt;fileset dir=&quot;main&quot;/&gt;
231 &lt;/scripttest&gt;
232</pre>
233
234<p>
235The following variation on the above script lists the number of fileset elements
236and iterates through them
237</p>
238<pre>
239 &lt;scriptdef name=&quot;scripttest2&quot; language=&quot;javascript&quot;&gt;
240 &lt;element name=&quot;fileset&quot; type=&quot;fileset&quot;/&gt;
241 &lt;![CDATA[
242 filesets = elements.get(&quot;fileset&quot;);
243 self.log(&quot;Number of filesets = &quot; + filesets.size());
244 for (i = 0; i &lt; filesets.size(); ++i) {
245 self.log(&quot;fileset &quot; + i + &quot; basedir = &quot;
246 + filesets.get(i).getDir(project));
247 }
248 ]]&gt;
249 &lt;/scriptdef&gt
250
251 &lt;scripttest2&gt;
252 &lt;fileset dir=&quot;src&quot;/&gt;
253 &lt;fileset dir=&quot;main&quot;/&gt;
254 &lt;/scripttest2&gt;
255</pre>
256
257<p>
258When a script has a syntax error, the scriptdef name will be listed in the
259error. For example in the above script, removing the closing curly bracket
260would result in this error
261</p>
262
263<p><code>build.xml:15: SyntaxError: missing } in compound
264statement (scriptdef <code>&lt;scripttest2&gt;</code>; line 10)</code></p>
265
266<p>
267Script errors are only detected when a script task is actually executed.
268</p>
269<p>
270 The next example does uses nested text in Jython. It also declares
271 the script in a new xml namespace, which must be used to refer to
272 the task. Declaring scripts in a new namespace guarantees that Ant will
273 not create a task of the same (namespace,localname) name pair.
274</p>
275
276<pre>
277&lt;target name="echo-task-jython"&gt;
278 &lt;scriptdef language="jython"
279 name="echo"
280 uri="http://example.org/script"&gt;
281 &lt;![CDATA[
282self.log("text: " +self.text)
283 ]]&gt;
284 &lt;/scriptdef&gt;
285&lt;/target&gt;
286
287&lt;target name="testEcho" depends="echo-task-jython"
288 xmlns:s="http://example.org/script"&gt;
289 &lt;s:echo&gt;nested text&lt;/s:echo&gt;
290&lt;/target&gt;
291</pre>
292
293The next example shows the use of &lt;classpath&gt; and
294"loaderref" to get access to the beanshell jar.
295<pre>
296 &lt;scriptdef name="b1" language="beanshell"
297 loaderref="beanshell-ref"&gt;
298 &lt;attribute name="a"/&gt;
299 &lt;classpath
300 path="${user.home}/scripting/beanshell/bsh-1.3b1.jar"/&gt;
301 self.log("attribute a is " + attributes.get("a"));
302 &lt;/scriptdef&gt;
303
304 &lt;scriptdef name="b2" language="beanshell"
305 loaderref="beanshell-ref"&gt;
306 &lt;attribute name="a2"/&gt;
307 self.log("attribute a2 is " + attributes.get("a2"));
308 &lt;/scriptdef&gt;
309
310 &lt;b1 a="this is an 'a'"/&gt;
311 &lt;b2 a2="this is an 'a2' for b2"/&gt;
312</pre>
313<h3>Testing Scripts</h3>
314
315<p>
316The easiest way to test scripts is to use the
317<a href="http://ant.apache.org/antlibs/antunit/">AntUnit</a> ant library.
318This will run all targets in a script that begin with "test" (and their dependencies). </p>
319
320
321
322
323</body>
324</html>
Note: See TracBrowser for help on using the repository browser.