====== $map: ======

<hi #ffd700>~~SP~~~~SP~~</hi> 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 [[http://java.sun.com/javase/6/docs/api/java/util/Properties.html|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.

===== Parameters =====

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.


===== Examples =====

== Installing $map: shortcut ==
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.
<code xml 1>
<oja:managefuncuts action="enable">
  <parameter name="map"
    value="${ojaf}.collection.MapFunctionShortcut"/>
</oja:managefuncuts>
</code>

== Altering task parameters with maps ==
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.
<code xml 1>
<macrodef name="run-programmertests">
  <attribute name="sysenv" default=""/>
  ...
    <doforeach i="key" list="${$map:@{sysenv}?keys}"> 
      <altertask name="junitrunner" ...>
        <sysproperty key="${key}" value="${$map:@{sysenv}?${key}}"/>
      </altertask>
    </doforeach>
   ...
</macrodef>
</code>

== Showing a Map data object’s contents ==
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. 
<code xml 1>
<macrodef name="dumpmap">
  <attribute name="map"/>
  <attribute name="if" default="${$iso:}"/>
  <sequential>
    <do if="@{if}">
      <echo level="debug">
${$map:@{map}?dump}
      </echo>
    </do>
  </sequential>
</macrodef>
...
[now use it like:]
<propertyset id="testproperties" .../>
<dumpmap if="debug" map="testproperties"/>
</code>


===== Related Topics =====
  * The //latest// [[/apis/antxtras/latest/org/jwaresoftware/antxtras/funcuts/collection/MapFunctionShortcut.html|MapFunctionShortcut]] javadocs with more examples.
  * The [[fc_zero|$zero:]] funcut lets you check a map to see if it’s empty.
  * The [[fc_list|$list:]] funcut lets you manipulate a list-based structure.

~~UP~~