.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::CalendarMonth::DateTool 3pm"
.TH HTML::CalendarMonth::DateTool 3pm "2018-11-25" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::CalendarMonth::DateTool \- Base class for determining which date package to use for calendrical calculations.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&  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,
\&                  );
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Constructor. Takes the following parameters:
.RS 4
.IP "year" 4
.IX Item "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.
.IP "month" 4
.IX Item "month"
Month of calendar in question (required). 1 through 12.
.IP "weeknum" 4
.IX Item "weeknum"
Optional. When specified, will limit class excursions to those that are
currently set up for week of year calculations.
.IP "historic" 4
.IX Item "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.
.IP "datetool" 4
.IX Item "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.
.RE
.RS 4
.RE
.PP
There are number of methods automatically available:
.IP "\fBmonth()\fR" 4
.IX Item "month()"
.PD 0
.IP "\fByear()\fR" 4
.IX Item "year()"
.IP "\fBweeknum()\fR" 4
.IX Item "weeknum()"
.IP "\fBhistorical()\fR" 4
.IX Item "historical()"
.IP "\fBdatetool()\fR" 4
.IX Item "datetool()"
.PD
Accessors for the parameters provided to \f(CW\*(C`new()\*(C'\fR above.
.IP "\fBdow1st()\fR" 4
.IX Item "dow1st()"
Returns the day of week number for the 1st of the \f(CW\*(C`year\*(C'\fR and \f(CW\*(C`month\*(C'\fR
specified during the call to \f(CW\*(C`new()\*(C'\fR. Relies on the presence of
\&\f(CW\*(C`dow1st_and_lastday()\*(C'\fR. Should be 0..6 starting with Sun.
.IP "\fBlastday()\fR" 4
.IX Item "lastday()"
Returns the last day of the month for the \f(CW\*(C`year\*(C'\fR and \f(CW\*(C`month\*(C'\fR specified
during the call to \f(CW\*(C`new()\*(C'\fR. Relies on the presence of
\&\f(CW\*(C`dow1st_and_lastday()\*(C'\fR.
.SH "Overridden methods"
.IX Header "Overridden methods"
Subclasses of this module must provide at least the \f(CW\*(C`day_epoch()\*(C'\fR and
\&\f(CW\*(C`dow1st_and_lastday()\*(C'\fR methods.
.IP "\fBdow1st_and_lastday()\fR" 4
.IX Item "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.
.IP "\fBday_epoch()\fR" 4
.IX Item "day_epoch()"
Optional unless interested in epoch values for wacky dates. For a given
day, and optionally \f(CW\*(C`month\*(C'\fR and \f(CW\*(C`year\*(C'\fR if they are different from
those specified in \f(CW\*(C`new()\*(C'\fR, provide the unix epoch in seconds for that
day at midnight.
.PP
If the subclass is expected to provide week of year numbers, three more
methods are necessary:
.IP "\fBdow()\fR" 4
.IX Item "dow()"
For a given day, and optionally \f(CW\*(C`month\*(C'\fR and \f(CW\*(C`year\*(C'\fR if they are
different from those specified in \f(CW\*(C`new()\*(C'\fR, provide the day of week
number. (0=Sunday, 6=Saturday).
.ie n .IP "add_days($days, $delta, $day, [$month], [$year])" 4
.el .IP "add_days($days, \f(CW$delta\fR, \f(CW$day\fR, [$month], [$year])" 4
.IX Item "add_days($days, $delta, $day, [$month], [$year])"
For a given day, and optionally \f(CW\*(C`month\*(C'\fR and \f(CW\*(C`year\*(C'\fR if they are
different from those specified in \f(CW\*(C`new()\*(C'\fR, provide a list of year,
month, and day once \f(CW\*(C`delta\*(C'\fR days have been added.
.IP "week_of_year($day, [$month], [$year])" 4
.IX Item "week_of_year($day, [$month], [$year])"
For a given day, and optionally \f(CW\*(C`month\*(C'\fR and \f(CW\*(C`year\*(C'\fR if they are
different from those specified in \f(CW\*(C`new()\*(C'\fR, 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).
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew P. Sisk, <\fIsisk@mojotoad.com\fR>
.SH "COPYRIGHT"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBHTML::CalendarMonth\fR\|(3), \fBTime::Local\fR\|(3), \fBDateTime\fR\|(3), \fBDate::Calc\fR\|(3),
\&\fBDate::Manip\fR\|(3), \fBcal\fR\|(1)