view release on metacpan or  search on metacpan

lib/Calendar/Functions.pm  view on Meta::CPAN

package Calendar::Functions;

use strict;
use warnings;

use vars qw($VERSION @ISA %EXPORT_TAGS @EXPORT @EXPORT_OK);
$VERSION = '1.02';

#----------------------------------------------------------------------------

=head1 NAME

Calendar::Functions - A module containing functions for dates and calendars.

=head1 SYNOPSIS

  use Calendar::Functions;
  $ext       = ext($day);
  $moty      = moty($monthname);
  $monthname = moty($moty);
  $dotw      = dotw($dayname);
  $dayname   = dotw($dotw);

  use Calendar::Functions qw(:dates);
  my $dateobj               = encode_date($day,$month,$year);
  ($day,$month,$year,$dotw) = decode_date($dateobj);
  $cmp = compare_dates($dateobj1, $dateobj2);

  use Calendar::Functions qw(:form);
  $str = format_date( $fmt, $day, $month, $year, $dotw);
  $str = reformat_date( $date, $fmt1, $fmt2 );

  use Calendar::Functions qw(:all);
  fail_range($year);

=head1 DESCRIPTION

The module is intended to provide numerous support functions for other
date and/or calendar functions

=head1 EXPORT

  ext, moty, dotw

  dates:    encode_date, decode_date, compare_dates, add_day

  form:     format_date, reformat_date

  all:      encode_date, decode_date, compare_dates, add_day
            format_date, reformat_date,
            ext, moty, dotw, fail_range

=cut

#----------------------------------------------------------------------------

#############################################################################
#Export Settings                                                            #
#############################################################################

require Exporter;

@ISA = qw(Exporter);

%EXPORT_TAGS = (
    'basic' => [ qw( ext moty dotw ) ],
    'dates' => [ qw( ext moty dotw
                     encode_date decode_date compare_dates add_day ) ],
    'form'  => [ qw( ext moty dotw format_date reformat_date ) ],
    'all'   => [ qw( ext moty dotw format_date reformat_date fail_range
                     encode_date decode_date compare_dates add_day ) ],
    'test'  => [ qw( _caltest ) ],
);

@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} }, @{ $EXPORT_TAGS{'test'} } );
@EXPORT    = ( @{ $EXPORT_TAGS{'basic'} } );

#############################################################################
#Library Modules                                                            #
#############################################################################

use Time::Local;
eval "use Date::ICal";
my $di = ! $@;
eval "use DateTime";
my $dt = ! $@;
eval "use Time::Piece";
my $tp = ! $@;

if($tp) {
    require Time::Piece;
}

#############################################################################
#Variables
#############################################################################

# prime our print out names
my @months  = qw(   NULL January February March April May June July

lib/Calendar/Functions.pm  view on Meta::CPAN

  DABV

The first three are tranlated into the numerical day/month/year strings.
The DAY format is translated into the day of the week name, and MONTH
is the month name. DDEXT is the day with the appropriate suffix, eg 1st,
22nd or 13th. DMY, MDY and YMD default to '13-09-1965' (DMY) style strings.
MABV and DABV provide 3 letter abbreviations of MONTH and DAY respectively.

=back

=head1 DATE MODULES

Internal to this module is some date comparison code. As a consequence this
requires some date modules that can handle a wide range of dates. There are
three modules which are tested for you, these are, in order of preference,
DateTime, Date::ICal and Time::Local.

Each module has the ability to handle dates, although only Time::Local exists
in the core release of Perl. Unfortunately Time::Local is limited by the
Operating System. On a 32bit machine this limit means dates before 1st January
1902 and after 31st December 2037 will not be represented. If this date range
is well within your scope, then you can safely allow the module to use
Time::Local. However, should you require a date range that exceedes this
range, then it is recommended that you install one of the two other modules.

=head1 ERROR HANDLING

In the event that Time::Local is being used and dates that exceed the range
of 1st January 1902 to 31st December 2037 are passed, an undef is returned.

=head1 SEE ALSO

=head2 Further Modules

=over 4

=item L<Calendar::List>

=back

=head2 Date/Time Modules

=over 4

=item L<Date::ICal>

=item L<DateTime>

=item L<Time::Local>

=item L<Time::Piece>

=back

=head2 Further Information

=over 4

=item L<The Calendar FAQ>

L<http://www.tondering.dk/claus/calendar.html>

=item L<The Perl Advent Entry>

2018-12-01 : L<http://perladvent.org/2018/2018-12-01.html>

=back
  
=head1 BUGS, PATCHES & FIXES

There are no known bugs at the time of this release. However, if you spot a
bug or are experiencing difficulties that are not explained within the POD
documentation, please submit a bug to the RT system (see link below). However,
it would help greatly if you are able to pinpoint problems or even supply a
patch.

Fixes are dependent upon their severity and my availability. Should a fix not
be forthcoming, please feel free to (politely) remind me by sending an email
to barbie@cpan.org .

RT: http://rt.cpan.org/Public/Dist/Display.html?Name=Calendar-List

=head1 AUTHOR

  Barbie, <barbie@cpan.org>
  for Miss Barbell Productions <http://www.missbarbell.co.uk>.

=head1 THANKS TO

Dave Cross, E<lt>dave at dave.orgE<gt> for creating Calendar::Simple, the
newbie poster on a technical message board who inspired me to write the
original wrapper code and Richard Clamp E<lt>richardc at unixbeard.co.ukE<gt>
for testing the beta versions.

=head1 COPYRIGHT AND LICENSE

  Copyright (C) 2003-2019 Barbie for Miss Barbell Productions

  This distribution is free software; you can redistribute it and/or
  modify it under the Artistic License v2.

=cut