NAME

Calendar - Perl extension for calendar convertion

SYNOPSIS

   use Calendar;
   my $date = Calendar->new_from_Gregorian(12, 16, 2006);
   print $date->date_string("Gregorian date: %M %W %d %Y"), "\n";

   my $newdate = $date + 7;
   print $date->date_string("Gregorian date of next week: %D"), "\n";


   $newdate = $date-7;
   print $newdate->date_string("Absolute date of last week: %A\n");


   my $diff = $date-$newdate;
   printf "There is %d days between %s and %s\n",
       $diff, $date->date_string("%D"), $newdate->date_string("%D");


   $date->convert_to_Julian;
   print $date->date_string("Julian date: %M %W %d %Y"), "\n";

DESCRIPTION

Calendar is a class for calendar convertion or calculation. The algorithm is from emacs calendar library. Most functions of this class is simply rewrite from elisp to perl.

Constructor

new

All class of Calendar should accept absolute date to construct the object. Other type of argument may also be acceptable. For example:

    use Calendar::Gregorian;
    Calendar::Gregorian->new(732662);
    Calendar::Gregorian->new(12, 17, 2006);
    Calendar::Gregorian->new(-year=>2006, -month=>12, -day=>17);

new_from_Package

Calendar has AUTOLOAD function that can automatic call new function from package. So the following construct are also valid:

    use Calendar;
    Calendar->new_from_Gregorian(732662);
    Calendar->new_from_Gregorian(12, 17, 2006);
    Calendar->new_from_Gregorian(-year=>2006, -month=>12, -day=>17);

Convertion

Calendar object can convert from each other. The function is name `convert_to_Package'. For example:

    $date = Calendar->new_from_Gregorian(12, 17, 2006);
    $date->convert_to_Julian;

Now $date is a Julian calendar date. If you want maintain $date not change, use Calendar->new_from_Julian($date->absolute_date) instead.

Operator

Calendar overload several operator.

+

A Calendar object can add a number of days. For example:

    $newdate = $date + 1;

The $newdate is next day of $date. You CANNOT add a date to another date.

-

If a date substract from a number of days, that means the date before the number of days. For example:

    $newdate = $date - 1;

The $newdate is the last day of $date. When a date substract from another date, returns the days between the two date. For example:

    $newdate = $date + 7;
    $days = $newdate - $date;        # $days is 7

The return value is different type, you should always be careful.

<=>

Two date can compare from each other. For example:

    if ( $date2 > $date1 ) {
        print "$date2 is after $date1.\n";
    }
    else {
        print "$date1 is after $date2.\n";
    }

``''

That means you can simply print the date without explicitly call a method. For detail, read ``Format date'' section.

Format date

Every calendar class has a format template: $default_format. You can set the template. The format function is `date_string'. The format specifications as following:

   %%       PERCENT
   %A       Absoute date
   %d       numeric day of the month, with leading zeros (eg 01..31)
   %D       MM/DD/YY
   %m       month number, with leading zeros (eg 01..31)
   %M       month numer
   %W       day of the week
   %Y       year

For chinese calendar, the following specifications are available:

   %S       sexagesimal name, eg. "丙戌"
   %D       day name, eg. "初二"
   %Z       zodiac name, eg. "狗"
   %m       month name in chinese, eg. "十一月"
   %W       week day name in chinese, eg. "星期一"

Other method

absoute_date: The number of days elapsed between the Gregorian date 12/31/1 BC. The Gregorian date Sunday, December 31, 1 BC is imaginary.
astro_date: Astronomers use a simple counting of days elapsed since noon, Monday, January 1, 4713 B.C. on the Julian calendar. The number of days elapsed is called the ``Julian day number'' or the ``Astronomical day number''.
new_from_Astro: There is no package Calendar::Astro. use new_from_Astro and astro_date to convert between other type of calendar and astro calendar.
today: The current date of local time.
weekday: The weekday number. 0 for sunday and 1 for monday.
weekday_name: The full name of the weekday.
month: The number of month, range from 1 to 12.
month_name: The full name of month.
day: The number of day in the month. The first day in the month is 1.
year: The year number.

AUTHOR

Ye Wenbin <wenbinye@gmail.com>

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

Calendar - Perl extension for calendar convertion