You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

scriptdef.html 6.5 KiB

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