Calendar::List - A module for creating date lists
use Calendar::List; # basic usage my %hash = calendar_list('DD-MM-YYYY' => 'DD MONTH, YYYY' ); my @list = calendar_list('MM-DD-YYYY'); my $html = calendar_selectbox('DD-MM-YYYY' => 'DAY DDEXT MONTH, YYYY'); # using the hash my %hash01 = ( 'options' => 10, 'exclude' => { 'weekend' => 1 }, 'start' => '01-05-2003', ); my %hash02 = ( 'options' => 10, 'exclude' => { 'holidays' => \@holidays }, 'start' => '01-05-2003', ); my %hash03 = ( 'exclude' => { 'monday' => 1, 'tuesday' => 1, 'wednesday' => 1 }, 'start' => '01-05-2003', 'end' => '10-05-2003', 'name' => 'MyDates', 'selected' => '04-05-2003', ); my %hash = calendar_list('DD-MM-YYYY' => 'DDEXT MONTH YYYY', \%hash01); my @list = calendar_list('DD-MM-YYYY', \%hash02); my $html = calendar_selectbox('DD-MM-YYYY',\%hash03);
The module is intended to be used to return a simple list, hash or scalar of calendar dates. This is achieved by two functions, calendar_list and calendar_selectbox. The former allows a return of a list of dates and a hash of dates, whereas the later returns a scalar containing a HTML code snippet for use as a HTML Form field select box.
calendar_list, calendar_selectbox
Returns a list in an array context or a hash reference in any other context. All paramters are optional, one or two date formats can be specified for the date formats returned in the list/hash. A hash of user defined settings can also be passed into the function. See below for further details.
Note that a second date format is not required when returning a list. A single date format when returning a hash reference, will be used in both key and value portions.
Returns a scalar containing a HTML string. The HTML snippet consists of an HTML form field select box. All paramters are optional, one or two date formats can be specified for the date formats returned in the value attribute and data portion. A hash of user defined settings can also be passed into the function. See below for further details.
Note that a single date format will be used in both value attribute and data portions.
The date formatted parameters passed to the two exported functions can take many different formats. If a single array is required then only one date format string is required.
Each format string can have the following components:
DD MM YYYY DAY MONTH DDEXT DMY MDY YMD MABV DABV EPOCH
The first three are translated into the numerical day/month/year strings. The DAY format is translated into the day of the week name, and MONTH is the month name. DDEXT is the day with the appropriate suffix, eg 1st, 22nd or 13th. DMY, MDY and YMD default to '13-09-1965' (DMY) style strings. MABV and DABV provide 3 letter abbreviations of MONTH and DAY respectively.
EPOCH is translated into the number od seconds since the system epoch. Note that the Time::Piece module must be installed to use this format.
In the optional hash that can be passed to either function, it should be noted that all 3 date formatted strings MUST be in the format 'DD-MM-YYYY'.
An optional hash of settings can be passed as the last parameter to each external function, which consists of user defined limitations. Each setting will effect the contents of the returned lists. This may lead to conflicts, which will result in an undefined reference being returned.
The maximum number of items to be returned in the list.
Note that where 'options' and 'end' are both specified, 'options' takes precedence.
Used by calendar_selectbox. Names the select box form field.
Used by calendar_selectbox. Predefines the selected entry in a select box.
The exclude key allows the user to defined which days they wish to exclude from the returned list. This can either consist of individual days or the added flexibility of 'weekend' and 'weekday' to exclude a traditional group of days. Full list is:
weekday monday tuesday wednesday thursday friday weekend saturday sunday
References a start date in the format DD-MM-YYYY.
References an end date in the format DD-MM-YYYY. Note that if an end date has been set alongside a setting for the maximum number of options, the limit will be defined by which one is reached first.
Internal to the Calendar::Functions module, there is some date comparison code. As a consequence, this requires some date modules that can handle a wide range of dates. There are three modules which are tested for you, these are, in order of preference, Date::ICal, DateTime and Time::Local.
Each module has the ability to handle dates, although only Time::Local exists in the core release of Perl. Unfortunately Time::Local is limited by the Operating System. On a 32bit machine this limit means dates before the epoch (1st January, 1970) and after the rollover (January 2038) will not be represented. If this date range is well within your scope, then you can safely allow the module to use Time::Local. However, should you require a date range that exceedes this range, then it is recommend that you install one of the two other modules.
Calendar::Functions Clone Date::ICal DateTime Time::Local Time::Piece The Calendar FAQ at http://www.tondering.dk/claus/calendar.html
There are no known bugs at the time of this release. However, if you spot a bug or are experiencing difficulties that are not explained within the POD documentation, please submit a bug to the RT system (see link below). However, it would help greatly if you are able to pinpoint problems or even supply a patch.
Fixes are dependent upon their severity and my availability. Should a fix not be forthcoming, please feel free to (politely) remind me by sending an email to barbie@cpan.org .
RT: http://rt.cpan.org/Public/Dist/Display.html?Name=Calendar-List
Barbie, <barbie@cpan.org> for Miss Barbell Productions <http://www.missbarbell.co.uk>.
Dave Cross, <dave at dave.org> for creating Calendar::Simple, the newbie poster on a technical message board who inspired me to write the original code and Richard Clamp <richardc at unixbeard.co.uk> for testing the beta versions.
Copyright (C) 2003-2014 Barbie for Miss Barbell Productions This distribution is free software; you can redistribute it and/or modify it under the Artistic License v2.
To install Calendar::List, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Calendar::List
CPAN shell
perl -MCPAN -e shell install Calendar::List
For more information on module installation, please visit the detailed CPAN module installation guide.