NAME
Time::Keeper::Moon - the phases of the moon, as Time::Keeper values
VERSION
Version 0.01
SYNOPSIS
use Time::Keeper::Moon;
Time::Keeper::Moon->phase_name($t); # waxing_crescent
Time::Keeper::Moon->illumination($t); # 0.22
Time::Keeper::Moon->age($t); # 4.7 days since the new moon
Time::Keeper::Moon->next(phase => 'full', after => $t); # 2026-10-26T04:12:03Z
Time::Keeper::Moon->phases(from => $a, to => $b); # ([new, value], [first_quarter, value], ...)
Time::Keeper::Moon->on($date, zone => 'Asia/Tokyo'); # a Time::Keeper::Moon::DayDESCRIPTION
The instants of new moon, first quarter, full moon and last quarter, to a few seconds; and at any instant the moon's elongation from the sun, its phase angle, the fraction of its disk that is lit, its age and the name of its phase. The instants come from the periodic terms of Meeus's chapter 49; the fraction from his approximation 48.4, which is good to a few thousandths. See "ACCURACY".
Every value returned is a Time::Keeper value in the zone given (UTC otherwise), rounded to the whole second. Every method is a class method.
METHODS
phase_name
Time::Keeper::Moon->phase_name($t); # one of the eight belowThe phase at an instant, by eighths of the elongation: new within 22.5 degrees of the sun, then waxing_crescent, first_quarter, waxing_gibbous, full, waning_gibbous, last_quarter, waning_crescent. A day's name is a different question: see "phase_name" in Time::Keeper::Moon::Day.
elongation
The moon's elongation from the sun in longitude, degrees, 0 at new moon rising to 360: under 180 the moon is waxing.
phase_angle
The angle at the moon between the sun and the earth, degrees: 0 at full moon, 180 at new.
illumination
The fraction of the disk that is lit, 0 to 1.
age
Days since the last new moon, as a number.
lunation
The lunation number in Brown's series, in which the new moon of 17 January 1923 is lunation 1 (and that of 6 January 2000 is 953): the number of the lunation the instant falls in.
next
previous
Time::Keeper::Moon->next(phase => 'full'); # after now
Time::Keeper::Moon->next(phase => 'new', after => $t, zone => 'Asia/Tokyo');
Time::Keeper::Moon->previous(phase => 'last_quarter', before => $t);The first phase of the kind strictly after (or the last strictly before) an instant, which is now when none is given. phase is new, first_quarter, full or last_quarter; zone and locale shape the value returned.
phases
my @p = Time::Keeper::Moon->phases(from => $a, to => $b, zone => 'UTC');
# ([new, value], [first_quarter, value], [full, value], [last_quarter, value], ...)Every principal phase from one instant to another, inclusive, in order, each a reference to a two-element array of its name and its value; at most a year at a time.
on
my $day = Time::Keeper::Moon->on($date, zone => 'Europe/London');
my $day = Time::Keeper::Moon->on($t); # the value's date in the zone givenThe moon on a civil day in a zone, as a Time::Keeper::Moon::Day: the principal phase that falls in the day if there is one, else the name of the phase between, with the fraction and the age at local noon. The day is the zone's civil day, as "THE DAY" in Time::Keeper::Sun describes it; a value's date is taken in the zone given, not its own.
ACCURACY
The phase instants are those of chapter 49, which the book states to be within a few seconds of the ephemeris from 1980 to 2020; from 1900 to 2100 they agree with the U.S. Naval Observatory's published times to the minute. Outside that span Delta T's uncertainty enters one for one (see "DELTA T" in Time::Keeper::Sun). The illuminated fraction ignores the moon's latitude and the small terms of its longitude, and is within about 0.003 of the exact figure; the elongation and the phase angle within about a tenth of a degree.
SEE ALSO
Time::Keeper::Sun, Time::Keeper, Astro::MoonPhase.
AUTHOR
LNATION, <email at lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)