DE(3pm)

📦
version 2.07 · 7 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 DE(3pm) — like, the German holidays module bestie 💖

okay so this is Date::Holidays::DE, a page from the User Contributed Perl Documentation section of the manual. buckle up, we're doing holidays now. 🎀

✨ NAME ✨

Date::Holidays::DE — bestie, it determines German holidays. that's the whole job. 🇩🇪

🌸 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. one function. that's it. she's lowkey minimal and we respect that. 💅

👑 KNOWN HOLIDAYS 👑

The module knows about the following holidays — and yes, we're listing all of them, no skipping:

  • 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. 🐣 (fr fr, once you've got Easter everything else just falls out, iykyk)

💜 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. (the vibe check differs by state, obviously)

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 <i>really</i> 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. 💀 (rip to that list, gone but not forgotten)

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

okay bestie that's the whole page, you ate that 🫶 — this was perl v5.40.1, dated 2025-05-11, and it's the DE(3pm) page from User Contributed Perl Documentation. go forth and never miss a Feiertag again. periodt. 👑💜

📦 where this page comes from