NAME
    DateTime::Event::SolarTerm - DateTime Extension to Calculate Solar Terms

SYNOPSIS
      use DateTime::Event::SolarTerm;
      my $major_term = DateTime::Event::SolarTerm->new_moon();

      my $dt0  = DateTime->new(...);
      my $next_major_term = $new_moon->next($dt0);
      my $prev_major_term = $new_moon->previous($dt0);

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

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

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

      my $minor_term = DateTime::Event::SolarTerm->new_moon();

      my $dt0  = DateTime->new(...);
      my $next_minor_term = $new_moon->next($dt0);
      my $prev_minor_term = $new_moon->previous($dt0);

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

      my $set  = $minor_term->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 major/minor term event
      my $dt = DateTime::Event::Lunar->major_term_after(datetime => $dt0);
      my $dt = DateTime::Event::Lunar->major_term_before(datetime => $dt0);
      my $dt = DateTime::Event::Lunar->minor_term_after(datetime => $dt0);
      my $dt = DateTime::Event::Lunar->minor_term_before(datetime => $dt0);

      my $index = DateTime::Event::SolarTerm->last_major_term_index(datetime => $dt);
      my $index = DateTime::Event::SolarTerm->last_minor_term_index(datetime => $dt);
      my $boolean = DateTime::Event::SolarTerm->no_major_term_on(datetime => $dt);

      # to get the next specific solar term
      use DateTime::Event::SolarTerm qw(DONGZHI);
      my $next = DateTime::Event::SolarTerm->next_term_at(
        datetime  => $dt,
        longitude => DONGZHI
      );
    
      my $prev = DateTime::Event::SolarTerm->prev_term_at(
        datetime  => $dt,
        longitude => DONGZHI
      );

DESCRIPTION
    A lunar calendar has months based on the lunar cycle, which is
    approximately 29.5 days. This cycle does not match the cycle of the Sun,
    which is approximately 365 days.

    You can use leap months to better align the cycle as in the Chinese
    calendar, but that still means that months could be off by possibly one
    lunar month. This was unacceptable for agricultural purposes which is
    linked deeply with the season, which in turn is linked with the solar
    cycle.

    This is where solar terms are used. Regardless of what lunar month it
    is, you can tell the season using the solar terms.

    Solar terms are still used in some parts of Asia, especially China,
    where major holidays must be calculated based on these solar terms.

FUNCTIONS
      *** WARNING WARNING WARNING ****

      The return value of these functions are subject to change!
      They currently return a simple DateTime object, but we may somehow
      come up with a way to return more data with it, such as the solar
      term's name

      *** WARNING WARNING WARNING ***

  DateTime::Event::SolarTerm->major_term()
  DateTime::Event::SolarTerm->minor_term()
    Returns the *starting* date of the next or previous major/minor solar
    term. This recurrence set makes no attempt to classify just what solar
    term is beginning on that date. (This may change in the future)

    Because solar terms depend on the location/timezone, you should make
    sure to pass a DateTime object with locale and/or timezone set to where
    you are basing your calculations on. If the given time zone does not
    specify one (i.e. it is a "floating" time zone), then UTC is assumed.

  DateTime::Event::SolarTerm->next_term_at(%args)
    Returns a DateTime object representing the next solar term date at the
    specified longitude. For example, to get the next winter solstice, you
    can say

      use DateTime::Event::SolarTerm qw(WINTER_SOLSTICE);
      my $winter_solstice = DateTime::Event::SolarTerm->next_term_at(
        datetime  => $dt0,
        longitude => WINTER_SOLSTICE
      );

    This is the functiont that is internally used by major_term()->next()
    and minor_term->next()

  DateTime::Event::SolarTerm->prev_term_at(%args)
    Returns a DateTime object representing the previous solar term date at
    the specified longitude. For example, to get the previous winter
    solstice, you can say

      use DateTime::Event::SolarTerm qw(WINTER_SOLSTICE);
      my $winter_solstice = DateTime::Event::SolarTerm->previous_term_at(
        datetime  => $dt0,
        longitude => WINTER_SOLSTICE
      );

    This is the functiont that is internally used by
    major_term()->previous() and minor_term->previous()

  DateTime::Event::SolarTerm->last_major_term_index(%args)
    Returns the current/previous major term index. Note that even if the
    date falls on a minor term, returns the closest previous major term from
    the date given by the datetime argument.

    (This method has been renamed from current_major_term to better suit the
    behavior)

  DateTime::Event::SolarTerm->last_minor_term_index(%args)
    Returns the current/previous minor term index. Note that even if the
    date falls on a minor term, returns the closest previous minor term from
    the date given by the datetime argument.

    (This method has been renamed from current_minor_term to better suit the
    behavior)

  DateTime::Event::SolarTerm->no_major_term_on(%args)
    Returns true if there is a major term in the current month

    (XXX - from Calendrical Calculations, I couldn't figure out if this is a
    Chinese month or a Gregorian month)

AUTHOR
    Daisuke Maki <daisuke@cpan.org>

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

SEE ALSO
    DateTime DateTime::Set DateTime::Span DateTime::Event::Lunar

