phase()

        ( $MoonPhase,
          $MoonIllum,
          $MoonAge,
          $MoonDist,
          $MoonAng,
          $SunDist,
          $SunAng )  = phase($seconds_since_1970);

          $MoonPhase = phase($seconds_since_1970);

The argument is the time for which the phase is requested, expressed as a time returned by the "time" function. If $seconds_since_1970 is omitted, it does "phase(time)".

Return value in scalar context is $MoonPhase, the terminator phase angle as a percentage of a full circle (i.e., 0 to 1).

Return values in array context:

$MoonPhase:

the terminator phase angle as a percentage of a full circle (i.e., 0 to 1)

$MoonIllum:

the illuminated fraction of the Moon's disc

$MoonAge:

the Moon's age in days and fraction

$MoonDist:

the distance of the Moon from the centre of the Earth

$MoonAng:

the angular diameter subtended by the Moon as seen by an observer at the centre of the Earth.

$SunDist:

the distance from the Sun in km

$SunAng:

the angular size of Sun in degrees

Example:

   ( $MoonPhase,
     $MoonIllum,
     $MoonAge,
     $MoonDist,
     $MoonAng,
     $SunDist,
     $SunAng ) = phase();

     print "MoonPhase  = $MoonPhase\n";
     print "MoonIllum  = $MoonIllum\n";
     print "MoonAge    = $MoonAge\n";
     print "MoonDist   = $MoonDist\n";
     print "MoonAng    = $MoonAng\n";
     print "SunDist    = $SunDist\n";
     print "SunAng     = $SunAng\n";

could print something like this:

     MoonPhase  = 0.598939375319023
     MoonIllum  = 0.906458030827876
     MoonAge    = 17.6870323368022
     MoonDist   = 372479.357420033
     MoonAng    = 0.534682403555093
     SunDist    = 152078368.820205
     SunAng     = 0.524434538105092

phasehunt()

     @phases = phasehunt($seconds_since_1970);

Finds time of phases of the moon which surround the given date. Five phases are found, starting and ending with the new moons which bound the current lunation.

The argument is the time, expressed as a time returned by the "time" function. If $seconds_since_1970 is omitted, it does "phasehunt(time)".

Example:

    @phases = phasehunt();
    print "New Moon      = ", scalar(localtime($phases[0])), "\n";
    print "First quarter = ", scalar(localtime($phases[1])), "\n";
    print "Full moon     = ", scalar(localtime($phases[2])), "\n";
    print "Last quarter  = ", scalar(localtime($phases[3])), "\n";
    print "New Moon      = ", scalar(localtime($phases[4])), "\n";

could print something like this:

    New Moon      = Wed Jun 24 06:51:47 1998
    First quarter = Wed Jul  1 21:42:19 1998
    Full moon     = Thu Jul  9 19:02:47 1998
    Last quarter  = Thu Jul 16 18:15:18 1998
    New Moon      = Thu Jul 23 16:45:01 1998

phaselist()

    ($phase, @times) = phaselist($start, $stop);

Finds times of all phases of the moon which occur on or after $start but before $stop. Both the arguments and the return values are expressed as seconds since 1970 (like the "time" function returns).

$phase is an integer indicating the phase of the moon at $times[0], as shown in this table:

    0  New Moon
    1  First quarter
    2  Full Moon
    3  Last quarter

The remaining values in @times indicate subsequent phases of the moon (in ascending order by time). If there are no phases of the moon between $start and $stop, "phaselist" returns the empty list.

Example:

    @name = ("New Moon", "First quarter", "Full moon", "Last quarter");
    ($phase, @times) = phaselist($start, $stop);

    while (@times) {
      printf "%-14s= %s\n", $name[$phase], scalar localtime shift @times;
      $phase = ($phase + 1) % 4;
    }

could produce the same output as the "phasehunt" example above (given the appropriate start & stop times).