view release on metacpan or  search on metacpan

lib/Date/Tolkien/Shire.pm  view on Meta::CPAN

    $shiredate = Date::Tolkien::Shire->today();

This convenience constructor returns an object set to midnight the
morning of the current local day.

The optional arguments for L<new()|/new> may also be used here.

=head2 from_shire

    $shiredate = Date::Tolkien::Shire->from_shire(
        year    => 1419,
        month   => 3,
        day     => 25,
    );
    $shiredate = Date::Tolkien::Shire->from_shire(
        year    => 1419,
        holiday => 3,
    );

This convenience constructor just wraps a call to C<new()> followed by a
call to C<set_shire()>.

The optional arguments for L<new()|/new> may also be used here.

=head2 set_date

This method takes either the seconds from the start of the epoch (like
what C<time()> returns) or another shire date object, and sets the date
of the object in question equal to that date.  If the object previously
contained a date, it will be overwritten.  Local time, rather than UTC,
is used in converting from epoch date.

Please see the note below on calculating the year if you're curious how
I arrived by that.

=head2 set_rata_die

    $shiredate->set_rata_die( $datetime->utc_rd_values() );

This method takes a date in days since December 31 of Gregorian year 0,
and sets the date of the invocant to that date. Only the first argument
is used, but others, if provided, should be consistent with the output
of the L<DateTime|DateTime> C<utc_rd_values()>, to save trouble in the
(probably unlikely) event that I add time-of-day functionality to this
package.

=head2 set_shire

    $shiredate->set_shire(
        year    => 1418,
        month	=> 3,
        day     => 25,
    );
    $shiredate->set_shire(
        year    => 1419,
        holiday => 3,
    );

This method sets the object's date to the given date in the Shire
calendar. The named arguments are C<year>, C<month>, C<day>, and
C<holiday>, and all are numeric. The C<year> argument is required; all
others are optional. You may not specify both C<month> and C<holiday>.
If C<month> is specified, C<day> defaults to C<1>; otherwise C<holiday>
defaults to C<1>.

This method returns the invocant. Errors are indicated by setting the
C<$ERROR> variable.

=head2 set_accented

This method takes a Boolean value which determines whether
L<on_date()|/on_date> should produce accented output. It returns the
invocant.

=head2 set_traditional

This method takes a Boolean value which determines whether
L<on_date()|/on_date> should use traditional rather than common names
for the days of the week. It returns the invocant.

=head2 time_in_seconds

    $epoch_time = $shire_date->time_in_seconds

Returns the epoch time (with 0 for hours, minutes, and seconds) of
a given shire date. This relies on the library Time::Local, so the
caveats and error handling with that module apply to this method as
well.

=head2 epoch

This is currently a synonym for L<time_in_seconds()|/time_in_seconds>.
But if I ever implement time-of-day functionality (far from certain)
this method will include that, whereas
L<time_in_seconds()|/time_in_seconds> will remain as of midnight.

=head2 weekday

    $day_of_week_name = $shiredate->weekday;

This method returns the day of the week using the more modern names in
use during the War of the Ring and given in the Lord of the Rings
Appendix D.  If the day in question is not part of any week (Midyear's
day and the Overlithe), then an empty string is returned.

=head2 weekday_number

    $day_of_week_number = $shiredate->weekday_number;

