NAME

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

SYNOPSIS

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

DESCRIPTION

       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
       linux/unix 'ncal' or 'cal' commands. Each of these has a specific subclass of this module
       offering the same utility methods needed by HTML::CalendarMonth.

METHODS

       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 the ncal or cal commands are available, use one of them rather
               than other available date modules since these utilities accurately handle 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. Use 'ncal' or 'cal', respectively, for the
               wrappers around those commands.

       There are number of methods automatically available:

       month()
       year()
       weeknum()
       historical()
       datetool()
           Accessors for the parameters provided to "new()" above.

       dow1st()
           Returns the day of week number for the 1st of the "year" and "month" specified during
           the call to "new()". Relies on the presence of "dow1st_and_lastday()". Should be 0..6
           starting with Sun.

       lastday()
           Returns the last day of the month for the "year" and "month" specified during the call
           to "new()". Relies on the presence of "dow1st_and_lastday()".

Overridden methods

       Subclasses of this module must provide at least the "day_epoch()" and
       "dow1st_and_lastday()" methods.

       dow1st_and_lastday()
           Required. Provides a list containing the day of the week of the first day of the month
           (0..6 starting with Sun) 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 "month" and "year" if they are different from those specified in "new()",
           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 "month" and "year" if they are different from those
           specified in "new()", provide the day of week number. (0=Sunday, 6=Saturday).

       add_days($days, $delta, $day, [$month], [$year])
           For a given day, and optionally "month" and "year" if they are different from those
           specified in "new()", provide a list of year, month, and day once "delta" days have
           been added.

       week_of_year($day, [$month], [$year])
           For a given day, and optionally "month" and "year" if they are different from those
           specified in "new()", 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).

AUTHOR

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

COPYRIGHT

       Copyright (c) 2010 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.

SEE ALSO

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