view release on metacpan or  search on metacpan

lib/Date/Roman.pm  view on Meta::CPAN

=item C<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 C<as_string> accepts the following parameters:

=over

=item B<prefix>

Controls how the "ante diem" or "pridie" part of the date is
written. Possible values are: B<abbrev>, which writes them as "a.d."
and "p.d." respectively, and B<complete> which writes them in
full. This parameter defaults to the value of the B<words> parameter
below if given, and to B<abbrev> otherwise.

=item B<die>

Controls how the number of the "ante diem" day is written. Possible
values are: B<Roman>, which writes it as an uppercase Roman numeral;
B<roman>, which writes it as a lowercase Roman numeral; and B<arabic>,
which writes it as an Arabic numeral. This parameter defaults to the
value of the B<num> parameter below if given, to B<Roman> otherwise.


=item B<fday>

Controls how the I<fixed day> appearing in the date is
written. Possible values are: B<abbrev>, which writes it abbreviated
to 'Kal.', 'Non.' or 'Id.'; and B<complete> which writes it in
full. This parameter defaults to the value of the B<words> parameter 
below if given, and to B<abbrev> otherwise.


=item B<mons>

Controls how the I<month> appearing in the date is
written. Possible values are: B<abbrev>, which writes it abbreviated
as 'Ian.', 'Feb.' an so on; and B<complete> which writes it in
full. This parameter defaults to the value of the B<words> parameter 
below if given, and to B<abbrev> otherwise.


=item B<annus>

Controls how the number of the year is written. Possible
values are: B<Roman>, which writes it as an uppercase Roman numeral;
B<roman>, which writes it as a lowercase Roman numeral; and B<arabic>,
which writes it as an Arabic numeral. This parameter defaults to the
value of the B<num> parameter below if given, to B<Roman> otherwise.


=item B<auc>

Controls how the "ab Urbe condita" formula is written. Possible values
are: B<abbrev>, which writes it as "AUC", and B<complete> which writes
it in full. This parameter defaults to the value of the B<words>
parameter below if given, and to B<abbrev> otherwise.


=item B<words>

This parameter permits to give a default value different from
B<abbrev> for the parameters B<prefix>, B<mons>, B<fday> and B<auc>.


=item B<num>

This parameter permits to give a default value different from
B<Romans> for the parameters B<die> and B<annus>.

=back

=item C<add>

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

=item C<heri>

Returns the yesterday date. Calling

  $date->heri();

is the same thing as calling

  $date->add(-1);


=item C<postridie>

Returns the tomorrow date. Calling

  $date->postridie();

is the same thing as calling

  $date->add(1);


=back

=head1 TODO

=over

=item 1

Add time management. This will require to determine sunraise/sunset
time for the given day.


=item 2

lib/Date/Roman.pm  view on Meta::CPAN

=head2 The Julian reform, the month length

Julius Caesar made his famous calendar reform in S<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).


=head2 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 
S<45 BC> and S<9 BC> there was a leap year every I<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 S<9 BC> was S<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 
S<1582 AD>. It does not take into account the problems in determining 
leap years between S<45 BC> and S<8 AD> (at least it does not yet, 
L<see the section TODO above|TODO>).

=head2 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: 

=over

=item Kalendae

which was the first day of the month;

=item 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;

=item Nonae

which was the 9th day befor the Idus (counting Idus itself as the
first day).

=back

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 
I<ante diem XVI Kalendas Maias>, abbreviated as I<a.d. Kal. Mai.>

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

=head2 Counting the years

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

=head2 What before the Julian reform?

Before Julius Caesar introduced the Julian calendar in S<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 S<45 BC> (or, more
precisely, Kalendas Ianuariis S<DCCIX AUC>). This is the so called
'proleptic Julian calendar' and it is consistent with the historians'
habit to do so.


=head1 AUTHOR

Leo Cacciari, aka TheHobbit E<lt>thehobbit@altern.orgE<gt>

=head1 THANKS

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

=over

=item *

The people on the datetime@perl.org mailing list, expecially Rich
Bowen E<lt>rbowen@rcbowen.comE<gt>, Elaine -HFB- Ashton
E<lt>elaine@chaos.wustl.eduE<gt> and Jean Forget
E<lt>J-FORGET@wanadoo.frE<gt>. 

=item *

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

=item *

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.


=back

=head1 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