DateTime-Calendar-Japanese

 view release on metacpan or  search on metacpan

LICENSE  view on Meta::CPAN

This is the license from "Calendrical Calculations", and code that was
ported from it.

---

The Functions (code, comments, and definitions) contained on this compact disk (the "Program") were written by Edward M. Reingold and Nachum Dershowitz (the "Authors"), who retain all rights to them except as granted in the License and subject to the...

The Authors' public service intent is more liberal than suggested by the License below, as are their licensing policies for otherwise nonallowed uses such as--without limitation--those in commercial, web-site, and large-scale academic contexts. Pleas...

http://www.calendarists.com

for all uses not authorized below; in case there is cause for doubt about whether a use you contemplate is authorized, please contact the Authors (email: reingold@iit.edu) . For commercial licensing information, contact the first author at the Depart...

1. LICENSE. The Authors grant you a license for personal use only. This means that for strictly personal use you may copy and use the code, and keep a backup or archival copy also. Any other uses, including without limitation, allowing the code or it...

2. WARRANTY.

(a) THE AUTHORS PROVIDE NO WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

(b) THE AUTHORS SHALL NOT BE LIABLE TO YOU OR ANY THIRD PARTIES FOR DAMAGES OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY LOST PROFITS, LOST SAVINGS, OR ANY OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATED TO THE USE, INABILITY TO...

lib/DateTime/Calendar/Japanese.pm  view on Meta::CPAN

  $leap_month     = $dt->leap_month;
  $day            = $dt->day;
  $hour           = $dt->hour;
  $canonical_hour = $dt->canonical_hour
  $hour_quarter   = $dt->hour_quarter;

=head1 DESCRIPTION

This module implements the traditional Japanese Calendar, which was used
from circa 692 A.D. to 1867 A.D. The traditional Japanese Calendar is a
I<lunisolar calendar> based on the Chinese Calendar, and therefore
this module may *not* be used for handling or formatting modern Japanese
calendars which are Gregorian Calendars with a twist.
Please use DateTime::Format::Japanese for that purpose.

On top of the lunisolar calendar, this module implements a simple time
system used in the Edo period, which is a type of temporal hour system, 
based on sunrise and sunset.

=head1 CAVEATS/DISCLAIMERS

=head2 SPEED

This module is based on L<DateTime::Calendar::Chinese>, which in turn is
based on positions of the Moon and the Sun. Calculations of this sort is
definitely not Perl's forte, and therefore this module is *very* slow.

Help is much appreciated to rectify this :)

=head2 CALENDAR "VERSION"

Note that for each of these calendars there exist numerous different
versions/revisions. The Japanese Calendar has at least 6 different
revisions.

The Japanese Calendar that is implemented here uses the algorithm described
in the book "Calendrical Computations" [1], which presumably describes the
latest incarnation of these calendars.

=head2 ERA DISCREPANCIES FROM MODERN JAPANESE DATES

Even though this module can handle modern dates, note that this module
creates dates in the *traditional* calendar, NOT the modern gregorian
calendar used in Japane since the Meiji era. Yet, we must honor the gregorian
date in which an era started or ended. This means that the era year
calculations could be off from what you'd expect on a modern calendar.

For example, the Heisei era starts on 08 Jan 1989 (Gregorian), so in a 
modern calendar you would expect the rest of year 1989 to be Heisei 1.
However, the Chinese New Year happens to fall on 06 Feb 1989. Thus
this module would see that and increment the era year by one on that
date.

If you want to express modern Japanese calendars, you will need to use
L<DateTime::Format::Japanese> module on the vanilla DateTime object. 
(As of this writing DateTime::Format::Japanese is in alpha release. Use
at your own peril)

=head2 TIME COMPONENTS

The time component is based on the little that I already knew about the
traditional Japanese time system and numerous resources available on the net.

As for the Japanese time system, not much detail was available to me.

lib/DateTime/Calendar/Japanese.pm  view on Meta::CPAN

These constructors are exactly the same as those in DateTime::Calendar::Chinese

=head2 set

Sets DateTime components.

=head2 utc_rd_values

Returns the current UTC Rata Die days, seconds, and nanoseconds as a three
element list. This exists primarily to allow other calendar modules to create
objects based on the values provided by this object.

=head2 cycle

Returns the current cycle. See L<DateTime::Calendar::Chinese>

=head2 cycle_year

Returns the current cycle_year. See L<DateTime::Calendar::Chinese>

=head2 era

Returns the DateTime::Calendar::Japanese::Era object associated with this
calendar.

=head2 era_name

Returns the name (id) of the DateTime::Calendar::Japanese::Era object
associated with this calendar.

=head2 era_year

Returns the number of years in the current era, as calculated by the
traditional lunisolar calendar. Note that calculations will be different
from those based on the modern calendar, as the date of New Year (which is
when era years are incremented) differ from modern calendars. For example,
based on the traditional calendar, SHOUWA3 (1926 - 1989) had only 63 years,
not 64. See L<CAVEATS|/ERA DISCREPANCIES FROM MODERN JAPANESE DATES>

=head2 hour

Returns the hour, based on the traditional Japanese time system. The
hours are encoded from 1 to 12 to uniquely qulaify them. However, you
can get the canonical hour by using the canonical_hour() method

1 is the time of sunrise, somewhere around 5am to 6am, depending on the
time of the year (This means that hour 12 on a given date is actually BEFORE

lib/DateTime/Calendar/Japanese.pm  view on Meta::CPAN

under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

=head1 REFERENCES

  [1] Edward M. Reingold, Nachum Dershowitz
      "Calendrical Calculations (Millenium Edition)", 2nd ed.
       Cambridge University Press, Cambridge, UK 2002

  [2] http://homepage2.nifty.com/o-tajima/rekidaso/calendar.htm
  [3] http://www.tanomi.com/shop/items/wa_watch/index2.html
  [4] http://www.geocities.co.jp/Playtown/6757/edojikan01.html
  [5] http://www.valley.ne.jp/~ariakehs/Wadokei/hours_system.html

=head1 SEE ALSO

L<DateTime>
L<DateTime::Set>
L<DateTime::Span>
L<DateTime::Calendar::Chinese>