view release on metacpan or  search on metacpan

lib/HTML/CalendarMonth/DateTool.pm  view on Meta::CPAN

sub _datemanip_fails {
  my $self = shift;
  return "not installed" unless $self->_datemanip_present;
  return "historic mode prior to 1752/09 not supported"
    if $self->historic && $self->_is_julian;
  eval { require Date::Manip && Date::Manip::Date_Init() };
  return "init failure: $@" if $@;
  return;
}

sub _timelocal_present { eval "require Time::Local"; return !$@ }
sub _datecalc_present  { eval "require Date::Calc";  return !$@ }
sub _datetime_present  { eval "require DateTime";    return !$@ }
sub _datemanip_present { eval "require Date::Manip"; return !$@ }
sub _ncal_present      { shift->_ncal_cmd }
sub _cal_present       { shift->_cal_cmd  };


1;

__END__

=head1 NAME

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

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

=head1 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.

=head1 METHODS

=over

=item new()

Constructor. Takes the following parameters:

=over

=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.

=item month

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

=item weeknum

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

=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.

=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.

=back

=back

There are number of methods automatically available:

=over

=item month()

=item year()

=item weeknum()

=item historical()

=item datetool()

Accessors for the parameters provided to C<new()> above.

=item dow1st()

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

=item lastday()

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

=back

=head1 Overridden methods

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