NAME

Date::Roman - Perl OO extension for handling roman style dates

SYNOPSIS

  use Date::Roman;

  $caesar_death = Date::Roman->new(roman => 'id 3 702');
  
  print $caesar_death->ical(),"\n"; #prints -520315

DESCRIPTION

This module defines a class for handling Roman dates as defined by Julius Caesar in 45 BC.

METHODS

The following methods are defined for "Date::Roman" objects:

"new": This method is the class constructor. It can be invoked in quite a lot of different ways:

"Date::Roman->new()"

With no arguments, is the same that

  Date::Roman->new(epoch => time())

"Date::Roman->new($dateobj)"

where $dateobj is a date objet. The only requested characteristic for this object is to support either a "roman" or a "ical" method behaving like the corresponding method of this class. For instance, it could be a Date::Roman or a Date::ICal object.

"Date::Roman->new(format => $datestring)"

where "format" is one of roman or ical and $datestring is a date in the format specified by "format" (see the DATE FORMATS section below).

"Date::Roman->new(dateelem => $value,...)"

this form allows you to enter a date by giving its constitutive elements. The given date can be either in the Roman or in the Christian form.

In the first case, you have to give the following mandatory elements: 'base' (the fixed day part of the date, can be one of 'kal', 'non' or 'id'), 'mons' (the month, must be a number between 1 and 12) and 'annus' (the year in the AUC count, must be a positive integer). You can add the following optional elmements: 'ad' (the days before the given fixed day, must be a positive integer, defaults to 1) and 'bis' (boolean specifying if the given day is the 'leap day').

In the second case, you must specify all the following elements: 'day' (the day of the month, starting at 1), 'month' (the month, must be a number between 1 and 12) and 'year' (the year in the Christian era format, year 0 is 1 BC).

"roman"

Called without arguments, it returns the date in the roman format (see the DATE FORMATS section below). If is called with one arguments it assumes it is a date string in the roman format, and sets the date to it.

"ical"

Called without arguments, it returns the date in the ical format (see the DATE FORMATS section below). If is called with one arguments it assumes it is a date string in the ical format, and sets the date to it.

"as_string"

This method returns a printable version of the date in the classical Roman format. The format of the returned string can be controlled with the parameters passed to the method. Parameters are passed to the method using the classical 'hash like' approach:

   $date->as_string(name => value,...);

The method "as_string" accepts the following parameters:

prefix: Controls how the "ante diem" or "pridie" part of the date is written. Possible values are: abbrev, which writes them as "a.d." and "p.d." respectively, and complete which writes them in full. This parameter defaults to the value of the words parameter below if given, and to abbrev otherwise.
die: Controls how the number of the "ante diem" day is written. Possible values are: Roman, which writes it as an uppercase Roman numeral; roman, which writes it as a lowercase Roman numeral; and arabic, which writes it as an Arabic numeral. This parameter defaults to the value of the num parameter below if given, to Roman otherwise.
fday: Controls how the fixed day appearing in the date is written. Possible values are: abbrev, which writes it abbreviated to 'Kal.', 'Non.' or 'Id.'; and complete which writes it in full. This parameter defaults to the value of the words parameter below if given, and to abbrev otherwise.
mons: Controls how the month appearing in the date is written. Possible values are: abbrev, which writes it abbreviated as 'Ian.', 'Feb.' an so on; and complete which writes it in full. This parameter defaults to the value of the words parameter below if given, and to abbrev otherwise.
annus: Controls how the number of the year is written. Possible values are: Roman, which writes it as an uppercase Roman numeral; roman, which writes it as a lowercase Roman numeral; and arabic, which writes it as an Arabic numeral. This parameter defaults to the value of the num parameter below if given, to Roman otherwise.
auc: Controls how the "ab Urbe condita" formula is written. Possible values are: abbrev, which writes it as "AUC", and complete which writes it in full. This parameter defaults to the value of the words parameter below if given, and to abbrev otherwise.
words: This parameter permits to give a default value different from abbrev for the parameters prefix, mons, fday and auc.
num: This parameter permits to give a default value different from Romans for the parameters die and annus.

"add"

Takes as argument an integer $n and returns a new Date::Roman object representig the date obtained adding $n days to the present date.

"heri"

Returns the yesterday date. Calling

  $date->heri();

is the same thing as calling

  $date->add(-1);

"postridie"

Returns the tomorrow date. Calling

  $date->postridie();

is the same thing as calling

  $date->add(1);

TODO

1.: Add time management. This will require to determine sunraise/sunset time for the given day.
2.: Change the "_leap" subroutine to reflect the fact that between 45 BC (709 AUC) and 9 BC (745 AUC) there was a leap year every three years, then between 8 BC (744 AUC) and 7 AD (760 AUC) there was no leap year to make up for the three exceeding leap years.
3.: Add Ante Urbe Condida years.
4.: Rewrite the module in Latin using the Lingua::Romana::Perligata module.

DATE FORMATS

Dates can be specified by a string in one of two formats: roman and ical.

The roman format.

