$reference:

   The builtin $reference: (or more commonly just $r: or $ref:) function shortcut lets you extract the contents of data object as a simple string through its project reference id. You can also use this funcut to supply a default value if the named reference is undefined or does not provide a usable string variant. The $reference: funcut is a query only feature– you cannot use it to modify existing data.

AntXtras does its best to determine what the best string representation of a named data type should be (in our case, “best” usually means a value that is re-usable from an Ant script not a loggable diagnostics string); however, there are some Ant types and third-party types that do not provide conversion functions. For these, AntXtras will use whatever the component’s implementation of the standard ‘toString’ method returns.

The $reference: funcut and its aliases $r: and $ref: are automatically installed and enabled by the standard AntXtras funcuts antlib. Because it’s built into AntXtras, you cannot uninstall the $reference: funcut like you can most other funcuts; if funcuts are enabled, you get the $reference:, $r:, and $ref: funcut handlers always.

The general form of the function shortcut is: $reference:refid[?default-value] where refid is the reference id of the object to be read and encoded as a string and default-value is the value to use if the named object does not exist. Note that if the references exists but there is an error encoding its value to a string, the shortcut returns the standard ‘toString’ result which is a reference to the Java memory object not your default string.

The following snippet uses the $ref: funcut to display the values of a patternset ‘<type>-docs.includes’ and a fileset ‘<type>-docs.files’ whose references have been passed to a macro.

1: <do iftrue=".debug.enabled">
2:   <debug message="###### FIXTURE ######"/>
3:   <debug message="${$ref:@{type}-docs.includes?UNDEFINED}"/>
4:   <debug message="${$ref:@{type}-docs.files}"/>
5:   <debug message="###### ####### ######"/>
6: </do>

The following snippet uses the $ref: funcut to read a list of modules from a named data object passed to a macro. If the named reference does not exist, the macro uses a default list “main,tests”.

 1: <macrodef name="java-modules">
 2:   <attribute name="list" default="modulelist"/>
 3:   <sequential>
 4:     <doforeach i="module" list="${$ref:@{list}?main,tests}">
 5:       <protect haltiferror="no" againstall="yes">
 6:         <java-module name="${module}" scheme="app-%{name}"/>
 7:         …
 8:       </protect>
 9:     </doforeach>
10:     …

• $reference:
• $r:
• $ref:

• The $property: funcut lets you read (and default) a property.
• The $var: funcut lets you read (and default) a variable.