$list:

   The $list: function shortcut lets you extract elements from, and information about, list based data objects like the AntXtras <strings> type and standard Ant resource collections like <fileset>. You can also use this funcut to get at items stored in a comma-delimited string or any data type based on the Java List interface. The $list: funcut is a query only feature– you cannot use it to modify an existing data object.

The $list: funcut is also useful when you need to dynamically construct a custom instance of a task based on client-supplied inputs. For instance, you could use the $list: funcut to translate list of string parameters (as passed to a <macrodef>) into task-specific sub-components using the AntXtras <createtask> and <altertask> functions [advanced antlib].

The $list: funcut is automatically installed and enabled by the standard AntXtras antlib. You can also explicitly install this funcut’s handler; read the Examples section to learn how.

The general form of the function shortcut is: $list:listref[?[values|size|dump|concat|<index>][,,arg1]] where listref is either a reference to an existing list friendly data object or an inlined comma-delimited list of strings (surrounded by a pair of square-brackets like “[a,b,c]”). You can also specify one of four explicit operations or pass in the index of the element the funcut should return as its value.

The dump operation prints whatever the object’s Java ‘toString’ method produces; the size (or len) operation returns the number of elements in the list; the values operation returns a delimited string of the list’s values (you can use the arg1 option to specify a delimiter other than a comma); and the concat (or add) operation will concatenate the listref contained in the arg1 option to the main list and return the combined result (note that the second listref can also be an inlined comma-delimited list). None of these operations, including the concat operation, alters the original list.

If you do not specify one of these four explicit operations, $list: assumes the value is the index of the element to return. If no index or operation is defined, $list: assumes the values operation.

The following snippet explicitly declares the list function shortcut and links it to the ‘$list:’ scheme. If you choose to activate shortcuts manually, you’ll need to do something like this at the start of your Ant script’s execution.

1: <oja:managefuncuts action="enable">
2:   <parameter name="list"
3:     value="${ojaf}.collection.ListFunctionShortcut"/>
4: </oja:managefuncuts>

The following snippet converts the contents of a comma-delimited string list ‘jvm.args’ passed to the macrodef “run-programmertests” into the specific sub-component <jvmarg> of the <junit> task. The detailed junit task creation and execute steps are omitted to emphasize the use of the $list: funcut.

 1: <macrodef name="run-programmertests">
 2:   <attribute name="jvm.args" default=""/>
 3:   ...
 4:     <doforeach i="i" in="0,${$list:@{jvm.args}?size}">
 5:       <altertask name="junitrunner" ...>
 6:         <jvmarg value="${$list:@{jvm.args}?${i}}"/>
 7:       </altertask>
 8:     </doforeach>
 9:    ...
10: </macrodef>

The following snippet defines a utility macro “dumpset” that prints the current contents of any list or resource collection type, such as a <fileset>, <propertyset>, or general <resources>, to the Ant console.

 1: <macrodef name="dumpset">
 2:   <attribute name="set"/>
 3:   <attribute name="if" default="${$isomillis:}"/>
 4:   <sequential>
 5:     <do if="@{if}">
 6:       <echo level="debug">
 7: ${$list:@{set}?dump}
 8:       </echo>
 9:     </do>
10:   </sequential>
11: </macrodef>
12: ...
13: [now use it like:]
14: <fileset id="myfiles" .../>
15: <dumpset if="debug" set="myfiles"/>

• The latest ListFunctionShortcut javadocs with more examples.
• The $zero: funcut lets you check a list to see if it’s empty.
• The $map: funcut lets you manipulate a Map-based structure.