Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Date::Roman(3)	      User Contributed Perl Documentation	Date::Roman(3)

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	45A 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 1A 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
	   45A BC (709A	AUC) and 9A BC (745A AUC) there	was a leap year	every
	   three years,	then between 8A	BC (744A AUC) and 7A AD	(760A 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	1A 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 1A BC, -1 to
       represent the year 2A BC	and so on.

THE ROMAN CALENDAR
   The Julian reform, the month	length
       Julius Caesar made his famous calendar reform in	45A 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
       45A BC and 9A 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
       9A BC was 8A 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 1582A AD.	It does	not take into account
       the problems in determining leap	years between 45A BC and 8A 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, 753A BC. Fr instance, year 2002A AD is the year
       2755A AUC (ab Urbe condita, after the foundation	of the City).

   What	before the Julian reform?
       Before Julius Caesar introduced the Julian calendar in 709A 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 45A BC (or, more
       precisely, Kalendas Ianuariis DCCIXA 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:

       o   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>.

       o   The people on the iclp (it.comp.lang.perl) newsgroup, expecially
	   Aldo	Calpini	<dada@perl.it>.

       o   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
       o   The perl(1) man page.

       o   The Roman(3)	man page.

       o   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.

v. 1.06			 a.d. XI Kal. Mai. MMDCCLV AUC		Date::Roman(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | TODO | DATE FORMATS | THE ROMAN CALENDAR | AUTHOR | THANKS | COPYRIGHT AND DISCLAIMER

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Date::Roman&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help