view release on metacpan or  search on metacpan

lib/Astro/MoonPhase/Simple.pm  view on Meta::CPAN

    });

    # alternatively provide a nameplace instead of a timezone
    # to deduce the timezone
    my $res = calculate_moon_phase({
      'date' => '1974-07-15',
      'time' => '04:00',
      'location' => 'Nicosia',
    });

    ...

=head1 EXPORT

=over 2

=item * C<calculate_moon_phase()>

=back

=head1 SUBROUTINES

=head2 calculate_moon_phase

This is the main and only subroutine which is
exported by default. It expects a HASH reference
as its input parameter containing C<date>, in the
form "YYYY-MM-DD", and optionally C<time>, in
the form "hh:mm:ss". The timezone the date is pertaining
to can be specified using key "timezone", in the form
of a TZ identifier, e.g. "Africa/Abidjan". Alternatively,
specify the location, as a HASHref of C<{lon, lat}>,
the moon is observed from and this
will deduce the timezone, albeit not always as accurately
as with specifying a "timezone" explicitly.

Warning: if the caller does not specify a C<timezone> or C<location>
then the specified C<time> will be assumed to be B<UTC time> and not
at the local timezone of the host.

L<Astro::MoonPhase> calculates the moon phase
given an I<epoch>. Which is the number of seconds
since 1970-01-01 B<on a UTC timezone>. This epoch
is corrected to a "I<localepoch>" by adding to it
the specific timezone offset. For example, if you
specified the timezone to be "China/Beijing" and
the local time (at the specified timezone) to be 23:00.
It means UTC time is 15:00. The epoch will be calculated
on UTC time. However, we add C<23:00-15:00=8:00> hours to
that epoch to make it "I<localepoch>" and this is
what we pass on to L<Astro::MoonPhase> to calculate
the moon phase.

On failure it returns C<undef>.
On success it returns a HASHref with keys:

=over 2

=item * C<MoonPhase> : the moon phase (terminator phase angle) as a number between 0 and 1. New Moon (dark) being 0 and Full Moon (bright) being 1.

=item * C<MoonPhase%> : the above as a percentage.

=item * C<MoonIllum> : the illuminated fraction of the moon's disc as a number between 0 and 1. New Moon (dark) being 0 and Full Moon (bright) being 1.

=item * C<MoonIllum%> : the above as a percentage.

=item * C<MoonAge> : the fractional number of days since the Moon's birth (new moon), at specified date.

=item * C<MoonDist> : the distance of the Moon from the centre of the Earth (kilometers).

=item * C<MoonAng> : the angular diameter subtended by the Moon as seen by an observer at the centre of the Earth

=item * C<SunDist> : Moon's distance from the Sun (kilometers).

=item * C<SunAng> : the angular size of Sun (degrees).

=item * C<phases> : a HASHref containing the date and time for the various Moon phases (at specified date). It contains keys C<New Moon, First quarter, Full moon, Last quarter, Next New Moon>

=item * C<asString> : a string representation of the above.

=back

=head1 SCRIPT

The script C<moon-phase-calculator.pl> is provided for doing
the calculations via the command line.

Example usage: C<moon-phase-calculator.pl --date 1974-07-14 --timezone 'Asia/Nicosia'>

=head1 SEE ALSO

This package summarises the post and
discussion L<this post|https://perlmonks.org/?node_id=11137299>
over at PerlMonks.org

There are some more goodies in that post e.g. PerlMonk Aldebaran provides
code for tracking the planets and at different altitudes.

I can't iterate enough that this module wraps the
functionality of L<Astro::MoonPhase>.
L<Astro::MoonPhase> does all the heavy lifting.

=head1 CAVEATS

In L<calculate_moon_phase>, if the caller does not specify a C<timezone> or C<location>
then the specified C<time> will be assumed to be B<UTC time> and not
at the local timezone of the host.


=head1 AUTHOR

Andreas Hadjiprocopis, C<< <bliako at cpan.org> >>

=head1 DEDICATIONS

Marathon Almaz

=head1 BUGS

Please report any bugs or feature requests to C<bug-astro-moonphase-simple at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Astro-MoonPhase-Simple>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.