This method returns the number of the day of the week of the date in
question, or C<0> if the day is not part of any week (i.e.
C<Midyear's day> or the C<Overlithe>). Note that C<0> is also returned
on an error (date not set), so the careful programmer who uses this
method will check C<$ERROR> if C<0> is returned.

=head2 trad_weekday

    $day_of_week = $shiredate->trad_weekday

This method returns the day of the week using the archaic forms, the

lib/Date/Tolkien/Shire.pm  view on Meta::CPAN

    $shiredate1 cmp $shiredate2

You can only compare on shire date to another (no apples to oranges
here).  In this context both the numeric and string operators perform
the exact same function.  Like the standard operators, all but <=> and
cmp return 1 if the condition is true and the null string if it is
false.  <=> and cmp return -1 if the left operand is less than the right
one, 0 if the two operands are equal, and 1 if the left operand is
greater than the right one.

Additionally, you can view a shire date as a string:

    # prints something like 'Monday 28 Rethe 7465'
    print $shiredate;

=head2 as_string

    $shire_date_as_string = $shire_date->as_string;

Returns the given shire date as a string, similar in theory to
C<scalar localtime>. This is the method used to implement
the stringification overload.

=head2 on_date

    $historic_events = $shire_date->on_date

or you may want to try something like

    my $shiredate = Date::Tolkien::Shire->new( time );
    print "Today is " . $shiredate->on_date . "\n";

This method returns a string containing important events that happened
on this day and month in history, as well as the day itself.  It does
not give much more usefulness as far as using dates go, but it should be
fun to run during a startup script or something.  At present the events
are limited to the crucial years at the end of the third age when the
final war of the ring took place and Sauron was permanently defeated.
More dates will be added as I find them (if I find them maybe I should
say).  All the ones below come from Appendix B of the Lord of the Rings.
At this point, these are only available in English.

Note here that the string is formatted. This is to keep things simple
when using it as in the example above.  Note that in this example you
are actually ending with a double newline, as the first newline is part
of the return value.

If you don't like how this is formatted, complain at me and if I like
you I'll consider changing it :-)

If L<accented()|/accented> is true, this method returns accented output.
If L<traditional()|/traditional> is true, this method uses traditional
rather than common weekday names.

=head2 strftime

This is a re-implementation imported from
L<Date::Tolkien::Shire::Data|Date::Tolkien::Shire::Data>. It is intended
to be reasonably compatible with the same-named L<DateTime|DateTime>
method, but has some additions to deal with the peculiarities of the
Shire calendar.

See L<__format()|Date::Tolkien::Shire::Data/__format> in
L<Date::Tolkien::Shire::Data|Date::Tolkien::Shire::Data> for the
documentation, since that is the code that does the heavy lifting for
us.

If L<accented()|/accented> is true, this method returns accented output.
If L<traditional()|/traditional> is true, this method uses traditional
rather than common weekday names.

=head1 NOTE: YEAR CALCULATION

L<https://encyclopedia-of-arda.com/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 and calculated back 6000 years from 1958 and set
this as the start of the 4th age (1422). 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 uses every 4
years unless it is 100 years unless it is 400 years.  So, if no changes
had 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 thoughts, at least
right now, is that it is truer to the spirit of things for March 25
today to be about the same as March 25 was back then.  So instead, I
have modified Tolkien's description of the hobbits' calendar so that
leap years occur once every 4 years unless it is 100 years unless it is
400 years, so that it matches our calendar in that regard.  These 100
and 400 year intervals occur at different times in the two calendars,
however.  Thus the last day of our year is sometimes 7 Afteryule,
sometimes 8, and sometimes 9.

I<The "I" in the above is Tom Braun -- TRW>

=head1 BIBLIOGRAPHY

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

L<https://encyclopedia-of-arda.com/f/fourthage.html>

=head1 BUGS

Epoch time.  Since epoch time was used as the base for this module, and the
only way to currently set a date is from epoch time, it borks on values that
epoch time doesn't support (currently values before 1902 or after 2037).  The
module should automatically expand in available dates directly with epoch time
support on your system.

Support is by the author. Please file bug reports at
L<https://github.com/trwyant/perl-Date-Tolkien-Shire/issues> or in
electronic mail to the author.

=head1 AUTHOR

Tom Braun <tbraun@pobox.com>

Thomas R. Wyant, III F<harryfmudd at comcast dot net>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2001-2003, 2006 Tom Braun. All rights reserved.

Copyright (C) 2017-2022, 2025-2026 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 files F<LICENSE-Artistic> and F<LICENSE-GPL>.

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.

=cut

# ex: set textwidth=72 :