Calendar File and Date Formats (zsh)

### 23.2 File and Date Formats ¶

#### 23.2.1 Calendar File Format ¶

The calendar file is by default `~/calendar`. This can be configured by the `calendar-file` style, see Styles. The basic format consists of a series of separate lines, with no indentation, each including a date and time specification followed by a description of the event.

Various enhancements to this format are supported, based on the syntax of Emacs calendar mode. An indented line indicates a continuation line that continues the description of the event from the preceding line (note the date may not be continued in this way). An initial ampersand (`&`) is ignored for compatibility.

An indented line on which the first non-whitespace character is `#` is not displayed with the calendar entry, but is still scanned for information. This can be used to hide information useful to the calendar system but not to the user, such as the unique identifier used by `calendar_add`.

The Emacs extension that a date with no description may refer to a number of succeeding events at different times is not supported.

Unless the `done-file` style has been altered, any events which have been processed are appended to the file with the same name as the calendar file with the suffix `.done`, hence `~/calendar.done` by default.

An example is shown below.

#### 23.2.2 Date Format ¶

The format of the date and time is designed to allow flexibility without admitting ambiguity. (The words ‘date’ and ‘time’ are both used in the documentation below; except where specifically noted this implies a string that may include both a date and a time specification.) Note that there is no localization support; month and day names must be in English and separator characters are fixed. Matching is case insensitive, and only the first three letters of the names are significant, although as a special case a form beginning "month" does not match "Monday". Furthermore, time zones are not handled; all times are assumed to be local.

It is recommended that, rather than exploring the intricacies of the system, users find a date format that is natural to them and stick to it. This will avoid unexpected effects. Various key facts should be noted.

- In particular, note the confusion between month`/`day`/`year and day`/`month`/`year when the month is numeric; these formats should be avoided if at all possible. Many alternatives are available.
- The year must be given in full to avoid confusion, and only years from 1900 to 2099 inclusive are matched.

The following give some obvious examples; users finding here a format they like and not subject to vagaries of style may skip the full description. As dates and times are matched separately (even though the time may be embedded in the date), any date format may be mixed with any format for the time of day provide the separators are clear (whitespace, colons, commas).

    2007/04/03 13:13
    2007/04/03:13:13
    2007/04/03 1:13 pm
    3rd April 2007, 13:13
    April 3rd 2007 1:13 p.m.
    Apr 3, 2007 13:13
    Tue Apr 03 13:13:00 2007
    13:13 2007/apr/3

More detailed rules follow.

Times are parsed and extracted before dates. They must use colons to separate hours and minutes, though a dot is allowed before seconds if they are present. This limits time formats to the following:

- HH`:`MM[`:`SS[`.`FFFFF]] [`am`|`pm`|`a.m.`|`p.m.`]
- HH`:`MM`.`SS[`.`FFFFF] [`am`|`pm`|`a.m.`|`p.m.`]

Here, square brackets indicate optional elements, possibly with alternatives. Fractions of a second are recognised but ignored. For absolute times (the normal format require by the `calendar` file and the `age`, `before` and `after` functions) a date is mandatory but a time of day is not; the time returned is at the start of the date. One variation is allowed: if `a.m.` or `p.m.` or one of their variants is present, an hour without a minute is allowed, e.g. `3 p.m.`.

Time zones are not handled, though if one is matched following a time specification it will be removed to allow a surrounding date to be parsed. This only happens if the format of the timezone is not too unusual. The following are examples of forms that are understood:

    +0100
    GMT
    GMT-7
    CET+1CDT

Any part of the timezone that is not numeric must have exactly three capital letters in the name.

Dates suffer from the ambiguity between DD`/`MM`/`YYYY and MM`/`DD`/`YYYY. It is recommended this form is avoided with purely numeric dates, but use of ordinals, eg. `3rd/04/2007`, will resolve the ambiguity as the ordinal is always parsed as the day of the month. Years must be four digits (and the first two must be `19` or `20`); `03/04/08` is not recognised. Other numbers may have leading zeroes, but they are not required. The following are handled:

- YYYY`/`MM`/`DD
- YYYY`-`MM`-`DD
- YYYY`/`MNM`/`DD
- YYYY`-`MNM`-`DD
- DD[`th`|`st`|`rd`] MNM[`,`] [ YYYY ]
- MNM DD[`th`|`st`|`rd`][`,`] [ YYYY ]
- DD[`th`|`st`|`rd`]`/`MM[`,`] YYYY
- DD[`th`|`st`|`rd`]`/`MM`/`YYYY
- MM`/`DD[`th`|`st`|`rd`][`,`] YYYY
- MM`/`DD[`th`|`st`|`rd`]`/`YYYY

Here, MNM is at least the first three letters of a month name, matched case-insensitively. The remainder of the month name may appear but its contents are irrelevant, so janissary, febrile, martial, apricot, maybe, junta, etc. are happily handled.

Where the year is shown as optional, the current year is assumed. There are only two such cases, the form `Jun 20` or `14 September` (the only two commonly occurring forms, apart from a "the" in some forms of English, which isn’t currently supported). Such dates will of course become ambiguous in the future, so should ideally be avoided.

