MoonPhase(3pm)

📦 version 0.60, in ubuntu stonking

💖 NAME 💖

Astro::MoonPhase — the whole entire tea on what the Moon is doing up there, phase-wise. She's giving astronomy, she's giving astrology-adjacent, she's giving "why is the moon so big tonight" energy. Periodt. 🌙✨

✨ SYNOPSIS ✨

okay bestie, here's the vibe. You load the module, and then you got options:

use Astro::MoonPhase;

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

        @phases  = phasehunt($seconds_since_1970);

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

Three little functions, three little moods. 🫶

🌸 DESCRIPTION 🌸

MoonPhase calculates information about the phase of the moon at a given time. That's it, that's the whole job, and she does it immaculately. No cap. 🔥

👑 FUNCTIONS 👑

🦋 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. And if you just don't pass $seconds_since_1970? No problem, she's flexible — she does phase(time) for you. 💅

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

look at those numbers. look at them. iconic. 💜

🎀 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. So she basically scoops you up a whole lunation arc, bookended by new moons. 😭🫶

The argument is the time, expressed as a time returned by the "time" function. Omit $seconds_since_1970 and she does phasehunt(time) for you, bestie behaviour fr fr.

⭐ 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

five timestamps, zero notes. immaculate. ✨

🧚 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). iykyk. 🕰️

$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). And if there are literally zero phases of the moon between $start and $stop? "phaselist" returns the empty list. nothing. nada. the void. 💀

🍓 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). so basically same energy, different entrance. 💫

🔭 ABOUT THE ALGORITHMS 🔭

The algorithms used in this program to calculate the positions of Sun and Moon as seen from the Earth are given in the book Practical Astronomy With Your Calculator by Peter Duffett-Smith, Second Edition, Cambridge University Press, 1981. Ignore the word "Calculator" in the title; this is an essential reference if you're interested in developing software which calculates planetary positions, orbits, eclipses, and the like. (the book is not playing around, ok? she's serious.) 📚

If you're interested in pursuing such programming, you should also obtain:

  • Astronomical Formulae for Calculators by Jean Meeus, Third Edition, Willmann-Bell, 1985. A must-have.
  • Planetary Programs and Tables from -4000 to +2800 by Pierre Bretagnon and Jean-Louis Simon, Willmann-Bell, 1986. If you want the utmost (outside of JPL) accuracy for the planets, it's here.
  • Celestial BASIC by Eric Burgess, Revised Edition, Sybex, 1985. Very cookbook oriented, and many of the algorithms are hard to dig out of the turgid BASIC code, but you'll probably want it anyway.

Many of these references can be obtained from Willmann-Bell, P.O. Box 35025, Richmond, VA 23235, USA. Phone: (804) 320-7016. In addition to their own publications, they stock most of the standard references for mathematical and positional astronomy.

bestie literally just wrote down a whole reading list and I respect it so much 🫶

💅 LICENCE 💅

This program is in the public domain: "Do what thou wilt shall be the whole of the law".

she's free. she's unbothered. she belongs to the people. periodt. 👑

🌟 AUTHORS 🌟

give it up for the people who built this 🌈

The moontool.c Release 2.0:

A Moon for the Sun
Designed and implemented by John Walker in December 1987,
revised and updated in February of 1988.

Initial Perl transcription:

Raino Pikkarainen, 1998
raino.pikkarainen@saunalahti.fi

The moontool.c Release 2.4:

Major enhancements by Ron Hitchens, 1989

Revisions:

Brett Hamilton  http://simple.be/
Bug fix, 2003
Second transcription and bugfixes, 2004

Christopher J. Madsen  http://www.cjmweb.net/
Added phaselist function, March 2007

and that's the whole page, bestie 💖 this was perl v5.40.1, dated 2026-05-05, and honestly she ate. go calculate some moons. 🌙✨

📦 where this page comes from