kholidays/holidays/file-format.txt

0001 The file format was originally adopted from PLAN (http://www.bitrot.de/plan.html)
0002 but has since been heavily modified to add new features such as holiday categories
0003 and alternative calendar systems, or to remove unused features.
0004
0005 The file format is currently defined using Bison and Flex in the following files:
0006
0007     kholidays/src/parsers/plan2/holidayscannerplan.ypp
0008     kholidays/src/parsers/plan2/holidayscannerplan.lpp
0009
0010 (In the following definition, optional parts are in [square brackets],
0011 nonterminals are in CAPS, alternatives are separated by |, everything must be
0012 entered in lower case. In all cases defer to the defintiion in the ypp/lpp
0013 files.)
0014
0015 A holiday file consists of an optional metadata header section, followed by an
0016 optional holiday list:
0017
0018     [METADATA]
0019     [LIST]
0020
0021 The metadata can contain country code, language code, name and description:
0022
0023     [COUNTRY_CODE]
0024     [LANGUAGE_CODE]
0025     ["Name"]
0026     ["Description"]
0027
0028 The list holds 0 or more holiday definitions:
0029
0030     "Event Name" [CATEGORIES] DATE_RULE
0031
0032 Categories can be 0 or more of the following keywords:
0033
0034     public
0035     civil
0036     religious
0037     school
0038     government
0039     financial
0040     cultural
0041     commemorative
0042     historical
0043     nameday
0044     seasonal
0045
0046 The "public" category caries the extra meaning of being a day off.
0047
0048 There are several possible ways for a date rule to be defined
0049
0050     [CALENDAR] DATE [OFFSET] [LENGTH]
0051
0052 Calendar can be 0 or 1 of the following keywords:
0053
0054     gregorian
0055     julian
0056     coptic
0057     ethiopian
0058     hebrew
0059     hijri
0060     indiannational
0061     jalali
0062
0063 "gregorian" is the default value if not defined.
0064
0065 There are several formats for DATE:
0066
0067     DAY.MONTH[.YEAR]
0068     MONTH/DAY[/YEAR]
0069     DAY MONTHNAME [YEAR]
0070     MONTHNAME DAY [YEAR]
0071     [every NTH] WEEKDAY [in MONTH]
0072     WEEKDAY before LIT_DATE
0073     WEEKDAY after LIT_DATE
0074     easter
0075     pascha
0076
0077 It is recommended to always use month names where-ever possible to avoid confusion,
0078 but if a month number is used then use DAY.MONTH[.YEAR] format for consistency.
0079
0080 DAY, MONTH, YEAR, NTH, and NUMBER can be C expressions; in
0081 dates, they must be parenthesized.  The special values "any" and "last" are
0082 also available. Any valid DATE description specifying a single day may
0083 be converted to a NUMBER by enclosing it in square brackets [].
0084 NTH can alternatively be first, second, ..., fifth, last.
0085
0086 The words "on", "every", "day", and "days" are syntactic sugar without meaning.
0087 LIT_DATE stands for one of the first two alternatives, DAY.MONTH[.YEAR]
0088 or MONTH/DAY[/YEAR].
0089
0090 Dates can be converted to numbers by enclosing them in square brackets.
0091 For example, the number of days between Easter and May 1 can be
0092 computed with ([may 1] - [easter]). As with C expressions, bracketed
0093 expressions must be parenthesized.
0094
0095 The OFFSET after DATE is used to calculate a holiday date relative to another date
0096 and is defined as:
0097
0098     [plus|minus] NUMBER [days]
0099
0100 The LENGTH is used to calculate how long a holiday is and is defined as:
0101
0102     length NUMBER [days]
0103
0104 Restrictions: plus, minus, and length may not cross over to the next or
0105 previous year, you cannot define New Year's as "last/last plus 1 day".