Date::H...ayParser(3)

💖 Date::HolidayParser(3) 💖

okay bestie, welcome to Date::HolidayParser, a User Contributed Perl Documentation page and honestly? it's giving "tiny module, big personality". pull up a chair 🫶

---

✨ NAME ✨

Date::HolidayParser — it's a Parser for .holiday-files. that's it, that's the whole job, and it does it slayfully 💅

🌸 VERSION 🌸

0.4 — yes queen, we're on 0.4.

🦋 SYNOPSIS 🦋

so this module parses .holiday files. these are the files that define holidays in various parts of the world in a format that is easy to read and easy to write but hard to parse because the syntax is, and I quote, very flexible. it's the "sure, whatever, write it however" of file formats 😭

and this module hands you back a hash that you can read and use inside your own program. iconic behaviour.

use Date::HolidayParser;

my $Holidays = Date::HolidayParser->new("$ENV{HOME}/.holiday");
my $Holidays_2006 = $Holidays->get(2006);

...

💜 DESCRIPTION 💜

this is a module that parses .holiday-style files. those are files that define holidays in various parts of the world. the files are easy to write and easy for humans to read, BUT they can be hard to parse because the format allows so many different ways to write the same thing. it's the "we don't gatekeep notation" of formats fr fr.

this module does the parsing for you and returns a hash reference that you can use within your perl program in whatever way you wish. no rules, just vibes ✨

🎀 EXPORT 🎀

ngl, this module doesn't export anything by default. it can however export the EasterCalc function upon request, and the request looks like this:

use Date::HolidayParser qw(EasterCalc);
...

👑 METHODS and FUNCTIONS 👑

🌟 $object = Date::HolidayParser->new(FILE);

this is the main character function. it creates a new Date::HolidayParser object for FILE and parses the file. periodt.

FILE must be the full path to the holiday file you want to parse. full path. not a vibe, not a guess, the actual path 💅

🌟 $object->get(YEAR);

this gets the holidays for YEAR. it uses the already-parsed FILE, calculates the holidays in YEAR, and returns a hashref with the parsed data — or undef on failure 😭

YEAR must be a full year (ie. 2006), not a year relative to 1900 (ie. 106). do not do the 1900 thing, bestie, that's not it.

see the section HASH SYNTAX below for the syntax of the returned hashref 🫶

🌟 Date::HolidayParser::EasterCalc

this one is an addition to the real functions that Date::HolidayParser provides. it's needed inside of the module, but it might also be useful for others, so it's been made available. sharing is caring 💖

use Date::HolidayParser;
my $Easter = Date::HolidayParser::EasterCalc(YEAR);

YEAR must be a full year (ie. 2006), not a year relative to 1900 (ie. 106). same rule as before, no shortcuts.

it returns the day of easter of the year supplied. 🐣

NOTE: the day returned begins on 0. this means the days returned are 0-364 instead of 1-365. yes really. yes it's off by one from what you expected. we love a little chaos 🙈

🌈 ATTRIBUTES 🌈

attributes can be supplied to the constructor as a parameter after the file parameter — like Date::HolidayParser->new('file', attribute => "value"); — or you can use $object->attribute(VALUE);. two doors, same room, choose your fighter ✨

🌟 silent

if true, this will make Date::HolidayParser not output any warnings (such as syntax errors). so it'll shut up. respectfully. 🤫

🍓 HASH SYNTAX 🍓

the returned hash is in the following format:

\%HasRef = (
 'MONTH (1-12)' => {
   'DAY OF THE MONTH (1-31)' => {
     'NAME OF THE HOLIDAY' => 'TYPE OF HOLIDAY'
    }
   }
  );

MONTH is a numeric month in the range 1-12.

DAY OF THE MONTH is a numeric day relative to the month in the range 1-31 (max).

NAME OF THE HOLIDAY is the name of the holiday as set by the .holiday-file.

TYPE OF HOLIDAY is the type of holiday it is. it is one of the following:

