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)

perl v5.22.2                                       2016-06-21                 HTML::CalendarMonth::DateTool(3pm)