[guide] $list:

The $list: value uri lets you extract elements from and information about list based data objects like the AntX <strings> type. You can also use this uri to get at items stored in a comma-delimited string or any data type based on the Java List interface. This uri is most useful when you need to dynamically construct a task from client-supplied inputs. In particular, when you need to translate simple string lists into task-specific sub-components. You must explicitly install this value uri’s handler; read the Examples section to see how this is done.

Parameters

The general form of the uri is: $list:listref[?[values|size|dump|index][,,delim]] where listref is either a reference to an existing list friendly data object or an inlined comma-delimited list. You can also specify one of three explicit operations or pass in the index of the element to return. dump prints whatever the object’s toString method produces; size returns the number of elements in the list; and values returns delimited string of the list’s values. The delim option is only relevant to the values operation; when specified the handler uses it to separate the items in the returned string. If you do not specify either an index or an operation, $list: defaults to the dump operation.

Examples

1) The following snippet declares the default scheme name for the list value uri handler: $list:. This is usually done by an “init” target or at the project’s top level.

    <manageuris action="install">
        <parameter name="list"
            value="com.idaremedia.antx.valueuri.info.ListFriendlyValueURIHandler"/>
    </manageuris>

2) The following snippet converts the contents of a list jvm.args passed to the macrodef run-programmertests into the specific sub-component <jvmarg> of the <junit> task.

    <macrodef name="run-programmertests">
       <attribute name="jvm.args" default=""/>
       ...
          <foreach i="arg" in="0,${$list:@{jvm.args}?size}" mode="local">
             <altertask name="junitrunner" resolveproperties="yes">
                <jvmarg value="${$list:@{jvm.args}?@(arg)}"/>
             </altertask>
          </foreach>
          <performtask name="junitrunner"/>
       ...
      </macrodef>

3) The following snippet is a debug helper dumpset that dumps the current results of a <fileset> or <dirset> type to the Ant console. First the macro converts the results of the set operation into a List-based structure then it dumps the contents of the list to the console.

    <macrodef name="dumpset">
       <attribute name="set"/>
       <sequential>
          <listconvert from="@{set}" to="dumpsetresults"/>
          <echo>
            ${$list:dumpsetresults?dump}
          </echo>
       </sequential>
      </macrodef>

Related Topics

• ListFriendlyValueURIHandler implements the $list: uri handler.
• The $zero: uri lets you check a list to see if it’s empty.
• The $map: uri lets you manipulate a Map-based structure like $list: manipulates a List-based one.