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. (1=Sunday,
7=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)
