====== $property: ======
~~SP~~~~SP~~ 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 //// is the refid of a property set data object and ////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 //// 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.
===== Parameters =====
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 and 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.
===== Examples =====
== 1) Define Fallback Values ==
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’.
== 2) As Part Of Funcut Pipeline ==
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: //.filterset// where //// 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.
…
== 3) An Open-Ended Macro ==
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).
…
…
[now use it...]
===== Related Topics =====
* The [[fc_variable|$var:]] funcut lets you read (and default) a variable.
* The [[fc_system|$system:]] funcut lets you read (and default) a System property.
~~UP~~