$map:

   The $map: function shortcut lets you extract elements from, and information about, map based data objects like the AntXtras <properties> type and the standard Ant <propertyset>. You can also use this funcut to get at items stored in a semicolon-delimited key/value pair string or any data type based on the Java Properties type. The $map: funcut is a query only feature– you cannot use it to modify an existing data object.

The $map: 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 see how this is done.

The general form of the function shortcut is: $map:mapref[?[keys|values|size|dump|<itemkey>][,,arg1]] where mapref is a reference to an existing Properties data object. You can specify one of four explicit operations or pass in the name of the element whose value the funcut should return.

The dump operation prints whatever the object’s Java ‘toString’ method produces; the size (or len) operation returns the number of key-value pairs in the map; the keys operation returns a delimited string of the map’s keys; and the values operation returns a delimited string of the map’s values. You can use the arg1 option to specify a delimiter other than a comma for the values and keys operations.

If you do not specify one of the four explicit operations, $map: assumes the value is the key of the element to return. If no key or operation is defined, $map: assumes the dump operation.

The following snippet explicitly declares the map function shortcut and links it to the ‘$map:’ 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="map"
3:     value="${ojaf}.collection.MapFunctionShortcut"/>
4: </oja:managefuncuts>

The following snippet converts the contents of a property map ‘testproperties’ passed to the macrodef “run-programmertests” into the specific sub-component <sysproperty> of the <junit> task. The detailed junit task creation and execute steps are omitted to emphasize the use of the $map: funcut.

 1: <macrodef name="run-programmertests">
 2:   <attribute name="sysenv" default=""/>
 3:   ...
 4:     <doforeach i="key" list="${$map:@{sysenv}?keys}">
 5:       <altertask name="junitrunner" ...>
 6:         <sysproperty key="${key}" value="${$map:@{sysenv}?${key}}"/>
 7:       </altertask>
 8:     </doforeach>
 9:    ...
10: </macrodef>

The following snippet defines a utility macro “dumpmap” that dumps the current results of any properties type, such as a <propertyset>, a <parameters>, or a <properties>, to the Ant console.

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

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