1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
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>
|
