Calendar Declarations

To add a calendar in a Build, Dive, or cPlan file, you can add a calendar tag to the script. One reason you might want to add a calendar is to customize the formats used for a built-in calendar. For example, the format for the year-month period type of the standard calendar is "YYYY/MM", so February 2017 is displayed as 2017/02. To change the display to 2017-Feb, you can write the following calendar declaration:

calendar "modified-standard" type="standard" {
    period "year-month" format="YYYY-MMM"
  }

For example, using that declaration in a Build file:

build {
  // change the formatting of the standard calendar:
  calendar "modified-standard" type="standard" {
    period "year-month" format="YYYY-MMM"
  }
  default-calendar "modified-standard"
  text-input "data.txt" {
    // YearMo will use the format "YYYY-MMM":
    column "YearMo" type="period" period-type="year-month"
  }
  ...

Calendar declarations can also be used to create custom calendars. Here is an example of the syntax:

build {
  // create a custom fiscal calendar from the file fiscal.cbase:
  calendar "fiscal" type="custom" {
    cbase-input "fiscal.cbase"
  }
  default-calendar "fiscal"
  text-input "data.txt" {
    // YearMo will use the "year-month" period type from the "fiscal" calendar  
    column "YearMo" type="period" period-type="year-month"
  }
  ...

Calendar declarations can be used to load a calendar from an external calendar file. A calendar file is a text file whose file name extension is calendar and whose contents are a single calendar declaration. This allows you to write the calendar declaration in one place and reference it in many different scripts.  For example, if the file fiscal.calendar contains:

calendar type="offset september" {
  period "year-month" format="YYYY \\MMM"
}

A Build script can use that calendar like this:

build {
  calendar "fiscal" file="fiscal.calendar"
  default-calendar "fiscal"
  text-input "data.txt" {
    // YearMo will use the "year-month" period type from the "fiscal" calendar
    column "YearMo" type="period" period-type="year-month"
  }
  ...

You can have more than one calendar declaration in a script, but each declaration must have a unique name. For example:

build {
  // change the formatting of the standard calendar
  calendar "my-standard" type="standard" {
    period "year-month" format="YYYY-MMM"
  }
  // load a custom calendar
  calendar "my-custom" type="custom" {
    cbase-input "cal.cbase"
  }
  default-calendar "iso 8601"
  text-input "data.txt" {
    // YearWk will use the "iso 8601" calendar, which is the default
    column "YearWk" type="period" period-type="year-week"
    // To use the "my-standard" calendar you must use its name
    column "YearMo" type="period" calendar="my-standard" period-type="year-month"
    // To use the "my-custom" calendar you must use its name
    column "YearMo2" type="period" calendar="my-custom" period-type="year-month"
  }
  ...

NOTES:

  • Once declared, a calendar can be reference by columns in the Build script, as well as by add operations.
  • Calendar declarations (whether in calendar files, Build scripts, Dive scripts, or Measure Factory scripts) all use the period tag to declare a period type.
  • Type specifications (in input columns and date-rollup) all use the period-type= attribute to identify the period type that applies.

See also: