DateTime::Fiction::JRRTolkien::Shire - DateTime implementation of the Shire calendar.
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;
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.
Most of these methods mimic their corresponding DateTime methods in functionality. For additional information on these methods, see the DateTime documentation.
my $dt_ring = DateTime::Fiction::JRRTolkien::Shire->new( year => 1419, month => 3, day => 25, ); my $dt_aa = DateTime::Fiction::JRRTolkien::Shire->new( year => 1419, holiday => 3, # Midyear's day );
This method takes a year, month, and day parameter, or a year and holiday parameter. The year can be any value. The month can be specified with a string giving the name of the month (the same string that would be returned by month_name, with the first letter capitalized and the rest in lower case) or by giving the numerical value for the month, between 1 and 12. The day should always be between 1 and 30. If a holiday is given instead of a day and month, it should be the name of the holiday as returned by holiday_name (with the first letter of each word capitalized) or a value between 1 and 6. The 1 through 6 numbers map to holidays as follows:
1 => 2 Yule 2 => 1 Lithe 3 => Midyear's Day 4 => Overlithe # Leap years only 5 => 2 Lithe 6 => 1 Yule
The new method will also take parameters for hour, minute, second, nanosecond, time_zone and locale. If given, these parameters will be stored in case the object is converted to another class that supports times.
If a day is not given, it will default to 1. If neither a day or month is given, the date will default to 2 Yule, the first day of the year.
$dts = DateTime::Fiction::JRRTolkien::Shire->from_epoch( epoch => time, ... );
Same as in DateTime.
$dts = DateTime::Fiction::JRRTolkien::Shire->now( ... );
Same as in DateTime. Note that this is equivalent to
from_epoch( epoch => time() );
$dts = DateTime::Fiction::JRRTolkien::Shire->today( ... );
$dts = DateTime::Fiction::JRRTolkien::Shire->from_object( object => $object, ... );
Same as in DateTime. Takes any other DateTime calendar object and converts it to a DateTime::Fiction::JRRTolkien::Shire object.
$dts = DateTime::Fiction::JRRTolkien::Shire->last_day_of_month( year => 1419, month => 3, ... );
Same as in DateTime. Like the new() constructor, but it does not take a day parameter. Instead, the day is set to 30, which is the last day of any month in the shire calendar. A holiday parameter should not be used with this method. Use new() instead.
new()
$dts = DateTime::Fiction::JRRTolkien::Shire->from_day_of_year( year => 1419, day_of_year => 86, ... );
Same as in DateTime. Gets the date from the given year and day of year, both of which must be given. Hour, minute, second, time_zone, etc. parameters may also be given, and will be passed to the underlying DateTime object, just like in new().
$dts2 = $dts->clone();
Creates a new Shire object that is the same date (and underlying time) as the calling object.
print $dts->calendar_name(), "\n";
Returns 'Shire'.
'Shire'
print 'Year: ', $dts->year(), "\n";
Returns the year.
print 'Month: ', $dts->month(), "\n";
Returns the month number, from 1 to 12. If the date is a holiday, a 0 is returned for the month.
print 'Month name: ', $dts->month_name(), "\n";
Returns the name of the month. If the date is a holiday, an empty string is returned.
print 'Day of month: ', $dts->day_of_month(), "\n";
Returns the day of the current month, from 1 to 30. If the date is a holiday, 0 is returned.
Synonym for day_of_month().
print 'Day of week: ', $dts->day_of_week(), "\n";
Returns the day of the week from 1 to 7. If the day is not part of any week (Midyear's Day or the Overlithe), 0 is returned.
Synonym for day_of_week.
print 'Name of day of week: ', $dts->day_name(), "\n";
Returns the name of the day of the week, or an empty string if the day is not part of any week.
print 'Traditional name of day of week: ', $dts->day_name_trad(), "\n";
Like day_name, but returns the more traditional name of the days of the week, as defined in Appendix D.
print 'Day of year: ', $dts->day_of_year(), "\n";
Returns the day of the year, from 1 to 366
Synonym for day_of_year().
print 'Holiday number: ', $dts->holiday(), "\n";
Returns the holiday number (given in the description of the new() constructor). If the day is not a holiday, 0 is returned.
print 'Holiday name: ', $dts->holiday_name(), "\n";
Returns the name of the holiday. If the day is not a holiday, an empty string is returned.
my @ly = ( 'is not', 'is' ); printf "%d %s a leap year\n", $dts->year(), $ly[ $dts->is_leap_year() ];
Returns 1 if the year is a leap year, and 0 otherwise.
Leap years are given the same rule as the Gregorian calendar. Every four years is a leap year, except the first year of the century, which is not a leap year. However, every fourth century (400 years), the first year of the century is a leap year (every 4, except every 100, except every 400). This is a slight change from the calendar described in Appendix D, which uses the rule of once every 4 years, except every 100 years (the same as in the Julian calendar). Given some uncertainty about how many years have passed since the time in Lord of the Rings (see note below), and the expectations of most people that the years match up with what they're used to, I have changed this rule for this implementation. However, this does mean that this calendar implementation is not strictly that described in Appendix D.
print 'The week year is ', $dts->week_year(), "\n";
This is always the same as the year in the shire calendar, but is present for compatibility with other DateTime objects.
print 'The week number is ', $dts->week_number(), "\n";
Returns the week of the year, or 0 for days that are not part of any week: Midyear's day and the Overlithe.
0
printf "Year %d; Week number %d\n", $dts->week();
Returns a two element array, where the first is the week_year and the latter is the week_number.
print scalar gmtime $dts->epoch(), "UT\n";
Returns the epoch of the given object, just like in DateTime.
Returns the epoch as a floating point number, with the fractional portion for fractional seconds. Functions the same as in DateTime.
Returns the UTC rata die days, seconds, and nanoseconds. Ignores fractional seconds. This is the standard method used by other methods to convert the shire calendar to other calendars. See the DateTime documentation for more information.
Returns the UTC rata die days entirely as seconds.
Returns the current day, with day of week if present, and with all names in full. If the day has some events that transpired on it (as defined in Appendix B of the Lord of the Rings), those events are appended. This can be fun to put in a .bashrc or .cshrc. Try
perl -MDateTime::Fiction::JRRTolkien::Shire -le 'print DateTime::Fiction::JRRTolkien::Shire->now->on_date;'
$dts->set( month => 3, day => 25, );
Allows the day, month, and year to be changed. It takes any parameters allowed by new constructor, including all those supported by DateTime and the holiday parameter, except for time_zone. This is used in much the same way as new, with the exception that any parameters not given will be left as is.
All parameters are optional, with the current values inserted if the values are not supplied. However, with holidays not falling in any month, it is recommended that a day and month always be given together. Otherwise, unanticipated results may occur.
As in the new() constructor, time parameters have no effect on the shire dates returned. However, they are maintained in case the object is converted to another calendar which supports time.
$dts->truncate( to => 'day' );
Same as in DateTime. If the date is a holiday, truncation to 'month' is equivalent to truncation to 'day', and similar for holidays that are not part of any week. Otherwise, this functions as specified in the DateTime object.
'month'
'day'
$dts->set_time_zone( 'UTC' );
Just like in DateTime. This method has no effect on the shire calendar, but be stored with the date if it is ever converted to another calendar with time support.
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.
DateTime::Fiction::JRRTolkien::Shire
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 working 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.
http://www.glyphweb.com/arda/f/fourthage.html references a letter sent by Tolkien in 1958 in which he estimates approximately 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 the hobbits' calendar are every 4 years unless it is the turn of the century, in which case it is 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 hobbits' 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 thought, 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.
Tom Braun <tbraun@pobox.com>
Thomas R. Wyant, III wyant at cpan dot org
Copyright (c) 2003 Tom Braun. All rights reserved.
Copyright (C) 2017 Thomas R. Wyant, III
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.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. For more details, see the full text of the licenses in the LICENSES directory included with this module.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
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.
Tolkien, J. R. R. Return of the King. New York: Houghton Mifflin Press, 1955.
http://www.glyphweb.com/arda/f/fourthage.html
The DateTime project documentation (perldoc DateTime, datetime@perl.org mailing list, or http://datetime.perl.org/).
To install DateTime::Fiction::JRRTolkien::Shire, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Fiction::JRRTolkien::Shire
CPAN shell
perl -MCPAN -e shell install DateTime::Fiction::JRRTolkien::Shire
For more information on module installation, please visit the detailed CPAN module installation guide.