[guide] $property:

The $property: uri (also $prop:) lets you read the current value of an regular Ant property and optionally provide a default value if that property does not exist. Unlike the <prefer> task, the property handler’s defaulting mechanism creates a property only for the attribute value where it’s being used, not in the project’s property space. You can also use this handler to get at properties stored inside map structures like Ant <propertyset>s and AntX <properties>s. This uri’s handler is builtin into AntX; it is always available whenever you enable value URIs.

An important feature of this uri is its ability to chain to other $property: uris; for example, you can chain multiple property uris together to get double or triple property deferencing. The property uri also makes some value uri combinations clearer for the human reader (particularly in macrodefs where attribute syntax and the AntX value uri property syntax are similar).

Parameters

The general form of the uri is: $property:property-name[?[default]] where property-name is the property to be read and default is the default value to use if the property is undefined (this value can be the empty string). You can use the AntX value uri property reference syntax $(…) to get double property deferencing but you must chain to get more levels of dereferencing.

If the uri handler is unable to find a direct match and property-name is of the form: refid->key, the handler looks for a property key in the map object stored under refid. If either the map object or the value does not exist, the uri returns the default value.

Examples

1) The following snippet loads the configuration file indicated by the target property. If the property does not exist, the script uses “dev” as a default value.

    <assign variable="conf" value="${config}/${$property:target?dev|$lowercase:}.conf"/>
    <assert filenotempty="${$var:conf}" msg="File '${$var:conf}' exists."/>

    <property file="${$var:conf}"/>

2) The following snippet extracts the values of the two entries copyright and framesettitle from a referenced properties object labels. The reference can point to either an Ant <propertyset> or an AntX <properties> object.

    <macrodef name="mkjavadocs">
        <attribute name="labels" default="blank.labels"/>
        ...
        <datadef name="blank.labels" overwrite="no">
            <properties>
                <property name="framesettitle" value="Undefined"/>
                <property name="copyright" value="${$default:copyright}"/>
            </properties>
        </datadef>
        <javadoc ...
           windowtitle="${$property:@{labels}->framesettitle} ${ITID_DATE}">
           ...
           <bottom><![CDATA[<div align="center">${$property:@{labels}->copyright}</div>]]></bottom>
        </javadoc>
        ...
    </macrodef>

3) The following snippet defines a string list that includes patterns that optionally use a stem property. If stem is defined to “mystuff.” for example, the second pattern will be “mystuff.*.tests.*”; otherwise, it is “*.tests.*”.

    <strings id="main.coverage.filters">
        <string value="+${$prop:stem?}*"/>
        <string value="-${$prop:stem?}*.tests.*"/>
        <strings listref="thirdparty.coverage.filters"/>
    </strings>

Related Topics

• The $var: or $variable: uri lets you extract a mutable property’s current value.