Times may follow dates with a colon, e.g. `1965/07/12:09:45`; this is in order to provide a format with no whitespace. A comma and whitespace are allowed, e.g. `1965/07/12, 09:45`. Currently the order of these separators is not checked, so illogical formats such as `1965/07/12, : ,09:45` will also be matched. For simplicity such variations are not shown in the list above. Otherwise, a time is only recognised as being associated with a date if there is only whitespace in between, or if the time was embedded in the date.

Days of the week are not normally scanned, but will be ignored if they occur at the start of the date pattern only. However, in contexts where it is useful to specify dates relative to today, days of the week with no other date specification may be given. The day is assumed to be either today or within the past week. Likewise, the words `yesterday`, `today` and `tomorrow` are handled. All matches are case-insensitive. Hence if today is Monday, then `Sunday` is equivalent to `yesterday`, `Monday` is equivalent to `today`, but `Tuesday` gives a date six days ago. This is not generally useful within the calendar file. Dates in this format may be combined with a time specification; for example `Tomorrow, 8 p.m.`.

For example, the standard date format:

    Fri Aug 18 17:00:48 BST 2006

is handled by matching HH`:`MM`:`SS and removing it together with the matched (but unused) time zone. This leaves the following:

    Fri Aug 18 2006

`Fri` is ignored and the rest is matched according to the standard rules.

#### 23.2.3 Relative Time Format ¶

In certain places relative times are handled. Here, a date is not allowed; instead a combination of various supported periods are allowed, together with an optional time. The periods must be in order from most to least significant.

In some cases, a more accurate calculation is possible when there is an anchor date: offsets of months or years pick the correct day, rather than being rounded, and it is possible to pick a particular day in a month as ‘(1st Friday)’, etc., as described in more detail below.

Anchors are available in the following cases. If one or two times are passed to the function `calendar`, the start time acts an anchor for the end time when the end time is relative (even if the start time is implicit). When examining calendar files, the scheduled event being examined anchors the warning time when it is given explicitly by means of the `WARN` keyword; likewise, the scheduled event anchors a repetition period when given by the `RPT` keyword, so that specifications such as `RPT 2 months, 3rd Thursday` are handled properly. Finally, the `-R` argument to `calendar_scandate` directly provides an anchor for relative calculations.

The periods handled, with possible abbreviations are:

Years

  `years`, `yrs`, `ys`, `year`, `yr`, `y`, `yearly`. A year is 365.25 days unless there is an anchor.

Months

  `months`, `mons`, `mnths`, `mths`, `month`, `mon`, `mnth`, `mth`, `monthly`. Note that `m`, `ms`, `mn`, `mns` are ambiguous and are not handled. A month is a period of 30 days rather than a calendar month unless there is an anchor.

Weeks

  `weeks`, `wks`, `ws`, `week`, `wk`, `w`, `weekly`

Days

  `days`, `dys`, `ds`, `day`, `dy`, `d`, `daily`

Hours

  `hours`, `hrs`, `hs`, `hour`, `hr`, `h`, `hourly`

Minutes

  `minutes`, `mins`, `minute`, `min`, but not `m`, `ms`, `mn` or `mns`

Seconds

  `seconds`, `secs`, `ss`, `second`, `sec`, `s`

Spaces between the numbers are optional, but are required between items, although a comma may be used (with or without spaces).

The forms `yearly` to `hourly` allow the number to be omitted; it is assumed to be 1. For example, `1 d` and `daily` are equivalent. Note that using those forms with plurals is confusing; `2 yearly` is the same as `2 years`, not twice yearly, so it is recommended they only be used without numbers.

When an anchor time is present, there is an extension to handle regular events in the form of the nth someday of the month. Such a specification must occur immediately after any year and month specification, but before any time of day, and must be in the form n(`th`|`st`|`rd`) day, for example `1st Tuesday` or `3rd Monday`. As in other places, days are matched case insensitively, must be in English, and only the first three letters are significant except that a form beginning ‘month’ does not match ‘Monday’. No attempt is made to sanitize the resulting date; attempts to squeeze too many occurrences into a month will push the day into the next month (but in the obvious fashion, retaining the correct day of the week).

Here are some examples:

    30 years 3 months 4 days 3:42:41
    14 days 5 hours
    Monthly, 3rd Thursday
    4d,10hr

#### 23.2.4 Example ¶

Here is an example calendar file. It uses a consistent date format, as recommended above.

    Feb 1, 2006 14:30 Pointless bureaucratic meeting
    Mar 27, 2006 11:00 Mutual recrimination and finger pointing
      Bring water pistol and waterproofs
    Mar 31, 2006 14:00 Very serious managerial pontification
      # UID 12C7878A9A50
    Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
    May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday

The second entry has a continuation line. The third entry has a continuation line that will not be shown when the entry is displayed, but the unique identifier will be used by the `calendar_add` function when updating the event. The fourth entry will produce a warning 30 minutes before the event (to allow you to equip yourself appropriately). The fifth entry repeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the same time.