Barbie > Calendar-List-0.28 > Calendar::List

Download:
Calendar-List-0.28.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.28   Source  

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.

Note that where 'options' and 'end' are both specified, 'options' takes precedence.

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.

Note that where 'options' and 'end' are both specified, 'options' takes precedence.

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

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 (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.
syntax highlighting: