Child pages
  • Dates language
Skip to end of metadata
Go to start of metadata

Dates language

An extension to the Base Language that adds support for dates.


The Dates Language provides dedicated facilities to operate with date and time. Dates creation, comparison or adding and subtracting periods are done in a natural way, using common conventions and standard operators. As the backend implementation vehicle the Joda Time library is used.


The following types are defined:

  • instant represents the number of milliseconds passed since the epoch, 1970-01-01T00:00Z. It's represented with a long. Thus an instant can be exchanged freely for a long value and vice versa.
  • datetime represents a date and time with time zone.
  • duration represents an interval of time measured in milliseconds.
  • period is a representation of a time interval defined in terms of fields: seconds, minutes, etc. A period is constructed using + (plus) operator.
  • timezone represents a time zone.

    Changes in 1.1


    Old datetime type is renamed to instant. New datetime type contains timezone information. Use in expression to convert instant to datetime.

Predefined values

A special reserved keyword now represents the current time.

A reserved keyword never represents an instant before the beginning of times. All instants are placed after never on the time axis. Its actual representation is null.

Period constant contains of a number and a property. They can be summed up together to form more complicated periods.

Time zone can be created in different ways. All predefined values are available in completion menu. default timezone is a shortcut to the computer local time zone.

Converting between types

Datetime can be obtained from an instant by providing a time zone. For reverse conversion simply get the datetime's instant property.

Period can be converted to duration using toDuration operation. It converts the period to a duration assuming a 7 day week, 24 hour day, 60 minute hour and 60 second minute.

For compatibility there are ways to convert datetime or instant types to java.util.Date and java.util.Calendar.

Reverse conversion:


Each individual datetime field can be queried using dot expression.

To replace a field, use with expression.

Each period can be re-evaluated in terms of any field (with rounding if needed) leveraging the in operator.



A period can be added to or substracted from a datetime. The result is a datetime.

Two datetimes can be subtracted, the result is a period.

A duration can be added to or subtracted from an instant. The result is an instant.

Two instants can be subtracted, the result is a duration.


Two values of the same type (instant, datetime, period or duration) can be compared using standard operators: <, >, ==, etc.

Another form of comparison can be used for datetime by adding a keyword by following the field specification. In this case values are compared rounded to the field (see #Rounding).

Minimum and maximum operations are defined for instant and datetime types.


Datetime values can be rounded to the nearest whole unit of the specified field (second, minute, hour, day, month, etc). There are several ways of rounding:

  • round returns the datetime that is closest to the original
  • round down to returns the largest datetime that does not exceed the original
  • round up to returns the smallest datetime that is not less than the original

Printing and Parsing

To print or parse datetime value we use date format describing its textual representation. The following formats are available by default:

  • defaultFormat, rssDate
  • shortDate, shortDateTime, shortTime, fullDate, longDate, etc (defined in Joda library)

Date format consists of one or more format tokens. The following kinds of tokens are supported:

  • literal (referenced with a single quote) - any text, commonly used to insert dash or space
  • datetime property (referenced with the name of a property in curly braces) - is replaced with the value of the property when printed
  • switch - composite token, which may vary the format depending on the date
  • offset (referenced as days ago, months ago, etc.) - calculates the difference between the provided datetime and the current moment
  • reference (the name in angle brackets) - a way to include existing format

Additional date formats can be introduced using the j.m.baseLanguage.dates.DateFormatsTable root concept. Each format has a name and visibility. Formats with private visibility are local for the table.

Datetime instance can be printed in the form of existing format by # operation.

Another possibility is to use {{#} operation, which allows to define format in-place.

Both printing operations accept optional locale argument in parentheses.

Parse operation accepts string, date format, timezone and two optional parameters: default value and locale.

Changes in 1.1


New print/parse expressions operate on datetime instead of instant. Use intention to convert deprecated expressions to a new ones.

Previous Next

  • No labels