$property:

   The builtin $property: (or more commonly just $p:) function shortcut lets you extract the value of an existing script property whether that property exists as a standard Ant project property or as part of a property set. You can also use this funcut to supply a default value if the named property does not exist or is malformed (contains unresolved references). The $property: funcut is a query only feature– you cannot use it to modify existing data.

Why would you use this function shortcut when you can just use the standard Ant property deference for the named property? First, you can use this funcut to supply a default value if the named property does not exist (as in ${$p:LOGS_HOME?${out.d}/logs}). Second, you can use this funcut to read a property inside a property set using the special ‘→’ operation (as in ${$p:myargs→maxwait} where <myargs> is the refid of a property set data object and <maxwait>is a property’s name). Last, you can use this funcut as part of a funcut pipeline where the named property does not exist (or is unknown) until a particular element in the pipe is executed (as in ${$var:propertyname|$p:} where <propertyname> is a variable that contains the name of the property to be read).

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

The general form of the function shortcut is: $property:name[?default-value] where name is the name of the property to be read or a dereference selector into a property set data object.

To read a property from inside of property set object (currently only <propertyset> and <properties> are supported), the funcut name fragment should be in the form: refid→key where refid is the reference to the property set, and key is a property inside that set. Note that AntXtras will always look for a project property named name first; so if you have a standard property whose name is refid→key and a property set refid, the standard property’s value is returned— the property set is never examined.

The following snippet defines a single variable “environ” to one of the following (checked in order): the value of property ENVIRON if it is defined, the value of property MACHINE if it is defined, or the value ‘desktop’.

1: <assign var="environ" value="${$p:ENVIRON?{$p:MACHINE?desktop}}"/>

The following snippet defines a set of standard Ant filterset objects from a set of files. The name of each filterset is based on the name of the file like: <type>.filterset where <type> is the lowercased base name of the source filter file itself. The funcut pipeline makes the algorithm the script uses to determine the filterset’s name explicit and clear.

 1: <fileset id="filterfiles" dir="${conf.d}/filtersets">
 2:   <type type="file"/>
 3:   <include name="*.sources"/>
 4:   <include name="*.mf"/>
 5: </fileset>
 6: …
 7: <doforeach i="file" files="filterfiles" tryeach="yes">
 8:   <datadef name="${$p:file|$basename:|$lowercase:}.filterset" overwrite="no">
 9:     <filterset filtersfile="${file}" recurse="yes"/>
10:   </datadef>
11: </doforeach>

The following snippet uses the $property: funcut to retrieve any number of arguments from a single “pingserver” macro attribute that actually refers to a property set object. While the macro’s parameters can grow over time, its signature remains the same (and the macro uses the default feature of the $property: funcut to supply useful defaults for new parameters).

 1: <macrodef name="pingserver">
 2:   <attribute name="conf"/>
 3:   <sequential>
 4:     <assert isref="@{conf}"/>
 5:     <wl:pingserver
 6:          name="${$property:@{conf}→name}"
 7:          url="${$property:@{conf}→url?ERROR}"
 8:          maxwait="${$property:@{conf}→maxwait?${$millis:2min}}">
 9:         …
10:     </wl:pingserver>
11:     …
12: </macrodef>
13:
14: [now use it...]
15:
16: <fileset id="servers" dir="${base.d}/servers">
17:   <include name="*.properties"/>
18: </fileset>
19:
20: <doforeach i="conf" files="servers" tryeach="yes" failproperty="ping.incomplete">
21:   <datadef name="next.server" overwrite="yes" setid="yes">
22:     <properties file="${conf}"/>
23:   </datadef>
24:   <pingserver conf="next.server"/>
25:   <assign var="happy.list" op="+s" value="{${$p:next.server→name}}"/>
26: </doforeach>
27:
28: <unassign ref="next.server"/>
29:
30: <echo message="${$message:MSG.completed.pings?${$v:happy.list}}"/>
31: <stop if="ping.incomplete" messageid="ERR.ping.incomplete"/>

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