Date::Tolkien::Shire::Data(3)

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:

":all" - export everything;
":consts" - export all manifest constants;
":subs" - export all subroutines.

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 0 to 12, with 0 indicating a holiday.

__fmt_shire_day
    This method returns the day of the month in the range 1 to 30, or the holiday number in the range 1 to 6.

__fmt_shire_hour
    This method returns the hour in the range 0 to 23.

__fmt_shire_minute
    This method returns the minute in the range 0 to 59.

__fmt_shire_second
    This method returns the second in the range 0 to 61.

__fmt_shire_day_of_week
    This method returns the day of the week as a number in the range 0 to 7, with 0 indicating 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, or "undef" is 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:OO 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 01 to 30). On holidays it is the holiday number, zero-filled (range 01 to 06).

%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 $date object 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 );  # 1

Given 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 am 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 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
Date::Tolkien::Shire

DateTime::Fiction::JRRTolkien::Shire

SUPPORT
Support is by the author. Please file bug reports at <http://rt.cpan.org>, or in electronic mail to the author.

AUTHOR
Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE
Copyright (C) 2017-2018 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.