/ 
Date-HolidayParser-0.43
River stage zero No dependents
/ Date::HolidayParser

NAME

Date::HolidayParser - Parser for .holiday-files

VERSION

0.4

SYNOPSIS

This module parses .holiday files. These are files that define holidays in various parts of the world in an easy to read and easy to write (but hard to parse due to its very flexible syntax) format.

This module returns a hash that you can read and use within your program.

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. These are files that define holidays in various parts of the world. The files are easy to write and easy for humans to read, but can be hard to parse because the format allows many different ways to write it.

This module parses the files for you and returns a hash reference that you can use within your perl program in whatever way you wish.

EXPORT

This module doesn't export anything by default. It can however export the EasterCalc function upon request by issuing

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

METHODS and FUNCTIONS

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

This is the main function. It creates a new Date::HolidayParser object for FILE and parses the file.

FILE must be the full path to the holiday file you want to parse.

$object->get(YEAR);

This gets the holidays for YEAR. It uses the already parsed FILE and 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).

See the section HASH SYNTAX below for the syntax of the returned hashref.

Date::HolidayParser::EasterCalc

This is an addition to the real functions that Date::HolidayParser provides. It's needed inside of the module but might also be useful for others and thus made available.

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

It returns the day of easter of the year supplied.

NOTE: The day returned begins on 0. This means that the days returned are 0-364 instead of 1-365.

ATTRIBUTES

Attributes can be supplied to the constructor as a parameter after the file parameter (ie. Date::HolidayParser->new('file', attribute => "value");), or you can use $object->attribute(VALUE).

silent

If true this will make Date::HolidayParser not output any warnings (such as syntax errors).

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.

  • "red" means that it is a "red" day (ie. public holiday/day off).

EXAMPLE

Here is an example of the module in use. The UK holiday file was chosen because it is rather small and simple.

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

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.

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.

INCOMPATIBILITIES

No longer supports the legacy function-oriented syntax.

AUTHOR

Eskild Hustvedt - <zerodogg@cpan.org>

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.

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.