KDE PIM/KOrganizer/Holiday File Format
Contents |
KOrganizer's Holiday File Format
Using your custom holiday files
While KOrganizer and KDE PIM provide more than 40 holiday files for various regions worldwide (installed as /usr/share/apps/libkholidays/holiday_*), some countries might still be missing or you might want to add your own holidays. As the global holiday files will not be writable by an ordinary user, you can create your own user-specific holiday file(s).
To achieve this, simply create a file named
- ~/.kde/share/apps/libkholidays/holiday_something
where "something" can really be anything you like. That string after holiday_ will be displayed in korganizer's holiday region selection box in the configuration dialog. For example, I copied the Austrian holiday file /usr/share/apps/libkholidays/holiday_at to /home/reinhold/.kde/share/apps/libkholidays/holiday_Reinhold, so that KOrganizer now also offers a holiday region named "Reinhold" in the config dialog.
You can now edit that file (using the syntax defined below) to your very own needs.
Holiday file format specification
The following specification of the holiday files is taken from plan, from which we have also taken the GPL'ed parser. This specification is © Thomas Driemeyer <thomas@bitrot.de>. Some enhancement to the syntax (conditional shifts) were made by Reinhold Kainhofer <reinhold@kainhofer.com>:
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