/ 
DateTime-Event-Easter-1.0
River stage two • 7 direct dependents • 10 total dependents
/ DateTime::Event::Easter

NAME

DateTime::Event::Easter - Returns Easter events for DateTime objects

SYNOPSIS

use DateTime::Event::Easter;

$dt = DateTime->new( year   => 2002,
                     month  => 3,
                     day    => 31,
                   );


$easter_sunday = DateTime::Event::Easter->new();

$previous_easter_sunday = $easter_sunday->previous($dt);
# Sun, 15 Apr 2001 00:00:00 UTC

$following_easter_sunday = $easter_sunday->following($dt);
# Sun, 20 Apr 2003 00:00:00 UTC

$closest_easter_sunday = $easter_sunday->closest($dt);
# Sun, 31 Mar 2002 00:00:00 UTC

$is_easter_sunday = $easter_sunday->is($dt);
# 1

$palm_sunday = DateTime::Event::Easter->new(day=>'Palm Sunday');


$dt2 = DateTime->new( year   => 2012,
                      month  => 3,
                      day    => 31,
                    );

@set = $palm_sunday->set(from=>$dt, to=>$dt2, inclusive=>1);
# Sun, 13 Apr 2003 00:00:00 UTC
# Sun, 04 Apr 2004 00:00:00 UTC
# Sun, 20 Mar 2005 00:00:00 UTC
# Sun, 09 Apr 2006 00:00:00 UTC
# Sun, 01 Apr 2007 00:00:00 UTC
# Sun, 16 Mar 2008 00:00:00 UTC
# Sun, 05 Apr 2009 00:00:00 UTC
# Sun, 28 Mar 2010 00:00:00 UTC
# Sun, 17 Apr 2011 00:00:00 UTC

DESCRIPTION

The DateTime::Event::Easter module returns Easter events for DateTime objects. From a given datetime, it can tell you the previous, the following and the closest Easter event. The 'is' method will tell you if the given DateTime is an Easter Event.

Easter Events can be Palm Sunday, Maundy Thursday, Good Friday, Black Saturday and Easter Sunday. If that's not enough, the module will also accept an offset so you can get the date for Pentecost (49 days after Easter Sunday) by passing 49.

BACKGROUND

Easter Sunday is the Sunday following the first full moon on or following the Official Vernal Equinox. The Official Vernal Equinox is March 21st. Easter Sunday is never on the full moon. Thus the earliest Easter can be is March 22nd.

In the orthodox world, although they now use the Gregorian Calendar rather than the Julian, they still take the first full moon after the Julian March 21st. As the Julian calendar is slowly getting further and further out of sync with the Gregorian, the first full moon after this date can be a completely different one than for the western Easter. This is why the Orthodox churches celebrate Easter later than western churches.

CONSTRUCTOR

This class accepts the following options to its 'new' constructor:

  • easter => ([western]|eastern)

    The Catholic and Protestant churches use the 'official' date for the Paschal Full Moon which is the first Full Moon on or after the 'official' vernal Equinox (March 21). Not wanting to be outdone the Orthodox churches decided to use the same date .. only they use it in the Julian Calendar (which is increasingly moving away from the Georgian) This means Paschal Full Moon for Easter calculations can be the Full Moon after the moon used in the western world.

    By default this module uses the Gregorian Easter, however even if you ask for 'eastern' Easter you will get a Gregorian DateTime back. See DateTime::Calendar::Julian if you would like to convert this into a Julian date.

    In the future it is thought to allow an option of 'auto' here. This will take a look at the DateTime object's timezone to determine if a country follows the Official or the Astronomical method.

    If this parameter is not supplied, the western Easter will be used.

  • day => ([Easter Sunday]|Palm Sunday|Maundy Thursday|Good Friday|Black Saturday|n)

    When constructed with a day parameter, the method can return associated Easter days other than Easter Sunday. The constructor also allows an integer to be passed here as an offset. For example, Maundy Thursday is the same as an offset of -3 (Three days before Easter Sunday)

    When constructed without a day parameter, the method uses the date for Easter Sunday (which is the churches' official day for 'Easter', think of it a 'Easter Day' if you want)

    This parameter also allows the following abreviations: day => ([Sunday]|Palm|Thursday|Friday|Saturday)

    Other days which rely on Easter are in another module DateTime::Event::ChurchYear which (at this time) still needs to be written. The days that are included are the main days that are celebrated as 'Easter'

METHODS

This class offers the following methods.

  • following($dt)

    Returns the DateTime object for the Easter Event after $dt. This will not return $dt.

  • previous($dt)

    Returns the DateTime object for the Easter Event before $dt. This will not return $dt.

  • closest($dt)

    Returns the DateTime object for the Easter Event closest to $dt. This will return midnight of $dt if $dt is the Easter Event.

  • is($dt)

    Return positive (1) if $dt is the Easter Event, otherwise returns false (0)

  • as_list(from => $dt, to => $dt2, inclusive=>([0]|1))

    Returns a list of Easter Events between to and from. If the optional inclusive parameter is true (non-zero), the to and from dates will be included if they are the Easter Event. If you do not include an inclusive parameter, we assume you do not want to include these dates (the same behaviour as supplying a false value)

  • as_set(from => $dt, to => $dt2, inclusive=>([0]|1))

    Returns a DateTime::Set of Easter Events between to and from. If the optional inclusive parameter is true (non-zero), the to and from dates will be included if they are the Easter Event. If you do not include an inclusive parameter, we assume you do not want to include these dates (the same behaviour as supplying a false value)

EXPORTS

This class does not export any methods by default, however the following exports are supported.

  • easter($year)

    Given a year, this method will return a DateTime object for Easter Sunday in that year.

    This method uses the Official Paschal Moon.

AUTHOR

Rick Measham <rickm@cpan.org>

SEE ALSO

DateTime, perl(1).