NAME

Calendar::List - A module for creating date lists

SYNOPSIS

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

DESCRIPTION

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.

EXPORT

calendar_list,
calendar_selectbox

FUNCTIONS

calendar_list([DATEFORMAT] [,DATEFORMAT] [,OPTIONSHASH])

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.

calendar_selectbox([DATEFORMAT] [,DATEFORMAT] [,OPTIONSHASH])

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.

DATE FORMATS

Parameters

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.

Options

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

OPTIONAL SETTINGS

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.

options

The maximum number of items to be returned in the list.

name

Used by calendar_selectbox. Names the select box form field.

select

Used by calendar_selectbox. Predefines the selected entry in a select box.

exclude

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

start

References a start date in the format DD-MM-YYYY.

end

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.

DATE MODULES

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.

SEE ALSO

Calendar::Functions

Clone
Date::ICal
DateTime
Time::Local
Time::Piece

The Calendar FAQ at http://www.tondering.dk/claus/calendar.html

BUGS, PATCHES & FIXES

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 dependant upon their severity and my availablity. 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

AUTHOR

Barbie, <barbie@cpan.org>
for Miss Barbell Productions <http://www.missbarbell.co.uk>.

THANKS TO

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 AND LICENSE

Copyright © 2003-2008 Barbie for Miss Barbell Productions.

This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, using the Artistic License.

The full text of the licenses can be found in the Artistic file included with this distribution, or in perlartistic file as part of Perl installation, in the 5.8.1 release or later.

cpanm Calendar::List

perl -MCPAN -e shell
install Calendar::List