NAME Date::Tolkien::Shire.pm DESCRIPTION This is an object-oriented module to convert dates into the Shire Calender as presented in the Lord of the Rings by J. R. R. Tolkien. It includes converting epoch time to the Shire Calendar (you can also get epoch time back), comparison operators, and a method to print a formatted string containing that does something to the effect of on this date in history -- pulling events from the Lord of the Rings. The biggest use I can see in this thing is in a startup script or possible to keep yourself entertained in an otherwise boring app that includes a date. If you have any other ideas/suggestions/uses, etc., please let me know. I am curious to see how this gets used (if it gets used that is). AUTHOR Tom Braun DATE January 2001 METHOD REFERENCE Note: I have tried to make these as friendly as possible when an error occurs. As a consequence, none of them die, croak, etc. All of these return 0 on error, but as 0 can be a valid output in a couple cases (the day of the month for a holiday, for example), the error method should always be checked to see if an error has occured. As long as you set a date before you try to use it, you should be ok. new $shiredate = Date::Tolkien::Shire->new; $shiredate = Date::Tolkien::Shire->new(time); $shiredate = Date::Tolkine::Shire->new($another_shiredate); The constructor new can take zero or one parameter. Either a new object can be created without setting a specific date (the zero parameter version), or an object can be created and the date set to either a current shire date, or an epoch time such as is returned by the time function. For specifics on setting dates, see the 'set_date' function. error $the_error = $shiredate->error; $the_error = Date::Tolkien::Shire->error; This returns a null string if everything in the previous method call was as it should be, and a string contain a description of what happened if an error occurred. set_date This method takes either the seconds from the start of the epoch (like what 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. Locatime, rather than gmt, is used in converting from epoch date. 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. weekday $day_of_week = $shiredate->weekday; This function 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 day and the Overlithe), then the null string is returned. trad_weekday (for traditional weekday) $day_of_week = $shiredate->trad_weekday This function returns the day of the week using the archaic forms, the oldest forms found in the Yellowskin of Tuckborough (also given in Appendix D). If the day in question is not part of any week (Midyear day and the Overlithe), then the null string is returned. month $month = $shiredate->month; Returns the month of the date in question, or the null string if the day is a holiday, since holidays are not part of any month. day $day_of_month = $self->{monthday}; returns the day of the month of the day in question, or 0 in the case of a holiday, since they are not part of any month holiday $holiday = $shiredate->holiday; If the day in question is a holiday, returns a string which holiday it is: "Yule 1", "Yule 2" (first day of the new year), "Lithe 1", "Midyear's day", "Overlithe", or "Lithe 2". If the day is not a holiday, the null string is returned year $shire_year = $shiredate->year; Returns the year of the date in question. Note that I made up a year to keep things nice for me internally by making leap years always match up. Thus, 978 B.C. our time corresponds to the start of the fourth age. If anyone can give me a better approximate, let me know and I will look into changing this. Trying to figure out when the fourth age actually started in our calendar is a task quite beyond me. Operators The following comparison operators are available: $shiredate1 < $shiredate2 $shiredate1 lt $shiredate2 $shiredate1 <= $shiredate2 $shiredate1 le $shiredate2 $shiredate1 > $shiredate2 $shiredate1 gt $shiredate2 $shiredate1 >= $shiredate2 $shiredate1 ge $shiredate2 $shiredate1 == $shiredate2 $shiredate1 eq $shiredate2 $shiredate1 != $shiredate2 $shiredate1 ne $shiredate2 $shiredate1 <=> $shiredate2 $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. 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 usefullness 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 second example above. Note that in this second example you are actually ending with a double space, as the first endline 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 :-) BIBLIOGRAPHY Tolkien, J. R. R. Return of the King. New York: Houghton Mifflin Press, 1955. BUGS The treatment of years could probably by seen as a bug. After all, I just made it up to make things convenient. I'm afraid, however, that I have no clue what they should be, so until I discover some great insite or someone who does know is kind enought to instruct me, this will remain as is.