KOrganizer's Holiday File Format

~/.kde/share/apps/libkholidays/holiday_something

KOrganizer's Holiday File Format

The holiday format is: (optional parts are in [square brackets], nonterminals are in CAPS, alternatives are separated by |, everything must be entered in lower case)

   [small]  [STRINGCOLOR]  "name"  [DAYNUMBERCOLOR]
                           on  [DATE]  [OFFSET] [CONDITIONALOFFSET] [LENGTH]

(Although shown here on two lines, every holiday definition must be entered on a single line.)

Available colors are black, red, green, yellow, blue, magenta, cyan, white, and weekend (the same color used for Saturday and Sunday). Neither the string color nor the day number color is used in KOrganizer to draw UI elements. However, you can promote a day to an official holiday (where no working hours are shown) by using the "weekend" color. All holidays that do not have the weekend tag set are interpreted as special days, which are still work days.

There are several formats for DATE:

   DAY . MONTH [ . YEAR]
   MONTH / DAY [ / YEAR]
   DAY   MONTHNAME   [YEAR]
   MONTHNAME   DAY   [YEAR]
   [every   NTH]   WEEKDAY   [in   MONTH]
   WEEKDAY   before   LIT_DATE
   WEEKDAY   after   LIT_DATE
   easter
   pascha

DAY, MONTH, YEAR, NTH, and NUMBER can be C expressions; in dates, they must be parenthesized. The special values any and last are also available. Any valid DATE description specifying a single day may be converted to a NUMBER by enclosing it in square brackets []. MONTHNAME is january, february, etc; WEEKDAY is monday, tuesday, etc. NTH can alternatively be first, second, ..., fifth, last. The words on, every, day, and days are syntactic sugar without meaning. Easter is predefined because its definition is rather complicated. LIT_DATE stands for one of the first two alternatives, DAY.MONTH[.YEAR] or MONTH/DAY[/YEAR]. Pascha is the Christian Orthodox Easter.

The OFFSET after DATE is "[plus | minus NUMBER days", and the LENGTH after that is "length NUMBER days". Offsets are useful for holidays relative to Easter, and lengths are useful for trade shows and vacations. Always define vacations last in the list so regular holidays override them.

The CONDITIONALOFFSET part is used to shift a holiday that appears on a particular weekday to another weekday. In some countries, when a hoiday falls on a weekend (saturday or sunday), then the holiday is celebrated on the following monday. The syntax of the CONDITIONALOFFSET part is

SHIFT TO weekday IF weekday [ || weekday ]

Dates can be converted to numbers by enclosing them in square brackets. For example, the number of days between Easter and May 1 can be computed with ([may 1] - [easter]). As with C expressions, bracketed expressions must be parenthesized.

If you have /lib/cpp (see CPP_PATH in the Makefile), you can use #include statements to include additional external holiday files. The external files cannot be edited interactively with plan; use an editor.

Examples:

   small  "Easter"  weekend  on  easter
   small  "Surprise"  blue  on  last  sunday  in  april  plus  1  day
   small  green  "xmas"  weekend  on  12/25
   small  "May holiday" weekend on 1.5. shift to monday if saturday || sunday
   ""  weekend  on  july  4
   magenta  "Payday"  on  any/last
   green  "Vacation"  on  20.6.93  length  28  days
   #include "/usr/local/lib/vacations"

Restrictions: plus, minus, and length may not cross over to the next or previous year, you cannot define New Year's as "last/last plus 1 day".

BNF of the holiday file (generated by yacc)

    3 list: 
           | list small color STRING color entry

    4 small: /* leer */
    5      | SMALL

    6 color: /* leer */
    7      | COLOR

    8 entry: EASTER offset length
    9      | date offset conditionaloffset length
   10      | WDAY offset length
   11      | pexpr WDAY offset length
   12      | pexpr WDAY IN month offset length
   13      | WDAY pexpr date offset length

   14 offset: /* leer */
   15       | PLUS expr
   16       | MINUS expr

   17 conditionaloffset: /* leer */
   18                  | SHIFT wdaycondition IF wdaycondition

   19 wdaycondition: /* leer */
   20              | WDAY
   21              | WDAY OR wdaycondition

   22 length: /* leer */
   23       | LENGTH expr

   24 date: pexpr '.' month
   25     | pexpr '.' month '.'
   26     | pexpr '.' month '.' expr
   27     | month '/' pexpr
   28     | month '/' pexpr '/' pexpr
   29     | MONTH pexpr
   30     | MONTH pexpr pexpr
   31     | pexpr MONTH
   32     | pexpr MONTH pexpr
   33     | pexpr '.' MONTH pexpr
   34     | pexpr

   35 reldate: STRING
   36        | EASTER
   37        | pexpr '.' month
   38        | pexpr '.' month '.'
   39        | month '/' pexpr
   40        | pexpr MONTH
   41        | MONTH pexpr
   42        | WDAY pexpr pexpr
   43        | pexpr WDAY IN month

   44 month: MONTH
   45      | pexpr

   46 expr: pexpr
   47     | expr OR expr
   48     | expr AND expr
   49     | expr EQ expr
   50     | expr NE expr
   51     | expr LE expr
   52     | expr GE expr
   53     | expr LT expr
   54     | expr GT expr
   55     | expr '+' expr
   56     | expr '-' expr
   57     | expr '*' expr
   58     | expr '/' expr
   59     | expr '%' expr
   60     | expr '?' expr ':' expr
   61     | '!' expr
   62     | '[' reldate ']'

   63 pexpr: '(' expr ')'
   64      | number

   65 number: NUMBER
   66       | '-' NUMBER
   67       | CYEAR
   68       | LEAPYEAR pexpr

[ Edit ]