view release on metacpan or  search on metacpan

lib/DateTime/Event/Easter.pm  view on Meta::CPAN

Returns a DateTime::Set of Easter Events.

In  the past  this method  used the  same syntax  as 'as_list'  above.
However we now allow both the above syntax as well as the full options
allowable when creating sets with C<DateTime::Set>. This means you can
call C<< $datetime_set = $palm_sunday->as_set; >> and it will return a
C<DateTime::Set> of  all Palm  Sundays. See L<DateTime::Set>  for more
information.


=item * as_span()

This method switches output to spans rather than points. See the 'as' attribute
of the constructor for more information. The method returns the object for easy
chaining.

=item * as_point()

This method switches output to points rather than spans. See the 'as' attribute
of the constructor for more information. The method returns the object for easy
chaining.

=item * as_old_set()

Deprecated method.

In the  next version (1.10)  or in October  2021 (two years  after the
v1.08 initial  announcement), whichever  comes last, this  method will
emit  a warning.  And within  another two  years /  one version,  this
method will be removed.

=back

=head1 SUBROUTINES

The  module provides  a few  subroutines giving  the elements  used to
compute the Easter date.

These  elements can  be found  in various  sources, including  what is
known in France as I<l'Almanach  du Facteur> (the postman's almanach).
These values are printed at the bottom of the February frame, which is
a  convenient way  to ensure  this frame  has the  same height  as the
frames for 31-day months.

These subroutines are not exported by default.

=over 4

=item * golden_number($year)

Gives the position of  the year in the Metonic cycle.  This is a 1..19
number.

This subroutine applies to both western and eastern computs.

=item * western_epact($year)

In the  Gregorian comput, the epact  is the age of  the ecclesiastical
Moon on the 1st January of the  given year. The C<western> part of the
subroutine  name  accounts for  the  fact  that Gregorian  and  Julian
calendars do not use the same formula.

The epact  is a 0..29 number.  The "0" value  is shown as "*"  in some
sources. This  subroutine does not convert  "0" to "*", the  result is
always a pure number.

Actually,  the western  epact  is  a little  more  than  a number.  As
explained by Paul Couderc (page 86)  and Jean Lefort (page 142), there
is a  special case for 25,  which should be considered  as two values,
"basic 25" and "alternate 25". "Basic 25" is printed as a plain number
C<25>, while "alternate 25" is printed  in a way that distinguishes it
from the other  numbers. Jean Lefort mentions C<XXV>  or using italics
or bold  digits, such as  B<C<25>>. This module prints  the "alternate
25" as "C<25*>".

=item * eastern_epact($year)

In the Julian comput, the epact  is the age of the ecclesiastical Moon
on 22nd March. The C<eastern> part of the subroutine name accounts for
the  fact that  Gregorian and  Julian calendars  do not  use the  same
formula.

The epact  is a 0..29 number.  The "0" value  is shown as "*"  in some
sources. This  subroutine does not convert  "0" to "*", the  result is
always a pure  number. There is no  other special case, for  25 as for
any other number.

The formula given by Reingold and  Dershowitz is a "shifted epact" and
gives  different  results from  the  values  printed in  Lefort's  and
Couderc's books. The module follows Couderc and Lefort.

=item * western_sunday_letter($year), eastern_sunday_letter($year)

On normal years (that is, excluding  leap years), the Sunday letter is
determined by tagging 1st January with  "A", 2nd January with "B", and
so on and looking at the first sunday of the year. The letter found at
this sunday if the sunday letter for the year.

The  sunday   letter  governs  all   conversions  from  (mm,   dd)  to
day-of-week. For example, if the letter is "F", then 1st January, 12th
February, 2nd July and 1st  October, among others, are tuesdays, while
6th January, 24th February, 14th July and 6th October are sundays.

On  leap  years, there  are  two  sunday  letters.  The first  one  is
determined  as above,  the second  one  is determined  by tagging  2nd
January,  not 1st,  with  "A".  The first  sunday  letter governs  all
conversions  from (mm,  dd) to  day-of-week for  January and  February
only, while the second sunday letter governs the conversions from (mm,
dd) to day-of-week for March and after.

So, if the sunday letters are  "FE", 1st January and 12th February are
still tuesdays,  but 2nd July and  1st October are wednesdays.  At the
same time, 6th January and 24th February are still sundays, while 14th
July and 6th October are mondays.

C<western_sunday_letter>  applies  only   to  Gregorian  years,  while
C<eastern_sunday_letter> applies only to Julian years.

=item * western_sunday_number($year), eastern_sunday_number($year)

Letters  (standalone or  in pairs)  are not  convenient for  numerical
calculations.  So  the   I<xxx>C<_sunday_number>  subroutine  is  used
instead of I<xxx>C<_sunday_letter>.

In case  of leap  years, the I<xxx>C<_sunday_number>  subroutine gives
the numerical value for the second sunday letter, because Easter never
falls in January or February.

=item * easter($year)

Given a Gregorian year, this  subroutine will return a DateTime object
for Western Easter Sunday in that year.

=item * western_easter($year)

Given a Gregorian year, this  subroutine will return a DateTime object
for  Western Easter  Sunday  in  that year.  But  unlike the  previous
subroutine,  C<western_easter> cannot  be imported.  You must  use its
fully qualified name:

  my $date = DateTime::Event::Easter::western_easter($year);

=item * eastern_easter($year)

Given  a  Julian year,  this  subroutine  will  return a  DateTime  ::
Calendar :: Julian object for Eastern  Easter Sunday in that year. And
like C<western_easter>, C<eastern_easter> cannot be imported. You must
use its fully qualified name: