Linux Certif

Toute la documentation sur la certification Linux LPI

Date::HolidayParser.3pm

NAME

Date::HolidayParser - Parser for .holiday-files

VERSION

0.3

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. You're encouraged to use the object oriented interface. It can however export the Parse and EasterCalc functions upon request by issuing

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

FUNCTIONS

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

$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);

$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 returns are 0-364 instead of 1-365.

Date::HolidayParser::Parse

This is the legacy syntax of Date::HolidayParser. You're strongly encouraged to use the object oriented interface. This function is slower than the OO-interface if you need to interperate more than one year.

         use Date::HolidayParser;
 
         my $Holidays = Date::HolidayParser::Parse("/path/to/holiday.file", "YEAR");
 
 

YEAR must be a full year (ie. 2006) not a year relative to 1900 (ie. 106). The path must be the full path to the holiday file you want to parse.

It returns a hashref with the parsed data or undef on failure. See the section HASH SYNTAX below for the syntax of the returned hashref.

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();
         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

$Date::HolidayParser::BeSilent

If this is set to any true value then the holiday parser will not output any errors (syntax or internal) unless they are fatal (causing the module to die()) or invalid usage of one or more of the functions.

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