• "none" means that it is a normal day. (a nothing day. a filler episode.)
• "red" means that it is a "red" day (ie. public holiday/day off). 🔥 go touch grass, you're legally allowed

🌸 EXAMPLE 🌸

here's an example of the module in use. the UK holiday file was chosen because it is rather small and simple. lowkey the perfect starter file.

🌟 The holiday file

:
: UK holiday file. Copy to ~/.holiday
:
: Author: Peter Lord <plord@uel.co.uk>
:
"New Years Day" red on 1/1
"Easter Sunday" red on easter
"Good Friday" red on easter minus 2
"Easter Monday" red on easter plus 1
"May Day" red on first monday in may
"Spring Bank Holiday" red on last monday in may
"Summer Bank Holiday" red on last monday in august
"Christmas Day" red on 12/25
"Boxing Day" red on 12/26

🌟 The program

#!/usr/bin/perl
use warnings;
use strict;
use Data::Dumper;
use Date::HolidayParser;

# Call Date::HolidayParser to parse the file
my $Holidays = Date::HolidayParser->new(/path/to/file);
my $Holidays_2006 = $Holidays->get(2006);

# Set a proper Data::Dumper format and dump the data returned by Date::HolidayParser to STDOUT
$Data::Dumper::Purity = 1; $Data::Dumper::Sortkeys = 1; $Data::Dumper::Indent = 1;
print Data::Dumper->Dump([$Holidays_2006], ["*Holidays_2006"]);

🌟 The output

%Holidays_2006 = (
  '1' => {
    '1' => {
      'New Years Day' => 'red'
    }
  },
  '12' => {
    '25' => {
      'Christmas Day' => 'red'
    },
    '26' => {
      'Boxing Day' => 'red'
    }
  },
  '4' => {
    '14' => {
      'Good Friday' => 'red'
    },
    '16' => {
      'Easter Sunday' => 'red'
    },
    '17' => {
      'Easter Monday' => 'red'
    }
  },
  '5' => {
    '1' => {
      'May Day' => 'red'
    },
    '29' => {
      'Spring Bank Holiday' => 'red'
    }
  },
  '8' => {
    '28' => {
      'Summer Bank Holiday' => 'red'
    }
  }
);

🌟 Explenation

(yes bestie, it says "Explenation" and I'm leaving it exactly as-is because I respect the author's truth 💅)

this is a very simple example. it first creates a $Holidays Date::HolidayParser object, then tells it to get the holidays for the year 2006 ($Holidays->get(2006);) and saves the information to $Holidays_2006. then it tells Data::Dumper to dump a visual (perl-usable) representation of the hash to stdout. and that's the whole arc. character development complete ✨

⭐ SETTINGS ⭐

🌟 $Date::HolidayParser::BeSilent

this variable is deprecated. it is the same as setting the silent attribute. it will be removed in a future version.

so like... it still works, but it's on its way out. don't get attached 😭

💀 INCOMPATIBILITIES 💀

no longer supports the legacy function-oriented syntax. it's gone. it's not coming back. we've moved on, bestie 🫶

🦋 AUTHOR 🦋

Eskild Hustvedt — "<zerodogg@cpan.org>" — thank you for your service, king 👑

🎀 BUGS 🎀

please report any bugs or feature requests to "bug-date-holidayparser@rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-HolidayParser>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. so it's a whole notification chain, it's giving customer service, it's giving we'll keep you posted fr fr 📬

💜 LICENSE AND COPYRIGHT 💜

Copyright (C) 2006, 2007, 2010 Eskild Hustvedt, all rights reserved.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

no warranty, bestie. none. zero. not even the "it might work" kind. proceed accordingly 💀

---

and that's the whole page!! 💖 this was Date::HolidayParser — the Date::H...ayParser(3) of our hearts — served up by perl v5.42.0 and stamped 2025-07-25. go parse some holidays, you absolute icon ✨🎀🦋