NAME
Date::Tolkien::Shire::Data - Data functionality for Shire calendars.
SYNOPSIS
use Date::Tolkien::Shire::Data;
say __on_date( 1, 2 ) // "Nothing happened\n";DESCRIPTION
This Perl module carries common functionality for implementations of the Shire calendar as described in Appendix D of J. R. R. Tolkien's novel "Lord Of The Rings". What it really contains is anything that was common to Date::Tolkien::Shire and DateTime::Fiction::JRRTolkien::Shire and I felt like factoring out. You probably do not want to use this module directly, at least not without looking into the other two.
The Shire calendar has 12 months of 30 days each, plus 5 holidays (6 in a leap year) that are not part of any month. Two of these holidays (Midyear's day and the Overlithe) are also part of no week.
In all of the following, years are counted from the founding of the Shire. Months are numbered 1-12, and days in months from 1-30. Holidays are specified by giving a month of 0 and the holiday number, as follows:
- 1 - 2 Yule
- 2 - 1 Lithe
- 3 - Midyear's day
- 4 - Overlithe (which occurs in leap years only)
- 5 - 2 Lithe (so numbered even in non-leap years)
- 6 - 1 Yule
This module is subroutine-based. Nothing is exported by default, but everything public can be exported by name. In addition the following export tags exist:
SUBROUTINES
This class supports the following public subroutines. Anything documented below is public unless its documentation explicitly states otherwise. The names begin with double underscores because it is anticipated that, although they are public as far as this package is concerned, they will be package-private for the purposes of any code that uses this package.
All of the following are exportable to your name space, but none are exported by default. They can all be exported using export tag :subs.
__am_or_pm
This subroutine takes as input an hour of the day in the range 0 to 23 and returns 'AM' if the hour is less than 12, or 'PM' otherwise.
__date_to_day_of_year
say __date_to_day_of_year( 1420, 3, 25 );This subroutine takes as input a year, month, and day and returns the day number in the year. An exception will be thrown if you specify the Overlithe ("month" 0, day 4) and it is not a leap year.
__day_of_week
say '3 Astron is day ', __day_of_week( 4, 3 );Given a month number and day number in the month, computes the day of the week that day falls on, as a number from 1 to 7, 1 being Sterday. If the day is Midyear's day or the Overlithe (month 0, days 3 or 4) the result is 0.
__day_of_year_to_date
my ( $month, $day ) = __day_of_year_to_date( 1419, 182 );Given a year and a day number in the year (from 1), compute the month and day of month. An exception will be thrown unless the day number is between 1 and 365, or 366 in a leap year.
__format
say __format( $date, $pattern );This method formats a date, in a manner similar to strftime(). The $date is either an object that supports the necessary methods, or a reference to a hash having the necessary keys (same as the methods). The $pattern is a string similar to the conversion specification passed to POSIX::strftime(); see below for a fuller description.
The $date methods used are:
- __fmt_shire_year
-
This method returns the Shire year, as a number.
- __fmt_shire_month
-
This method returns the Shire month as a number in the range
0to12, with0indicating a holiday. - __fmt_shire_day
-
This method returns the day of the month in the range
1to30, or the holiday number in the range1to6. - __fmt_shire_hour
-
This method returns the hour in the range
0to23. - __fmt_shire_minute
-
This method returns the minute in the range
0to59. - __fmt_shire_second
-
This method returns the second in the range
0to61. - __fmt_shire_day_of_week
-
This method returns the day of the week as a number in the range
0to7, with0indicating that the day is not part of any week. - __fmt_shire_nanosecond
-
This method returns the nanosecond (of the second) as a number.
- __fmt_shire_epoch
-
This method returns the seconds since the epoch, as a number.
- __fmt_shire_zone_offset
-
This method returns the seconds the current time zone is offset from
UTC, as a number, orundefis the offset is undefined. - __fmt_shire_zone_name
-
This method returns the name of the current time zone, or
''if the zone is undefined. - __fmt_shire_accented
-
This method returns a true value if __on_date() format is to be accented.
- __fmt_shire_traditional
-
This method returns a true value if traditional weekday names are to be used.
If you pass a hash, the keys are the above method names without the leading '__fmt_shire_' (i.e. 'year', 'month', and so on). The year must be specified; everything else defaults, generally to 0, although day_of_week, if unspecified, will be computed from the date.
The following conversion specifications (to use strftime() terminology) or patterns (to use DateTime terminology) are supported. Note that these have been extended by the use of '%E*' patterns, which generally represent holidays. E-prefixed patterns not defined below are (consistent with strftime()) implemented as if the 'E' were not present, but this use is discouraged because additional E-prefixed (or O-prefixed, which strftime() also allows) patterns may prove to be necessary.
- %A
-
The full weekday name, or
''for holidays that are part of no week. - %a
-
The abbreviated weekday name, or
''for holidays that are part of no week. - %B
-
The full month name, or
''for holidays. - %b
-
The abbreviated month name, or
''for holidays. - %C
-
The century number (year/100) as a 2-digit integer.
- %c
-
For normal days this is the abbreviated weekday name (
'%a'), the day number ('%e'), the abbreviated month name (%b), and the full year ('%Y'), followed by the time of day.For holidays the abbreviated holiday name (
'%Ee') replaces the day and month, and the weekday name is omitted if the holiday is part of no week. So (assuming times for all events):Sun 25 Ret 1419 3:00:00 PM # Ring destroyed Myd 1419 12:00:00 PM # Wedding of Aragorn and Arwen - %D
-
The equivalent of
'%m/%d/%y', or'%Ee/%y'on holidays. This format is discouraged, because it may not be clear whether it is month/day/year (as the United States does it) or day/month/year (as Europe does it). - %d
-
The day of the month as a decimal number, zero-filled (range
01to30). On holidays it is the holiday number, zero-filled (range01to06). - %Ea
-
The narrow (2-character) weekday name, or
''for holidays that are part of no week. - %Ed
-
The __on_date() text for the given date.
You can get a leading
"\n"if there was an actual event using'%En%Ed'. So to mimic Date::Tolkien::Shire on_date(), use'%Ex%n%En%Ed'. - %EE
-
The full holiday name, or
''for non-holidays. - %Ee
-
The abbreviated holiday name, or
''for non-holidays. - %En
-
Inserts nothing, but causes the next
%Ed(and only the next one) to have a"\n"prefixed if there was an actual event on the date. - %Eo
-
The narrow (2-character) holiday name, or
''for non-holidays. - %Ex
-
Like
'%c', but without the time of day, and with full names rather than abbreviations. - %e
-
The day of the month as a decimal number, space-filled (range
' 1'to'30'). On holidays it is the holiday number, space-filled (range' 1'to' 6'). - %F
-
For normal dates this is equivalent to
'%Y-%m-%d'(i.e. the ISO 8601 date format). For holidays it is equivalent to'%Y-%Er', which is something ISO had nothing to do with. - %G
-
The ISO 8601 year number. Given how the Shire calendar is defined, the ISO year number is the same as the calendar year (i.e.
'%Y'). - %H
-
The hour, zero-filled, in the range
'00'to'23'. - %h
-
Equivalent to
'%b'. - %I
-
The hour, zero-filled, in the range
'01'to'12'. - %j
-
The day of the year, zero-filled, in the range
'001'to'366'. - %k
-
The hour, blank-filed, in the range
' 0'to'23'. - %l
-
The hour, blank-filled, in the range
' 1'to'12'. - %M
-
The minute, zero-filled, in the range
'00'to'59'. - %m
-
The month number, zero filled, in the range
'01'to'12'. On holidays it is'00'. - %N
-
The fractional seconds. A decimal digit may appear between the percent sign and the
'N'to specify the precision:'3'gives milliseconds,'6'microseconds, and'9'nanoseconds. The default is'9'. - %n
-
A newline character.
- %P
-
The meridian indicator,
'am'or'pm'. - %p
-
The meridian indicator,
'AM'or'PM'. - %R
-
The time in hours and minutes, on a 24-hour clock. Equivalent to
'%H:%M'. - %r
-
The time in hours, minutes and seconds on a 12-hour clock. Equivalent to
'%I:%M:%S %p'. - %S
-
The second, zero-filled, in the range
'00'to'61', though only to'59'unless you are dealing with times when the leap second has been invented. - %s
-
The number of seconds since the epoch.
- %T
-
The time in hours, minutes and seconds on a 24-hour clock. Equivalent to
'%H:%M:%S'. - %t
-
A tab character.
- %U
-
The week number in the current year, zero-filled, in the range
'01'to'52', or''if the day is not part of a week. - %u
-
The day of the week, as a number in the range
'1'to'7', or''if the day is not part of a week. - %V
-
I have made this the same as
'%U', because all Shire years start on the same day of the week, and I do not think the hobbits would understand or condone the idea of different starting days to a week. - %v
-
This is from the BSD version of strftime(), and is equivalent to
'%{{%e %b %Y||%Ee %Y}}'. - %W
-
I have made this the same as
'%U'. For my reasoning, see above under'%V'. - %w
-
I have made this the same as
'%u', my argument being similar to the argument for making'%V'the same as'%U'. - %X
-
I have made this the same as
'%r'. We know the hobbits had clocks, because in "The Hobbit" Thorin Oakenshield left Bilbo Baggins a note under the clock on the mantelpiece. We know they spoke of time as "o'clock" because in the chapter "Of Herbs and Stewed Rabbit" in "The Lord Of The Rings", Sam Gamgee speaks of the time as being nine o'clock. But this was in the morning, and we have no evidence that I know of whether mid-afternoon would be three o'clock or fifteen o'clock. But my feeling is for the former. If I get evidence to the contrary this implementation will change. - %x
-
I have made this day, abbreviated month, and full year. Holidays are abbreviated holiday name and year.
- %Y
-
The year number.
- %y
-
Year of century, zero filled, in the range
'00'to'99'. - %Z
-
The time zone abbreviation.
- %z
-
The time zone offset.
- %%
-
A literal percent sign.
- %{
-
A literal left curly bracket.
- %}
-
A literal right curly bracket.
- %|
-
A literal vertical bar.
- %{method_name}
-
Any method actually implemented by the
$dateobject can be specified. This method will be called without arguments and its results replace the conversion specification. If the method does not exist, the pattern is left as-is. - %{{format||format||format}}
-
The formatter chooses the first format for normal days (i.e. part of a month), the second for holidays that are part of a week (i.e. 2 Yule, 1 Lithe, 2 Lithe and 1 Yule), or the third for holidays that are not part of a week (i.e. Midyear's day and the Overlithe). If the second or third formats are omitted, the preceding format is used. Trailing
||operators can also be omitted. If you need to specify more than one right curly bracket or vertical bar as part of a format, separate them with percent signs (i.e.'|%|%|').
Some of the Glibc extensions are implemented on some of the conversion specifications, typically where the author felt a need for them. The following flag characters may be specified immediately after the '%':
- - (dash)
-
This flag specifies no padding at all. That is to say, on the first of the month, both
'%-d'and'%-e'produce'1', not'01'or' 1'respectively.If an explicit field width is specified (see below), this specifies space padding.
- _ (underscore)
-
This flag specifies padding with spaces. That is to say, on the first of the month,
'%_d'produce' 1', not'01'. So does'%_e', in case you were wondering. - 0 (zero)
-
This flag specifies padding with zeroes. That is to say, on the first of the month,
'%0e'produce'01', not' 1'. So does'%0d', in case you were wondering. - ^
-
This flag specifies making the result upper-case.
- #
-
If applied to
'%p'or'%Z', this flag converts the output to lower case. It also overrides the'^'flag if both are specified, regardless of order.If applied to
'%A','%a','%B','%b','%EE','%Ee', or'%h', this flag converts the output to upper case.If applied to anything else, this flag has no effect.
Immediately after the flags (if any) you can specify a field width that overrides the default. If you explicitly specify field width, flag '-' pads with spaces, even in numeric fields.
__holiday_abbr
say __holiday_abbr( 3 );Given a holiday number (1-6), this subroutine returns that holiday's three-letter abbreviation. If the holiday number is 0 (i.e. the day is not a holiday), an empty string is returned. Otherwise, undef is returned.
__holiday_name
say __holiday_name( 3 );Given a holiday number (1-6), this subroutine returns that holiday's name. If the holiday number is 0 (i.e. the day is not a holiday), an empty string is returned. Otherwise, undef is returned.
__holiday_name_to_number
say __holiday_name_to_number( 'overlithe' );Given a holiday name, this subroutine normalizes it by converting it to lower case and removing spaces and punctuation, and then returns the number of the holiday. Unique abbreviations of names or short names (a.k,a. abbreviations) are allowed. Arguments consisting entirely of digits are returned unmodified. Anything unrecognized causes 0 to be returned.
__holiday_narrow
say __holiday_narrow( 3 );Given a holiday number (1-6), this subroutine returns that holiday's two-letter abbreviation. If the holiday number is 0 (i.e. the day is not a holiday), an empty string is returned. Otherwise, undef is returned.
__is_leap_year
say __is_leap_year( 1420 ); # 1Given a year number, this subroutine returns 1 if it is a leap year and 0 if it is not.
__month_name
say __month_name( 3 );Given a month number (1-12), this subroutine returns that month's name. If the month number is 0 (i.e. a holiday), the empty string is returned. Otherwise undef is returned.
__month_name_to_number
say __month_name_to_number( 'forelithe' );Given a month name, this subroutine normalizes it by converting it to lower case and removing spaces and punctuation, and then returns the number of the month. Unique abbreviations of names or short names (a.k,a. abbreviations) are allowed. Arguments consisting entirely of digits are returned unmodified. Anything unrecognized causes 0 to be returned.
__month_abbr
say __month_abbr( 3 );Given a month number (1-12), this subroutine returns that month's three-letter abbreviation. If the month number is 0 (i.e. a holiday), the empty string is returned. Otherwise undef is returned.
__on_date
say __on_date( $month, $day ) // '';
say __on_date( $holiday ) // '';Given month and day numbers (or a holiday number), returns text representing the events during and around the War of the Ring that occurred on that date. If nothing happened or any argument is out of range, undef is returned.
The actual text returned is from Appendix B of "Lord Of The Rings", and is copyright J. R. R. Tolkien, renewed by Christopher R. Tolkien et al. Specifically, I use the Houghton Mifflin trade paperback. I find no date of publication, but believe it to be the early 2000s because the cover illustrations appear to be movie tie-ins.
__on_date_accented
binmode STDOUT, ':encoding(utf-8)';
say __on_date_accented( $month, $day ) // '';
say __on_date( $holiday ) // '';This wrapper for __on_date() accents those names and words that are accented in the text of the Lord Of The Rings. How these display depends on how your Perl is configured. Note that the example above assumes Perl 5.10 (for say() and //). Even without those, the two-argument binmode() requires 5.8. Your mileage may vary.
Note that the first call incurs the overhead of accenting all events.
__quarter
say __quarter( $month, $day );Given month and day numbers, returns the relevant quarter number. If the date specified is Midyear's day or the Overlithe ("month" 0, days 3-4), the result is 0; otherwise it is a number in the range 1-4.
There is nothing I know of about hobbits using calendar quarters in anything Tolkien wrote. But if they did use them I suspect they would be rationalized this way.
__quarter_name
Given the quarter number, return the name of the quarter. If the quarter number is 0 (i.e. Midyear's day or Overlithe), '' is returned.
__quarter_abbr
Given the quarter number, return the abbreviated name of the quarter. If the quarter number is 0 (i.e. Midyear's day or Overlithe), '' is returned.
__rata_die_to_year_day
my ( $year, $day ) = __rata_die_to_year_day( $rata_die );Given a Rata Die day, returns the year and day of the year corresponding to that Rata Die day.
The algorithm used was inspired by Howard Hinnant's "chrono-Compatible Low-Level Date Algorithms" at http://howardhinnant.github.io/date_algorithms.html, and in particular his civil_from_days() algorithm at http://howardhinnant.github.io/date_algorithms.html#civil_from_days.
This subroutine assumes no particular calendar, though it does assume the Gregorian year-length rules, which have also been adopted for the Shire calendar. If you feed it an honest-to-God Rata Die day (i.e. days since December 31 of proleptic Gregorian year 0) you get back the Gregorian year and the day of that year (1-366). If you feed it a so-called Shire Rata Die (i.e. days since 1 Yule of Shire year 0) you get back the Shire year and the day of that year.
__trad_weekday_name
say 'Day 1 is ', __trad_weekday_name( 1 );This subroutine computes the traditional (i.e. old-style) name of a weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__trad_weekday_abbr
say 'Day 1 is ', __trad_weekday_abbr( 1 );This subroutine computes the three-letter abbreviation of a traditional (i.e. old-style) weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__trad_weekday_narrow
say 'Day 1 is ', __trad_weekday_narrow( 1 );This subroutine computes the two-letter abbreviation of a traditional (i.e. old-style) weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__valid_date_class
eval {
__valid_date_class( $class );
print "$class OK\n";
1;
} or print $@;This subroutine takes as its argument either an object or a class name. If a class name, it is loaded if needed and possible. Then the class is checked to see if it has all the methods required of a date object passed to __format(). If any missing methods are found an exception is thrown naming the missing methods; otherwise it returns its argument.
If you intend to use a class that autoloads requisite methods, that class will need to properly override UNIVERSAL->can(), or provide forward references to autoloaded methods.
This subroutine is used internally to validate the date argument to __format(). It is exposed for troubleshooting purposes. See also tools/valid-date-class.
__weekday_name
say 'Day 1 is ', __weekday_name( 1 );This subroutine computes the name of a weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__weekday_abbr
say 'Day 1 is ', __weekday_abbr( 1 );This subroutine computes the three-letter abbreviation of a weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__weekday_narrow
say 'Day 1 is ', __weekday_narrow( 1 );This subroutine computes the two-letter abbreviation of a weekday given its number (1-7). If the weekday number is 0 (i.e. Midyear's day or the Overlithe) the empty string is returned. Otherwise, undef is returned.
__week_of_year
say '25 Rethe is in week ', __week_of_year( 3, 25 );This subroutine computes the week number of the given month and day. Weeks start on Sterday, and the first week of the year is week 1. If the date is part of no week (i.e. Midyear's day or the Overlithe), 0 is returned.
__year_day_to_rata_die
my $rata_die = __year_day_to_rata_die(
$year, $day_of_year );Given the year and day of the year, this subroutine returns the Rata Die day of the given year and day. The day of the year defaults to 1.
This subroutine assumes no particular calendar, though it does assume the Gregorian year-length rules, which have also been adopted for the Shire calendar. If you feed it a Gregorian year, you get an honest-to-God Rata Die, as in days since December 31 of proleptic Gregorian year 0. If you feed it a Shire year, you get a so-called Shire Rata Die, as in the days since 1 Yule of Shire year 0.
MANIFEST CONSTANTS
The following manifest constants are exportable to your name space. None is exported by default. They can all be exported using export tag :consts.
DAY_OF_YEAR_MIDYEARS_DAY
This manifest constant represents the day number of Midyear's day in the year, i.e. 183.
DAY_OF_YEAR_OVERLITHE
This manifest constant represents the day number of Overlithe in the year, i.e. 184. Be aware that day 184 is Overlithe only in a leap year; otherwise day 184 is 2 Lithe.
GREGORIAN_RATA_DIE_TO_SHIRE
This manifest constant represents the number of days to add to a real Rata Die value (days since December 31 of proleptic Gregorian year 0) to get a so-called Shire Rata Die (days since 1 Yule of Shire year 0.)
The value was determined by the following computation.
my $dts = DateTime::Fiction::JRRTolkien::Shire->new(
year => 1,
holiday => 1,
);
my $gdt = DateTime->new(
year => 1,
month => 1,
day => 1,
);
my $rd_to_shire = ( $gdt->utc_rd_values() )[0] -
( $dts->utc_rd_values() )[0];using DateTime::Fiction::JRRTolkien::Shire version 0.21. This is after I adopted that module but before I started messing with the computational internals.
HOLIDAY_2_YULE
This manifest constant represents the holiday number of <2 Yule>, i.e. 1.
HOLIDAY_1_LITHE
This manifest constant represents the holiday number of <1 Lithe>, i.e. 2.
HOLIDAY_MIDYEARS_DAY
This manifest constant represents the holiday number of <Midyear's day>, i.e. 3.
HOLIDAY_OVERLITHE
This manifest constant represents the holiday number of <Overlithe>, i.e. 4.
HOLIDAY_2_LITHE
This manifest constant represents the holiday number of <2 Lithe>, i.e. 5.
HOLIDAY_1_YULE
This manifest constant represents the holiday number of <1 Yule>, i.e. 6.
SEE ALSO
DateTime::Fiction::JRRTolkien::Shire
SUPPORT
Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Date-Tolkien-Shire-Data, https://github.com/trwyant/perl-Date-Tolkien-Shire-Data/issues, or in electronic mail to the author.
AUTHOR
Thomas R. Wyant, III wyant at cpan dot org
COPYRIGHT AND LICENSE
Copyright (C) 2017-2021 by Thomas R. Wyant, III
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.
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.