Tom Braun > DateTime-Fiction-JRRTolkien-Shire-0.02 > DateTime::Fiction::JRRTolkien::Shire

Download:
DateTime-Fiction-JRRTolkien-Shire-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

DateTime::Fiction::JRRTolkien::Shire.pm

SYNOPSIS ^

    use DateTime::Fiction::JRRTolkien::Shire;

    # Constructors
    my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419,
                                                          month => 'Rethe',
                                                          day => 25);
    my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419,
                                                          month => 3,
                                                          day => 25);
    my $shire = DateTime::Fiction::JRRTolkien::Shire->new(year => 1419,
                                                          holiday => '2 Lithe');

    my $shire = DateTime::Fiction::JRRTolkien::Shire->from_epoch(epoch = $time);
    my $shire = DateTime::Fiction::JRRTolkien::Shire->today; # same as from_epoch(epoch = time());

    my $shire = DateTime::Fiction::JRRTolkien::Shire->from_object(object => $some_other_DateTime_object);
    my $shire = DateTime::Fiction::JRRTolkien::Shire->from_day_of_year(year => 1420,
                                                                       day_of_year => 182);
    my $shire2 = $shire->clone;

    # Accessors
    $year = $shire->year;
    $month = $shire->month;            # 1 - 12, or 0 on a holiday
    $month_name = $shire->month_name;
    $day = $shire->day;                # 1 - 30, or 0 on a holiday

    $dow = $shire->day_of_week;        # 1 - 7, or 0 on certain holidays
    $day_name = $shire->day_name;

    $holiday = $shire->holiday;
    $holiday_name = $shire->holiday_name;

    $leap = $shire->is_leap_year;

    $time = $shire->epoch;
    @rd = $shire->utc_rd_values;

    # Set Methods
    $shire->set(year => 7463,
                month => 5,
                day => 3);
    $shire->set(year => 7463,
                holiday => 6);
    $shire->truncate(to => 'month');

    # Comparisons
    $shire < $shire2;
    $shire == $shire2;

    # Strings
    print "$shire1\n"; # Prints Sunday 25 Rethe 1419

    # On this date in history
    print $shire->on_date;

DESCRIPTION ^

Implementation of the calendar used by the hobbits in J.R.R. Tolkien's exceptional novel The Lord of The Rings, as described in Appendix D of that book (except where noted). The calendar has 12 months, each with 30 days, and 5 holidays that are not part of any month. A sixth holiday, Overlithe, is added on leap years. The holiday Midyear's Day (and the Overlithe on a leap year) is not part of any week, which means that the year always starts on Sterday.

This module is a follow on to the Date::Tolkien::Shire module, and is rewritten to support Dave Rolsky and company's DateTime module. The DateTime module must be installed for this module to work. Unlike the DateTime module, which includes time support, this calendar does not have any mechanisms for giving a shire time (mostly because I've never quite figured out what it should look like). Time is maintained, however, so that objects can be converted from other calendars to the shire calendar and then converted back without their time components being lost. The same is true of time zones.

METHODS ^

Most of these methods mimic their corresponding DateTime methods in functionality. For additional information on these methods, see the DateTime documentation.

Constructors

Get Methods

Set Methods

Comparisons and Stringification

All comparison operators should work, just as in DateTime. In addition, all DateTime::Fiction::JRRTolkien::Shire objects will interpolate into a string representing the date when used in a double-quoted string.

DURATIONS AND DATE MATH ^

Durations and date math (other than comparisons) are not supported at present on this module (patches are always welcome). If this is needed, there are a couple of options. If workig with dates within epoch time, the dates can be converted to epoch time, the math done, and then converted back. Regardless of the dates, the shire objects can also be converted to DateTime objects, the math done with the DateTime class, and then the DateTime object converted back to a Shire object.

NOTE: YEAR CALCULATION ^

http://www.glyhweb.com/arda/f/fourthage.html references a letter sent by Tolkien in 1958 in which he estimates approxiimately 6000 years have passed since the War of the Ring and the end of the Third Age. (Thanks to Danny O'Brien from sending me this link). I took this approximate as an exact amount and calculated back 6000 years from 1958. This I set as the start of the 4th age (1422 S.R.). Thus the fourth age begins in our B.C 4042.

According to Appendix D of the Lord of the Rings, leap years in hobbit calendar are every 4 years unless its the turn of the century, in which case it's not a leap year. Our calendar (Gregorian) uses every 4 years unless it's 100 years unless its 400 years. So, if no changes have been made to the hobbit's calendar since the end of the third age, their calendar would be about 15 days further behind ours now then when the War of the Ring took place. Implementing this seemed to me to go against Tolkien's general habit of converting dates in the novel to our equivalents to give us a better sense of time. My thoughts, at least right now, is that it is truer to the spirit of things for years to line up, and for Midyear's day to still be approximately on the summer solstice. So instead, I have modified Tolkien's description of the hobbit calendar so that leap years occur once every 4 years unless it's 100 years unless it's 400 years, so as it matches the Gregorian calendar in that regard. These 100 and 400 year intervals occur at different times in the two calendars, so there is not a one to one correspondence of days regardless of years. However, the variations follow a 400 year cycle.

AUTHOR ^

Tom Braun <tbraun@pobox.com>

LICENSE AND COPYRIGHT ^

Copyright (c) 2003 Tom Braun. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The calendar implemented on this module was created by J.R.R. Tolkien, and the copyright is still held by his estate. The license and copyright given herein applies only to this code and not to the calendar itself.

The full text of the license can be found in the LICENSE file included with this module.

SUPPORT ^

Support on this module may be obtained by emailing me. However, I am not a developer on the other classes in the DateTime project. For support on them, please see the support options in the DateTime documentation.

BIBLIOGRAPHY ^

Tolkien, J. R. R. <i>Return of the King<i>. New York: Houghton Mifflin Press, 1955.

http://www.glyphweb.com/arda/f/fourthage.html

SEE ALSO ^

The DateTime project documentation (perldoc DateTime, datetime@perl.org mailing list, or http://datetime.perl.org/).

syntax highlighting: