/ 
Date-Holidays-DE-1.0.1
River stage one • 1 direct dependent • 1 total dependent
/ Date::Holidays::DE

NAME

Date::Holidays::DE - Determine German holidays

SYNOPSIS

use Date::Holidays::DE qw(holidays);
my $feiertage_ref = holidays();
my @feiertage     = @$feiertage_ref;

DESCRIPTION

This module exports a single function named holidays() which returns a list of German holidays in a given year.

KNOWN HOLIDAYS

The module knows about the following holidays:

neuj  Neujahr                     New Year's day
hl3k  Hl. 3 Koenige               Epiphany
romo  Rosenmontag                 Carnival monday
fadi  Faschingsdienstag           Shrove tuesday
karf  Karfreitag                  Good friday
osts  Ostersonntag                Easter sunday
ostm  Ostermontag                 Easter monday
pfis  Pfingstsonntag              Whit sunday
pfim  Pfingstmontag               Whit monday
himm  Himmelfahrtstag             Ascension day
fron  Fronleichnam                Corpus christi
1mai  Maifeiertag                 Labor day, German style 
mari  Mariae Himmelfahrt          Assumption day
3okt  Tag der deutschen Einheit   Reunion day
refo  Reformationstag             Reformation day
alhe  Allerheiligen               All hallows day
buss  Buss- und Bettag            Penance day
heil  Heiligabend                 Christmas eve
wei1  1. Weihnachtstag            Christmas
wei2  2. Weihnachtstag            Christmas
silv  Silvester                   New year's eve

Please refer to the module source for detailed information about how every holiday is calculated. Too much detail would be far beyond the scope of this document, but it's not particularly hard once you've found the date for Easter.

USAGE

OUTPUT FORMAT

The list returned by holidays() consists of UNIX-Style timestamps in seconds since The Epoch. You may pass a strftime() style format string to get the dates in any format you desire:

my $feiertage_ref = holidays(FORMAT=>"%d.%m.%Y");

This might be considered "hard to use" by some people, so here are a few examples to get you started:

FORMAT=>"%d.%m.%Y"              25.12.2001
FORMAT=>"%Y%m%d"                20011225
FORMAT=>"%a, %B %d"             Tuesday, December 25

Please consult the manual page of strftime() for a complete list of available format definitions.

There is, however, one "proprietary" extension to the formats of strftime(): The format definition %# will print the internal abbreviation used for each holiday.

FORMAT=>"%#:%d.%m"              wei1:25.12.

As the module doesn't want to deal with i18n issues, you'll have to find your own way to translate the aliases into your local language. See the example/feiertage.pl script included in the distribution to get the idea. This was added in version 0.6.

LOCAL HOLIDAYS

The module also knows about different regulations throughout Germany.

When calling holidays(), the resulting list by default contains the list of Germany-wide holidays.

You can specify one ore more of the following federal states to get the list of holidays local to that state:

bw  Baden-Wuerttemberg
by  Freistaat Bayern
be  Berlin
bb  Brandenburg
hb  Freie Hansestadt Bremen
hh  Freie und Hansestadt Hamburg
he  Hessen
mv  Mecklenburg-Vorpommern
ni  Niedersachsen
nw  Nordrhein-Westfalen
rp  Rheinland-Pfalz
sl  Saarland
sn  Freistaat Sachsen
st  Sachsen-Anhalt
sh  Schleswig-Holstein
th  Freistaat Thueringen

For example,

my $feiertage_ref = holidays(WHERE=>['by', 'bw']);

returns the list of holidays local to Bayern or Baden-Wuerttemberg.

To get the list of local holidays along with the default list of common German holidays, use the following:

my $feiertage_ref = holidays(WHERE=>['common', 'bw']);

returns the list of common German holidays merged with the list of holidays specific to Baden-Wuerttemberg.

You can also request a list containing all holidays this module knows about:

my $feiertage_ref = holidays(WHERE=>['all']);

will return a list of all known holidays. This was added in version 0.6.

ADDITIONAL HOLIDAYS

There are a number of holidays that aren't really holidays, e.g. New Year's Eve and Christmas Eve. These aren't contained in the common set of holidays returnd by the holidays() function. The aforementioned silv and heil are probably the most likely ones that you'll need. If you live in Koeln, you'll probably want to include romo and fadi, too. ;-)

As if things weren't bad enough already, there even are Holidays that aren't valid in an entire state. This refers to fron, alhe and mari in particular.

If you want one or several of them to appear in the output from holidays(), use the following:

my $feiertage_ref = holidays(ADD=>['heil', 'silv']);

SPECIFYING THE YEAR

By default, holidays() returns the holidays for the current year. Specify a year as follows:

my $feiertage_ref = holidays(YEAR=>2004);

HOLIDAYS ON WEEKENDS

By default, holidays() includes Holidays that occur on weekends in its listing.

To disable this behaviour, set the WEEKENDS option to 0:

my $feiertage_ref = holidays(WEEKENDS=>0);

COMPLETE EXAMPLE

Get all holidays for Germany and Bayern in 2004, count New Year's Eve and Christmas Eve as Holidays. Also, we live in a catholic region where Assumption day is a holiday, too. Exclude weekends and return the date list in human readable format:

  my $feiertage_ref = holidays( WHERE    => ['common', 'he'],
				FORMAT   => "%a, %d.%m.%Y"
				WEEKENDS => 0,
                                YEAR     => 2004,
				ADD      => ['heil', 'silv', 'mari']);

PREREQUISITES

Uses Date::Calc 5.0 for all calculations. Makes use of the POSIX and Time::Local modules from the standard Perl distribution.

BUGS & SUGGESTIONS

If you run into a miscalculation, need some sort of feature or an additional holiday, or if you know of any new changes to our funky holiday situation, please drop the author a note.

OFFICIAL HOLIDAY DATES

The official holiday dates are published by the German Federal Ministry of the Interior at:

http://www.bmi.bund.de/services/lexikon/lexikon.jsp?key=F&hit=Feiertage

LIMITATIONS

Date::Calc works with year, month and day numbers exclusively. Even though this module uses Date::Calc for all calculations, it represents the calculated holidays as UNIX timestamps (seconds since The Epoch) to allow for more flexible formatting. This limits the range of years to work on to the years from 1972 to 2037.

Date::Holidays::DE doesn't know anything about past holiday regulations. Tag der Deutschen Einheit, for example, was moved in 1991 from June 17th to October 3rd after the reunion of the eastern and western parts of Germany. None of the calendar programs the author has looked at, know about June 17th.

Date::Holidays::DE is not configurable. Holiday changes don't come over night and a new module release can be rolled out within a single day.

AUTHOR

Martin Schmitt <mas at scsy dot de>

SEE ALSO

perl, Date::Calc.