It is a simplified version of the roman way to write dates (see the section THE ROMAN CALENDAR below). It is defined by the following ABNF specification (see rfc2234):

   <roman date> = [<prefix><spaces>]<fixed day><spaces><mons><spaces><annus>
   <prefix>     = 1*2DIGIT     ; "1".."4" / "1".."6" / "1".."8" /
                               ; "1".."16" / "1".."17" /
                               ; "1".."18" / "1".."19"
                               ; according to <mons> <fixed day>
                               ; value.

   <prefix>    /= "b6"         ; only for <mons> equal to "3", <fixed day> 
                               ; equal to "kal" and <annus> equal to a 
                               ; leap year.
   <fixed day>  = "kal" / "non" / "id"
   <mons>       = 1*2DIGIT     ; "1".."12"
   <annus>      =  1*DIGIT
   <spaces>     =  1*WSP

We use the "b6" prefix to indicate the leap day (24th february) introduced in leap tears. As it is stated below in section "The days in the Roman calendar", this was again the 6th day before the Kalendae of March, exatly as the day after.

The ical format

The ical format is a generalization of the format for dates defined in rfc2445. The genralization consists in allowing a year in less than 4 digits and in allowing a prefixed "-" to represents years before 1 BC. More specifically, a ical date string is defined by the following ABNF specification (see rfc2234):

  <ical date>   = <year> <month> <day>
  <year>        = [<minus>] 1*DIGIT
  <month>       = 2DIGIT   ; "1".."12"
  <day>         = 2DIGIT   ; "1".."28" / "1".."29" /
                           ; "1".."30" / "1".."31" according 
                           ; to <month> <year> value
  <minus>       = %x2d

As it is customary, we use 0 to represent the year 1 BC, -1 to represent the year 2 BC and so on.

THE ROMAN CALENDAR

The Julian reform, the month length

Julius Caesar made his famous calendar reform in 45 BC. According to this reform, the year was of 365 days, divided in 12 months: Ianuarius, 31 days; Februaarius, 28 days, Martius, 31 days; Aprilis, 30 days; Maius, 31 days, Iunius, 30 days, Iulius, 31 days; Sextilis 31 days, September, 30 days, October, 31 days; November, 30 days; and December, 31 days. Later, Sextilis became Augustus (to simplify, we used Augustus as name of the 8th month trought the module).

The Julian reform, leap years

To make up with the fact that the tropical year is a little longer than 365 days, Julius Caesar decreed that one year in 4 should be longer by one day, adding one day to Februarius.

Due to a misunderstandig about what "one year in 4" meant, between 45 BC and 9 BC there was a leap year every three years. To make up for the surplus of leap years so introduced, emperor Augustus decreed a 15 years period without leap years, so that the first leap year after 9 BC was 8 AD. Then there was a leap year every 4 years until the Gregorian Reform. This module take into account the Gregorian reform assuming that it took place in 1582 AD. It does not take into account the problems in determining leap years between 45 BC and 8 AD (at least it does not yet, see the section TODO above).

The days in the Roman calendar

The Romans didn't number the days sequentially from 1. Instead they had three fixed days in each month:

Kalendae: which was the first day of the month;
Idus: which was the 13th day of January, February, April, June, August, September, November, and December and the 15th day of March, May, July, or October;
Nonae: which was the 9th day befor the Idus (counting Idus itself as the first day).

The others days, where designed counting backward from these fixed days. It should be remarked that, in counting backward, the romans used an inclusive counting. That way, for instance, the 2 Jan was the 4th day before the nones of January (the nones of January being the 5th of January).

The day before a fixed day was designed by "pridie", abbreviated as "p.d.". The other days was designed using the formula "ante diem", abbreviated as "a.d.". For instance, the 16th of April was ante diem XVI Kalendas Maias, abbreviated as a.d. Kal. Mai.

In leap years, the supplemental day was obtained by counting two times the 6th day before the Kalendae of March.

Counting the years

Romans counted years starting from the mitical foundation of Rome by Romolus on 21st April, 753 BC. Fr instance, year 2002 AD is the year 2755 AUC (ab Urbe condita, after the foundation of the City).

What before the Julian reform?

Before Julius Caesar introduced the Julian calendar in 709 AUC, the Roman calendar was a mess, and much of our so-called ``knowledge'' about it seems to be little more than guesswork. This module uses the Julian calendar also for dates before the 1 Jan 45 BC (or, more precisely, Kalendas Ianuariis DCCIX AUC). This is the so called 'proleptic Julian calendar' and it is consistent with the historians' habit to do so.

AUTHOR

Leo Cacciari, aka TheHobbit <thehobbit@altern.org>

THANKS

I would like to thanks people who helped me to get this module right:

The people on the datetime@perl.org mailing list, expecially Rich Bowen <rbowen@rcbowen.com>, Elaine -HFB- Ashton <elaine@chaos.wustl.edu> and Jean Forget <J-FORGET@wanadoo.fr>.
The people on the iclp (it.comp.lang.perl) newsgroup, expecially Aldo Calpini <dada@perl.it>.
Marco, aka `Diese|` from the #roma2 IRCnet channel, who helped me with Latin. Any Latin error which is still there is mine, the ones that went away did so thanks to him.

COPYRIGHT AND DISCLAIMER

This software is Copyright 2002 by Leo Cacciari. This software is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License, either as stated in the enclosed LICENSE file or (at your option) as given on the Perl home site: http://www.perl.com/language/misc/Artistic.html

Software documentation

The perl(1) man page.
The Roman(3) man page.
The Date::ICal(3) man page.

Books

Any Latin textbook.

Web

The very good Frequently Asked Questions about Calendars by Claus Tondering. You can found it at http://www.tondering.dk/claus/calendar.html See especially section 2.7.