NAME

DateTime::Event::Lunar - Compute Lunar Events

SYNOPSIS

  use DateTime::Event::Lunar;
  my $new_moon = DateTime::Event::Lunar->new_moon();

  my $dt0  = DateTime->new(...);
  my $next_new_moon = $new_moon->next($dt0);
  my $prev_new_moon = $new_moon->previous($dt0);

  my $dt1  = DateTime->new(...);
  my $dt2  = DateTime->new(...);
  my $span = DateTime::Span->new(start => $dt1, end => $dt2);

  my $set  = $new_moon->intersection($span);
  my $iter = $set->iterator();

  while (my $dt = $iter->next) {
    print $dt->datetime, "\n";
  }

  my $lunar_phase = DateTime::Event::Lunar->lunar_phase(phase => $phase);
  # same as new_moon, but returns DateTime objects
  # when the lunar phase is at $phase degress.

  # if you just want to calculate a single new moon event
  my $dt = DateTime::Event::Lunar->new_moon_after(datetime => $dt0);
  my $dt = DateTime::Event::Lunar->new_moon_before(datetime => $dt0);

  # if you just want to calculate a single lunar phase time
  my $dt = DateTime::Event::Lunar->lunar_phase_after(
        datetime => $dt0, phase => $degrees);
  my $dt = DateTime::Event::Lunar->lunar_phase_before(
        datetime => $dt0, phase => $degrees);

DESCRIPTION

This module calculates the time and date of certain recurring lunar events, including new moons and specific lunar phases.

Calculations for this module are based on "Calendrical Calculations" [1]. Please see REFERENCES for details.

DateTime::Event::Lunar->new_moon()

Returns a DateTime::Set object that you can use to get the date of the next or previous new moon.

  my $set = DateTime::Event::Lunar->new_moon();
  my $dt  = DateTime->now();
  my $dt_of_next_new_moon = $set->next($dt);

Or you can use it in conjunction with DateTime::Span. See SYNOPSIS.

DateTime::Event::Lunar->new_moon_after(%args)

Returns a DateTime object representing the next new moon relative to the datetime argument.

  my $next_dt = DateTime::Event::Lunar->new_moon_after(datetime => $dt0);

This is the function that is internally used by new_moon()->next(). While the DateTime::Set interface requires that the next() function always returns a date *after* the given date, for some calculations it is required that a new moon on *or* after is computed. This can be achieved by setting the "on_or_after" parameter:

  my $on_or_after = DateTime::Event::Lunar->new_moon_after(
    datetime => $dt0,
    on_or_after => 1
  );

The default for this parameter is false.

DateTime::Event::Lunar->new_moon_before(%args)

Returns a DateTime object representing the previous new moon relative to the datetime argument.

  my $prev_dt = DateTime::Event::Lunar->new_moon_before(datetime => $dt0);

This is the function that is internally used by new_moon()->previous().

DateTime::Event::Lunar->lunar_phase(%args)

Returns a DateTime::Set object that you can use to get the date of the next or previous date, when the lunar longitude is at $phase degrees

  my $set = DateTime::Event::Lunar->lunar_phase(phase => 60);
  my $dt  = DateTime->now();
  my $dt_at_longitude_60 = $set->next($dt);

Or you can use it in conjunction with DateTime::Span. See SYNOPSIS.

DateTime::Event::Lunar->lunar_phase_after(%args);

Returns a DateTime object representing the next date that the lunar phase is equal to the phase argument, relative to the datetime argument.

  use DateTime::Event::Lunar qw(:phases);
  my $next_dt = DateTime::Event::Lunar->lunar_phase_after(
    datetime => $dt,
    phase    => FULL_MOON
  );

This is the function that is internally used by lunar_phase()->next() While the DateTime::Set interface requires that the next() function always returns a date *after* the given date, for some calculations it is required that a lunar phase date on *or* after is computed. This can be achieved by setting the "on_or_after" parameter:

  my $on_or_after = DateTime::Event::Lunar->lunar_phase_after(
    datetime => $dt0,
    phase    => FULL_MOON,
    on_or_after => 1
  );

The default for this parameter is false.

DateTime::Event::Lunar->lunar_phase_before(%args);

Returns a DateTime object representing the previous date that the lunar phase is equal to the phase argument, relative to the datetime argument.

  use DateTime::Event::Lunar qw(:phases);
  my $prev_dt = DateTime::Event::Lunar->lunar_phase_before(
    datetime => $dt,
    phase    => FULL_MOON
  );

This is the function that is internally used by lunar_phase()->previous()

CAVEATS

Spansets created via intersection() functions are *very* slow at first, because it needs to calculate all the possible values within the span first. If you are going to be using these values in different places, it is strongly suggested that you create one spanset before hand that others can refer to.

Lunar phases are even slower than new moons. It would be nice to fix it...

AUTHOR

LICENSE

Algorithm by Edward M. Reingold and Nachum Dershowitz

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

REFERENCES

  [1] Edward M. Reingold, Nachum Dershowitz
      "Calendrical Calculations (Millenium Edition)", 2nd ed.
       Cambridge University Press, Cambridge, UK 2002