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
         weib  Weiberfastnacht             Fat Thursday
         romo  Rosenmontag                 Carnival monday
         fadi  Faschingsdienstag           Shrove tuesday
         asmi  Aschermittwoch              Ash wednesday
         frau  Internationaler Frauentag   International Women's day
         befr  Tag der Befreiung           Liberation day
         grdo  Gruendonnerstag             Maundy Thursday
         karf  Karfreitag                  Good friday
         kars  Karsamstag                  Holy Saturday
         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
         17ju  Tag der deutschen Einheit   Reunion day (>= 1954, <= 1990)
         frie  Augsburger Friedensfest     Augsburg peace day
         mari  Mariae Himmelfahrt          Assumption day
         kind  Weltkindertag               International Childrens Day
         3okt  Tag der deutschen Einheit   Reunion day (>= 1990)
         refo  Reformationstag             Reformation day
         alhe  Allerheiligen               All hallows day
         buss  Buss- und Bettag            Penance day
         votr  Volkstrauertag              Remembrance Day, German Style
         toso  Totensonntag                Sunday in commemoration of the dead
         adv1  1. Advent                   1st sunday in advent
         adv2  2. Advent                   2nd sunday in advent
         adv3  3. Advent                   3rd sunday in advent
         adv4  4. Advent                   4th sunday in advent
         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");

       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 returned 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.

       Patches are welcome. If you can, please fork the project on github to submit your change:

         http://github.com/mschmitt/Date-Holidays-DE

       Tag der Deutschen Einheit was moved from June 17th to October 3rd in 1990 and is therefore
       listed twice when calculating holidays for 1990. This is not a bug. Awareness for this was
       introduced in Version 1.1.

OFFICIAL HOLIDAY INFORMATION

       The German Federal Ministry of the Interior used to publish a comprehensive list of
       holiday dates. This does currently not appear to be the case.

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. On Perl
       versions earlier than 5.12.0 (released 2010), this limits the range of years to work on to
       the years from 1972 to 2037.

       Historic regulations for Buss- und Bettag are still not implemented.

       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.