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 = (
	'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 YEAR', \%hash01);
my @list = calendar_list('DD-MM-YYYY', \%hash01);
my $html = calendar_selectbox('DD-MM-YYYY',\%hash02);

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

METHODS

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

The first three are tranlated 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.

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

perl, Calendar::Functions, Clone

BUGS & ENHANCEMENTS

No bugs reported as yet.

If you think you've found a bug, send details and patches (if you have one) to <modules@missbarbell.co.uk>.

If you have a suggestion for an enhancement, though I can't promise to implement it, please send details to <modules@missbarbell.co.uk>.

AUTHOR

Barbie, <barbie@missbarbell.co.uk>

for Miss Barbell Productions.

THANKS TO

Dave Cross, <dave@dave.org> for creating Calendar::Simple, the newbie poster on a technical message board who inspired me to write the original wrapper code and Richard Clamp <richardc@unixbeard.co.uk> for testing the beta versions.

COPYRIGHT AND LICENSE

Copyright 2003 by Barbie.

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

cpanm Calendar::List

perl -MCPAN -e shell
install Calendar::List