diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/macrodef.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/macrodef.html | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/macrodef.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/macrodef.html new file mode 100644 index 00000000..60b30720 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/macrodef.html @@ -0,0 +1,385 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> + <title>MacroDef Task</title> + </head> + + <body> + + <h2><a name="macrodef">MacroDef</a></h2> + <h3>Description</h3> + <p> + This defines a new task using a <code><sequential></code> + nested task as a template. Nested elements <code><attribute></code> and + <code><element></code> are used to specify attributes and elements of + the new task. These get substituted into the <code><sequential></code> + task when the new task is run. + </p> + <h3>Note</h3> + <p> + You can also use <i>prior defined</i> attributes for default-values in + other attributes. See the examples. + </p> + <p> + <em>since Apache Ant 1.6</em> + </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 new definition.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">uri</td> + <td valign="top"> + The uri that this definition should live in. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">description</td> + <td valign="top">A description of the macrodef + (for documentation purposes only). + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">backtrace</td> + <td valign="top"> + This controls the error traceback if there is an + error detected when running the macro. If this is + set to true, there will be an error trackback, if false + there will not be one. <em>Since Ant 1.7</em>. + </td> + <td valign="top" align="center">No; default <em>true</em></td> + </tr> + </table> + <h3>Parameters specified as nested elements</h3> + <h4>attribute</h4> + <p> + This is used to specify attributes of the new task. The values + of the attributes get substituted into the templated task. + The attributes will be required attributes unless a default + value has been set. + </p> + <p> + This attribute is placed in the body of the templated + task using a notation similar to the ant property notation + - @{attribute name}. (May be remembered as "put the substitution + AT this location"). + </p> + <p> + The escape sequence @@ is used to escape @. This allows @{x} to be + placed in the text without substitution of x by using @@{x}. + This corresponds to the $$ escape sequence for properties. + </p> + <p> + The case of the attribute is ignored, so @{myAttribute} is treated the + same as @{MyAttribute}. + </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 new attribute</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">default</td> + <td valign="top"> + The default value of the attribute. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">description</td> + <td valign="top"> + This contains a description of the attribute. + <em>since ant 1.6.1</em> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">doubleexpanding</td> + <td valign="top"> + Controls whether or not property references in the attribute are expanded twice or just once. + See the <a href="http://ant.apache.org/faq.html#macrodef-property-expansion">FAQ</a> for details. + <em>since Ant 1.8.3</em> + </td> + <td valign="top" align="center">No; default true</td> + </tr> + </table> + <h4>element</h4> + <p> + This is used to specify nested elements of the new task. + The contents of the nested elements of the task instance + are placed in the templated task at the tag name. + </p> + <p> + The case of the element name is ignored. + </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 element</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">optional</td> + <td valign="top"> + If true this nested element is optional. Default is + false - i.e the nested element is required in + the new task. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">implicit</td> + <td valign="top"> + If true this nested element is implicit. This means that + any nested elements of the macrodef instance will be placed + in the element indicated by the name of this element. + There can only be one element if an element is implicit. + The default value is false. <em>since ant 1.6.2</em> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">description</td> + <td valign="top"> + This contains a description + informing the user what the contents of the element are expected to be. + <em>since ant 1.6.1</em> + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + <h4>text</h4> + <p> + This is used to specify the treatment of text contents of the macro invocation. + If this element is not present, then any nested text in the macro invocation + will be an error. If the text element is present, then the name + becomes an attribute that gets set to the nested text of the macro invocation. + <em>Since ant 1.6.1.</em> + </p> + <p> + The case of the text name is ignored. + </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 text attribute</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">optional</td> + <td valign="top"> + If true nested text in the macro is optional, default is "false". + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">trim</td> + <td valign="top"> + If true, the nested text is trimmed of white space, + default is "false". + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">description</td> + <td valign="top"> + This contains a description + informing the user what the nested text of the macro is expected + to be. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <h3>Examples</h3> + <p> + The following example defined a task called testing and + runs it. + </p> + <blockquote> +<pre class=code> +<macrodef name="testing"> + <attribute name="v" default="NOT SET"/> + <element name="some-tasks" optional="yes"/> + <sequential> + <echo>v is @{v}</echo> + <some-tasks/> + </sequential> +</macrodef> + +<testing v="This is v"> + <some-tasks> + <echo>this is a test</echo> + </some-tasks> +</testing> +</pre> + </blockquote> + <p> + The following fragment defines a task called <code><call-cc></code> which + take the attributes "target", "link" and "target.dir" and the + nested element "cc-elements". The body of the task + uses the <code><cc></code> task from the + <a href="http://ant-contrib.sourceforge.net/">ant-contrib</a> project. + </p> + <blockquote> +<pre class="code"> +<macrodef name="call-cc"> + <attribute name="target"/> + <attribute name="link"/> + <attribute name="target.dir"/> + <element name="cc-elements"/> + <sequential> + <mkdir dir="${obj.dir}/@{target}"/> + <mkdir dir="@{target.dir}"/> + <cc link="@{link}" objdir="${obj.dir}/@{target}" + outfile="@{target.dir}/@{target}"> + <compiler refid="compiler.options"/> + <cc-elements/> + </cc> + </sequential> +</macrodef> +</pre> + </blockquote> + <p> + This then can be used as follows: + </p> + <blockquote> +<pre class="code"> +<call-cc target="unittests" link="executable" + target.dir="${build.bin.dir}"> + <cc-elements> + <includepath location="${gen.dir}"/> + <includepath location="test"/> + <fileset dir="test/unittest" includes = "**/*.cpp"/> + <fileset dir="${gen.dir}" includes = "*.cpp"/> + <linker refid="linker-libs"/> + </cc-elements> +</call-cc> +</pre> + </blockquote> + <p> + The following fragment shows <call-cc>, but this time + using an implicit element and with the link and target.dir arguments + having default values. + </p> + <blockquote> +<pre class="code"> +<macrodef name="call-cc"> + <attribute name="target"/> + <attribute name="link" default="executable"/> + <attribute name="target.dir" default="${build.bin.dir}"/> + <element name="cc-elements" implicit="yes"/> + <sequential> + <mkdir dir="${obj.dir}/@{target}"/> + <mkdir dir="@{target.dir}"/> + <cc link="@{link}" objdir="${obj.dir}/@{target}" + outfile="@{target.dir}/@{target}"> + <compiler refid="compiler.options"/> + <cc-elements/> + </cc> + </sequential> +</macrodef> +</pre> + </blockquote> + <p> + This then can be used as follows, note that <cc-elements> + is not specified. + </p> + <blockquote> +<pre class="code"> +<call-cc target="unittests"> + <includepath location="${gen.dir}"/> + <includepath location="test"/> + <fileset dir="test/unittest" includes = "**/*.cpp"/> + <fileset dir="${gen.dir}" includes = "*.cpp"/> + <linker refid="linker-libs"/> +</call-cc> +</pre> + </blockquote> + <p> + The following shows the use of the <code>text</code> element. + </p> + <blockquote> +<pre class="code"> +<macrodef name="echotest"> + <text name="text"/> + <sequential> + <echo>@{text}</echo> + </sequential> +</macrodef> +<echotest> + Hello world +</echotest> +</pre> + </blockquote> + <p> + The following uses a prior defined attribute for setting the + default value of another. The output would be + <tt>one=test two=test</tt>. If you change the order of lines + *1 and *2 the output would be <tt>one=test two=@{one}</tt>, + because while processing the <i>two</i>-line the value for + <i>one</i> is not set. + </p> + <blockquote> +<pre class="code"> +<macrodef name="test"> + <attribute name="one"/> <b>*1</b> + <attribute name="two" default="@{one}"/> <b>*2</b> + <sequential> + <echo>one=@{one} two=@{two}</echo> + </sequential> +</macrodef> +<test one="test"/> +</pre> + </blockquote> + + +</body> +</html> |