HTML::CalendarMonth::DateTool - Base class for determining which date package to use for calendrical calculations.

  my $date_tool = HTML::CalendarMonth::DateTool->new(
                    year     => $YYYY_year,
                    month    => $one_thru_12_month,
                    weeknum  => $weeknum_mode,
                    historic => $historic_mode,
                    datetool => $specific_datetool_if_desired,
                  );

This module attempts to utilize the best date calculation package available on the current system. For most contemporary dates this usually ends up being the internal Time::Local package of perl. For more exotic dates, or when week number of the years are desired, other methods are attempted including DateTime, Date::Calc, Date::Manip, and the unix 'cal' command. Each of these has a specific subclass of this module offering the same utility methods needed by HTML::CalendarMonth.

new()

Constructor. Takes the following parameters:

year

Year of calendar in question (required). If you are rendering exotic dates (i.e. dates outside of 1970 to 2038) then something besides Time::Local will be used for calendrical calculations.

month

Month of calendar in question (required). 1 through 12.

weeknum

Optional. When specified, will limit class excursions to those that are currently set up for week of year calculations.

historic

Optional. If the 'cal' command is available, use it rather than other available date modules since the 'cal' command accurately handles some specific historical artifacts such as the transition from Julian to Gregorian.

datetool

Optional. Mostly for debugging, this option can be used to indicate a specific HTML::CalendarMonth::DateTool subclass for instantiation. The value can be either the actual utility class, e.g., Date::Calc, or the name of the CalendarMonth handler leaf class, e.g. DateCalc. For the 'cal' command, use 'cal'.

There are number of methods automatically available:

month()

year()

weeknum()

historical()

datetool()

Accessors for the parameters provided to CWnew() above.

dow1st()

Returns the day of week number for the 1st of the CWyear and CWmonth specified during the call to CWnew(). Relies on the presence of CWdow1st_and_lastday().

lastday()

Returns the last day of the month for the CWyear and CWmonth specified during the call to CWnew(). Relies on the presence of CWdow1st_and_lastday().

Subclasses of this module must provide at least the CWday_epoch() and CWdow1st_and_lastday() methods.

dow1st_and_lastday()

Required. Provides a list containing the day of the week of the first day of the month along with the last day of the month.

day_epoch()

Optional unless interested in epoch values for wacky dates. For a given day, and optionally CWmonth and CWyear if they are different from those specified in CWnew(), provide the unix epoch in seconds for that day at midnight.

If the subclass is expected to provide week of year numbers, three more methods are necessary:

dow()

For a given day, and optionally CWmonth and CWyear if they are different from those specified in CWnew(), provide the day of week number. (1=Sunday, 6=Saturday). For a given day, and optionally CWmonth and CWyear if they are different from those specified in CWnew(), provide a list of year, month, and day once CWdelta days have been added.

week_of_year($day, [$month], [$year])

For a given day, and optionally CWmonth and CWyear if they are different from those specified in CWnew(), provide a list with the week number of the year along with the year. (some days of a particular year can end up belonging to the prior or following years).

Matthew P. Sisk, <sisk@mojotoad.com>

Copyright (c) 2005 Matthew P. Sisk. All rights reserved. All wrongs revenged. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

HTML::CalendarMonth(3), Time::Local(3), DateTime(3), Date::Calc(3), Date::Manip(3), cal(1)