Function Shortcuts
This section summarizes and references all of the JWare learning materials available for AntXtras’s Function Shortcuts (funcuts) feature. For developers, this information is complemented by the AntXtras Javadocs; if you cannot find the information in the pages listed below, try the associated shortcut’s Javadoc pages which is listed in the “Related Topics” section of the function shortcut’s description.
Overview
AntXtras extends the standard Ant property dereference semantics and property naming conventions with a mechanism it calls Function Shortcuts (or funcuts for short) to expose your executing environment’s fixture, utility tasks, and select Ant functions. By using the existing property dereference mechanism AntXtras is able to help you avoid verbose XML script as well as “properties debris” or “properties junk” when trying to do simple, common bits of work. Read “Function Shortcuts-- why this is useful” for a detailed explanation of function shortcuts utility.
Format
The general form or URI of a function shortcut is ${$scheme:[fragment]} where the $scheme: portion selects one of a script-controlled set of function shortcuts and the optional fragment portion defines a query specific to a request and scheme. Note that there are two dollar signs in a function shortcut’s property dereference; the first is the trigger for Ant to parse the contents of the {…} and the second identifies the property name as an AntXtras funcut. The AntXtras function shortcut mechanism is open-ended; just as you can define additions to Ant’s standard conditions, tasks, and other types, you can rename most of our funcuts or add your own to AntXtras.
Chains
You can chain function shortcuts by piping the results of the first shortcut into a second and those results into a third and so on; for example “${$property:nextfile|$basename:|$uppercase:}” converts the basename of the path defined in the ‘nextfile’ property to all uppercase. The pipe instruction is the “|” (vertical bar). Only the first shortcut can have a query portion in its fragment; subsequent shortcuts are passed a fragment that is composed of the results of the preceding shortcut and any custom query string.
Recursion
Function shortcuts work as you would expect with the AntXtras recursive property expansion mechanism. This means you can easily pass fixture elements like properties and variables in as parameter values to funcuts; for example: “${$basename:${nextfile}|$uppercase:}”.
Standard Function Shortcuts
AntXtras provides the following function shortcuts although not all of them are installed automatically when you load the core AntXtras antlib. To get every available funcut you must also install the advanced AntXtras antlib.
| Funcut Scheme(s) | General Description |
|---|---|
| $p: or $property: | Fixed shortcut.1) Extracts the named property’s current setting and supports a special dereference ‘→’ to get at items inside a <properties> or <propertyset>. You can also specify a default value if the named property is not defined. |
| $v: or $var: | Fixed shortcut.2) Extracts the named variable’s current setting. You can also specify a default value if the named variable is not defined. |
| $r: or $ref: | Fixed shortcut.3) Extracts the named reference’s current setting as a simple string. This funcut depends on the referenced object to implement a useful “to string” method. |
| $string: or $message: | Extracts a message from the current Ant fixture’s installed message resource bundles. You can also specify up to ten (10) message template parameters. |
| $x: or $fixture: | Extracts a named piece of Ant runtime information within the context of the funcut’s enclosing target. For example, you can use the $x: funcut to extract the enclosing target’s name or line number. |
| $system:, $sysenv:, $default: | Extracts the named Java System property or environment variable. Lets you gain access to the platform environment variables without having to load all of them. You can also specify a default value if the named item is not defined. |
| $osfamily:, $oslibext: etc. | Extracts various platform-specific definitions of common attributes. Useful when you need to create cross-platform or cross-version Ant scripts. |
| $password: | Extracts a password from a password file on the filesystem. Lets you create scripts that use passwords without having to load the passwords into Ant properties that can be inadvertently leaked. |
| $anytrue:, $isnumber:, $noneset:, $not:, $isfile:, etc. | Executes the named AntXtras short hand condition and reflects its results as a simple boolean string. The complete list of short hand conditions is defined in the Function Shortcuts Guide. Like inlined versions of AntXtras’s new conditions that you can use with flow control tasks. |
| $test or $criteria: | Executes the named AntXtras <tallyset> or <criteria> and reflects its results as a simple boolean string. Lets you seamlessly link taskset execution with complex execution criteria. |
| $ospath:, $uppercase:, $stripws:, $trim: etc. | Converts the fragment part of the shortcut according to the named transformation. Currently limited to a subset of the <copyproperty>’s transform parameter. |
| $now:, $datetime:, $iso:, $duration:, etc. | Converts the current system time or a passed in timestamp according to the named datetime formatter. The complete list of datetime formats is defined in the Function Shortcuts Guide. |
| $millis: | Lets you convert a human-readable duration description string to its milliseconds equivalent. For example, converts the string “5min+30sec” into “330000”. |
| $list:, $map: | Extracts information from a structured list or map data object like a <strings>, <properties>, or other general Ant resource collection object. Because several AntXtras tasks let you generate item collections dynamically, you need a way to access such an item’s contents. |
Additional Links
- Function Shortcuts Javadocs (latest release)
Notes and Caveats
- You can load all of the AntXtras function shortcuts by loading a single antlib file. Alternatively, you can load only the function shortcuts you want. You can also install and uninstall a funcut at any time– you do not have to manage them collectively. All of these methods are described in “How do I enable or disable function shortcuts?”
To get your function shortcuts interpreted, you must install the AntXtras custom property resolver using the <managefuncuts> administrator task. This task is normally called by the AntXtras install antlib; however, because child projects do not automatically inherit their parent’s property resolvers, you must call <managefuncuts> to explicitly activate function shortcuts in child projects. You do not have to reinstall each shortcut, you only need to activate processing.
- Because all function shortcuts are embedded as part of standard property references, if they fail, the enclosing property dereference acts as if the property does not exist. In other words, the result of the property is the shortcut’s URI string itself (just like regular missing properties). You can force some function shortcuts to signal a build error if they are unable to process a fragment; see each shortcut’s javadocs for more information.
- You can pipe the results of one function shortcut into another by using a “|” (vertical bar) delimiter between funcut scheme markers like: “${$var:filelist|$stripws:|$uppercase:}”. Only the first shortcut can have a query portion in its fragment; subsequent shortcuts are passed a fragment that is composed of the results of the preceding shortcut and any custom query string. If any funcut returns
nullthe entire evaluation is aborted (as if the property reference is missing).
- When you supply multiple arguments in a shortcut, you must separate the arguments using two commas like “,,”. Not terribly beautiful but effective nonetheless; for instance, “${$message:LF.started.run?${$iso:},,${testname},,${$v:status}}” will return the resource bundle message ‘LF.started.run’ expanded with substitution for first three arguments. See each function shortcut’s description for details about the specific arguments it supports (if any).
- Function shortcuts and recursive property expansion are implemented by the same custom AntXtras property resolver. You cannot disable funcuts and keep recursive property expansion turned on. One way you can get the effect of having disabled funcuts is to uninstall all of the standard funcuts while enabling the resolver itself. So although the custom resolver is installed, there will be no funcuts installed for it to resolve to. Read “How do I enable or disable function shortcuts?.”