Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Calendar::List
A module for creating date lists

Calendar::List - A module for creating date lists


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 wrapper code and Richard Clamp <richardc at unixbeard.co.uk> for testing the beta versions.


COPYRIGHT AND LICENSE


    Copyright  2003-2007 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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy