date-time

   The AntXtras date-time function shortcuts let you insert formatted date and time strings as attribute values without having to create project properties. The bulk of the funcuts map to a small set of predefined formats as determined by the funcut’s scheme name; however, you can also supply your own format and timestamp using the funcut’s query string. These funcuts are most useful as a substitute for <tstamp> in macrodefs that are called repeatedly from the same project.

The various date and time funcuts are automatically installed and enabled by the standard AntXtras antlib. You can also explicitly install these funcut handlers; read the Examples section to see how this is done.

The general form of a date-time function shortcut is: $formatname:[now|<timestamp>][?format-string] where formatname is one of the predefined date-time formats like “isodate” or “shorttime”. The incoming timestamp is either the symbolic name “now” for the current time or a millisecond <timestamp> value (as of January 1, 1970 UTC). You can also provide a custom format format-string as a query parameter after the '?' mark; this format string is passed verbatim to the Java SimpleDateFormat utility class.

Below is a table of the predefined format names and example generated values. To force the function shortcut to use your own format string use any name that is not in this list; for example, you could use the scheme $tstamp: for your custom format strings.

Note that the so-called strict schemes guarantee that the returned formatted date-time strings are safe to be used as file names on the most common OS filesystems (Windows-based, Unix-based, MacOSX, etc.) So, for example, strict times do not use the colon (:) as a field delimiter as that is an illegal file name character in a Windows environment.

The following snippet explicitly declares three variants of the date-time function shortcut: the standard ‘$iso:’ and ‘$duration:’ schemes, and a custom prefix ‘$tstamp:’ for adhoc formats. If you choose to activate shortcuts manually, you’ll need to do something like this at the start of your Ant script’s execution.

1: <managefuncuts action="enable">
2:   <parameter name="iso"
3:     value="${ojaf}.datetime.DateTimeFunctionShortcut"/>
4:   <parameter name="duration"
5:     value="${ojaf}.datetime.DateTimeFunctionShortcut"/>
6:   <parameter name="tstamp"
7:     value="${ojaf}.datetime.DateTimeFunctionShortcut"/>
8: </managefuncuts>

The following snippet defines two macrodefs: “tick” that prints out a timestamped status line using a builtin date-time funcut (among others), and “done” that print out a final message using a custom time format. The example also shows how you might use the macros from within a target definition.

 1: <macrodef name="tick">
 2:   <attribute name="message" default=""/>
 3:   <sequential>
 4:     <echo level="info"
 5:      message="[TICK] [${$iso:}] @{message}"/>
 6:   </sequential>
 7: </macrodef>
 8:
 9: <macrodef name="done">
10:   <sequential>
11:     <echo level="info"
12:      message="[DONE] at ${$tstamp:now?hh 'o''clock' a, zzzz}"/>
13:   </sequential>
14: </macrodef>
15: ...
16: [now use them like:]
17: <target name="deployservers">
18:   <doforeach i="server" list="${$map:servers.urls?keys}">
19:      <tick message="Deploying to ${server}"/>
20:      ...
21:   </doforeach>
22:   <done/>
23: </target>

• The latest DateTimeFunctionShortcut javadocs with more examples.
• The $equaldate:, $newerdate:, and $olderdate: funcuts let you compare two dates.