DateTime::Calendar::Japanese - DateTime Extension for Traditional Japanese Calendars
use DateTime::Calendar::Japanese; # Construct a DT::C::Japanese object using the Chinese hexagecimal # cycle system my $dt = DateTime::Calendar::Japanese->new( cycle => $cycle, cycle_year => $cycle_year, month => $month, leap_month => $leap_month, day => $day, hour => $hour, hour_quarter => $hour_quarter ); # Construct a DT::C::Japanese object using the era system use DateTime::Calendar::Japanese::Era qw(HEISEI); my $dt = DateTime::Calendar::Japanese->new( era_name => HEISEI, era_year => $era_year, month => $month, leap_month => $leap_month, day => $day, hour => $hour, hour_quarter => $hour_quarter ); $cycle = $dt->cycle; $cycle_year = $dt->cycle_year; $era = $dt->era; # era object $era_name = $dt->era_name; $era_year = $dt->era_year; $month = $dt->month; $leap_month = $dt->leap_month; $day = $dt->day; $hour = $dt->hour; $canonical_hour = $dt->canonical_hour $hour_quarter = $dt->hour_quarter;
The traditional Japanese Calendar, which was used from circa 692 A.D. to 1867 A.D., is based on the Chinese Calendar. The traditional Chinese Calendar is a lunisolar calendar based on exact astronomical events.
Note that for each of these calendars there exist numerous different versions/revisions. The Japanese Calendar has at least 6 different revisions.
Even though this module can handle modern dates, note that this module creates dates in the *traditional* calendar, NOT the modern gregorian calendar used now. For example the following date is NOT equivalent to Jan 1, 2004:
DateTime::Calendar::Japanese->new( era_name => HEISEI, era_year => 16, month => 1, day => 1 );
The above being a month 1 day 1 on a lunisolar calendar, it's actually some date in Feb. 2004. (XXX - I might get around to writing DT::Format::Japanese)
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. 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. I searched in various resources on the net and used a combined alogorithm (see "REFERENCES") to produce what seemed logical (and simple enough for me) to emulate the time system implemented in this module is from the one used during the Edo period (1600's - 1800's).
If there are any corrections, please let me know.
Eras are a unique system that are used widely through Asia (XXX - This is unconfirmed, but I believe Japan is one of the only countries that uses
The time system that is implemented in this module is the time system used in the Edo era, during the time of the Tokugawa shogunate (1603 - 1867).
This time system is completely unlike the ones we are used in the modern world, mainly in that the notion of an "hour" changes from season to season. The days were divided in to two parts, from sunrise to sunset, and from sunset to sunrise. Each of these parts were then divided into 6 equal parts.
This also means that an "hour" has a different length depending on the season, and it even differs between day and night. However, for those people with no watches or clocks, it's sometimes more convenient because the position of the sun directly corelates to the time of the day.
Even more complicated to us is the fact that Japanese hours have a slightly complex numbering scheume. The hours do not start from 1. Instead, the hour that starts with the sunrise is hour "6", then "5", "4", and then "9", all the way back to "6". Each of these hours also have a corresponding name, which is based on the Chinese Zodiac.
------------------ | Hour | Zodiac | ------------------ | 6 | Hare | <-- Sunrise --- ------------------ | | 5 | Dragon | | ------------------ | | 4 | Snake | | ------------------ |---- Day | 9 | Horse | | ------------------ | | 8 | Sheep | | ------------------ | | 7 | Monkey |---------------- ------------------ | 6 | Fowl | <-- Sunset ---- ------------------ | | 5 | Dog | | ------------------ | | 4 | Pig | | ------------------ |---- Night | 9 | Rat | | ------------------ | | 8 | Ox | | ------------------ | | 7 | Tiger |---------------- ------------------
These names are used standalone or sometimes interchangeably. For example, "ne no koku" literary means "the hour of hare", but you can also say "ake mutsu" which means "morning 6".
For computational purposes, DateTime::Calendar::Japanese will number the hours 1 to 12. (You can get the canonical representation by using the canonical_hour() method)
Each hour is further broken up in 4 parts, which is combined with the hour notation to express a more precise time, for example:
hour of Ox, 3rd quarter (around 3 a.m.)
There are two forms to the constructor. One form accepts "era" and "era_year" to define the year, and the other accepts "cycle" and "cycle_year". The rest of the parameters are the same, and they are: "month", "leap_month", "day", "hour", "hour_quarter".
use DateTime::Calendar::Japanese; use DateTime::Calendar::Japanese::Era qw(TAIKA); my $dt = DateTime::Calendar::Japanese->new( era => TAIKA, era_year => 1, month => 7, day => 25, hour => 4, hour_quarter => 3 ); # DateTime::Calendar::Chinese style my $dt = DateTime::Calendar::Japanese->new( );
These constructors are exactly the same as those in DateTime::Calendar::Chinese
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.
Returns the current cycle. See DateTime::Calendar::Chinese
Returns the current cycle_year. See DateTime::Calendar::Chinese
Returns the DateTime::Calendar::Japanese::Era object associated with this calendar.
Returns the name (id) of the DateTime::Calendar::Japanese::Era object associated with this calendar.
Returns the number of years in the current era. 08 Jan 1989 is the start of "Heisei" era, so 08 Jan 1989 to 31 Dec 1989 is Heisei 1. 01 Jan 1990 to 31 Dec 1990 is Heisei 2, etc.
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
Returns the canonical hour, based on the numbering system described in the above section, which counts from 9 to 4, and back to 9.
Returns the quarter in the current hour (1 to 4).
Currently assumes that the sunrise/sunset hours are calculated based on Tokyo latitude/longitude.
Daisuke Maki <daisuke@cpan.org>
[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
DateTime DateTime::Set DateTime::Span DateTime::Calendar::Chinese DateTime::Calendar::Japanese::Era DateTime::Event::Sunrise
To install DateTime::Calendar::Japanese, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Calendar::Japanese
CPAN shell
perl -MCPAN -e shell install DateTime::Calendar::Japanese
For more information on module installation, please visit the detailed CPAN module installation guide.