NAME

    Astro::MoonPhase::Simple - Calculate the phase of the Moon on a given
    time without too much blah blah

VERSION

    Version 0.02

SYNOPSIS

    This package provides a single subroutine to calculate the phase of the
    moon on a given time. The results are returned as a hash.

    The heavy lifting is done by Astro::MoonPhase. All this package does is
    to wrap the functionality of Astro::MoonPhase adding some parameter
    checking.

        use Astro::MoonPhase::Simple;
    
        my $res = calculate_moon_phase({
          'date' => '1974-07-15',
          'timezone' => 'Asia/Nicosia',
        });
        print "moon is ".$res->{'MoonPhase%'}."% full\n";
        print "moon is illuminated by ".$res->{'MoonIllum%'}."%\n";
    
        print $res->{'asString'};
    
        # alternatively provide location coordinates
        # (instead of timezone) to deduce the timezone
        my $res = calculate_moon_phase({
          'date' => '1974-07-15',
          'time' => '04:00',
          'location' => {lat=>49.180000, lon=>-0.370000}
        });
    
        # 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',
        });
    
        ...

EXPORT

      * calculate_moon_phase()

SUBROUTINES

 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 date, in the
    form "YYYY-MM-DD", and optionally 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 {lon, lat}, the
    moon is observed from and this will deduce the timezone, albeit not
    always as accurately as with specifying a "timezone" explicitly.

    Astro::MoonPhase calculates the moon phase given an epoch. Which is the
    number of seconds since 1970-01-01 on a UTC timezone. This epoch is
    corrected to a 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 23:00-15:00=8:00 hours to that epoch to make it "localepoch" and
    this is what we pass on to Astro::MoonPhase to calculate the moon
    phase.

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

      * 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.

      * MoonPhase% : the above as a percentage.

      * 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.

      * MoonIllum% : the above as a percentage.

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

      * MoonDist : the distance of the Moon from the centre of the Earth
      (kilometers).

      * MoonAng : the angular diameter subtended by the Moon as seen by an
      observer at the centre of the Earth

      * SunDist : Moon's distance from the Sun (kilometers).

      * SunAng : the angular size of Sun (degrees).

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

      * asString : a string representation of the above.

SCRIPT

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

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

SEE ALSO

    This package summarises the post and discussion 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
    Astro::MoonPhase. Astro::MoonPhase does all the heavy lifting.

AUTHOR

    Andreas Hadjiprocopis, <bliako at cpan.org>

DEDICATIONS

    Marathon Almaz

BUGS

    Please report any bugs or feature requests to
    bug-astro-moonphase-simple at rt.cpan.org, or through the web interface
    at
    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.

SUPPORT

    You can find documentation for this module with the perldoc command.

        perldoc Astro::MoonPhase::Simple

    You can also look for information at:

      * RT: CPAN's request tracker (report bugs here)

      https://rt.cpan.org/NoAuth/Bugs.html?Dist=Astro-MoonPhase-Simple

      * Search CPAN

      https://metacpan.org/release/Astro-MoonPhase-Simple

ACKNOWLEDGEMENTS

    The authors of Astro::MoonPhase take all the credit.

LICENSE AND COPYRIGHT

    This software is Copyright (c) 2024 by Andreas Hadjiprocopis.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)