DateTime-Calendar-Mayan

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

DateTime::Calendar::Mayan
========================

This is a companion module to DateTime.pm. It implements the Mayan Long Count
calendar.

INSTALLATION

To install this module type the following:

perl Makefile.PL
make
make test
make install

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

=head1 NAME

DateTime::Calendar::Mayan - The Mayan Long Count, Haab, and Tzolkin calendars

=head1 SYNOPSIS
 
   use DateTime::Calendar::Mayan

   my $dtcm = DateTime::Calendar::Mayan->new(
        baktun  => 12,
        katun   => 19,
        tun     => 10,
        uinal   => 2,

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

   print $dtcm->date; 
   # prints 12.19.10.2.8
   print $dtcm->haab; 
   # prints 3 Uayeb
   print $dtcm->tzolkin; 
   # prints 3 Oc

=head1 DESCRIPTION

An implementation of the Mayan Long Count, Haab, and Tzolkin calendars as
defined in "Calendrical Calculations The Millennium Edition".  Supplemented
by "Frequently Asked Questions about Calendars".

=head1 METHODS

=over 4

=item * new( baktun => $scalar, ..., epoch => $object ) 

Accepts a hash representing a date on the Long Count calendar
and a "DateTime::Calendar" object specifying an alternate epoch.
All keys are optional.


   The units are:
   kin   = 1 day
   uinal = 20 days
   tun   = 360 days
   katun = 7200 days
   baktun = 144000 days

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

=item * today

Alternate constructor.  Uses DateTime->today to set the current date.

=item * clone

This object method returns a replica of the given object.

=item * from_object( object => $object )

Accepts a "DateTime::Calendar" object.  Although this calendar doesn't support
time it will preserve the time value of objects passed to it.  This prevents a
loss of precision when chaining calendars.

Note: Language support is not implemented.

=item * utc_rd_values

Returns the current UTC Rata Die days, UTC Rata Die seconds, and nanoseconds
as a three element list. 

=item * from_epoch( epoch => $scalar )

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

=item * mayan_epoch

Returns a "DateTime::Calendar::Mayan" object set to the current Mayan epoch.

=item * date

=item * bktuk

=item * long_count( $scalar )

Returns the Long Count calendar date.  Think DateTime::ymd.  Like ymd this
method also accepts an optional field separator string.

=item * haab( $scalar )

Returns the Haab calendar date.  Accepts an optional field separator string.

=item * tzolkin( $scalar )

Returns the Tzolkin calendar date.  Accepts an optional field separator string.

=item * baktun

=item * katun

=item * tun

=item * uinal

=item * kin( $scalar )

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

Chapter 10 of Calendarical Calculations "The Millennium Edition".

and

Chapter 7 of Frequently Asked Questions about Calendars.
   http://www.tondering.dk/claus/cal/node8.html

=head1 GOTCHAS

The Long Count calendar is cyclical and it is possible to have different dates
in other calendars that convert to be the same Long Count date.  Under this
calendar the dates 0.0.0.0.0 and 13.0.0.0.0 are equivalent.

The Long Count calendar will next roll over in late 2012 (Gregorian).  In
anticipation of this Long Count dates input as 0-12.*.*.*.* will convert to
Gregorian dates in the Mayan year that started in -3113 (Gregorian).  Long
Count dates input as 13.*.*.*.* will convert to Gregorian dates in the Mayan
year that start in 2012 (Gregorian).

Example:

   use DateTime;
   use DateTime::Calendar::Mayan;

lib/DateTime/Calendar/Mayan.pod  view on Meta::CPAN

   13.0.0.0.0
   -3113-08-11
   13.0.0.0.0
   2012-12-21

As you can see the Long Count dates are identical but the Gregorian equivalent
dates are different.

Support for a count of Mayan "years" or "cycles" allowing accurate conversion
to/from Gregorian dates may be added to this module in the future.  This would
be an extension to the historical Long Count calendar.

=head1 CREDITS

Dave Rolsky (DROLSKY) for the DateTime project and carrying
us this far.

Eugene van der Pijll (PIJLL) for DateTime::Calendar::Julian
which I looked at more then once.

Calendrical Calculations
"The Millennium Edition"
By Edward M. Reingold & Nachum Dershowitz.
(ISBN 0-521-77752-6 paperback)
   http://www.calendarists.com

Abigail (ABIGAIL) for Date::Maya from which I confirmed the algorithm
for Mayan years.

"Frequently Asked Questions about Calendars" by
Claus TE<248>ndering.
   http://www.tondering.dk/claus/calendar.html

=head1 SUPPORT

Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.

=head1 AUTHOR

Joshua Hoblitt <jhoblitt@cpan.org>

t/009_haab.t  view on Meta::CPAN

use warnings;

use Test::More tests => 21;

use DateTime::Calendar::Mayan;

{
    my $dtcm = DateTime::Calendar::Mayan->new();
    is( $dtcm->haab, '8 Cumku', 'Haab epoch' );

    # calendar repeats every 365 days
    $dtcm->add( kin => 365 );
    is( $dtcm->haab, '8 Cumku', 'Full cycle' );
}

{
    # rewind to start of haab cycle
    my $dtcm = DateTime::Calendar::Mayan->new();
    $dtcm->subtract( kin => 348 );

    is( $dtcm->haab, '0 Pop', 'Haab month' );

t/010_tzolkin.t  view on Meta::CPAN

use warnings;

use Test::More tests => 22;

use DateTime::Calendar::Mayan;

{
    my $dtcm = DateTime::Calendar::Mayan->new();
    is( $dtcm->tzolkin, '4 Ahau', 'Haab epoch' );

    # calendar repeats every 260 days
    $dtcm->add( kin => 260 );
    is( $dtcm->tzolkin, '4 Ahau', 'Full Cycle' );
}

{
    # rewind to start of tzolkin cycle
    my $dtcm = DateTime::Calendar::Mayan->new();
    $dtcm->subtract( kin => 159 );
    
    is( $dtcm->tzolkin, '1 Imix', 'Tzolkin name' );