NAME
Date::ManipX::Almanac::Date - Methods for working with almanac dates
SYNOPSIS
use Date::ManipX::Almanac::Date
my $dmad = Date::ManipX::Almanac::Date->new();
$dmad->config(
latitude => 38.8987, # Degrees; south is negative
longitude => -77.0377, # Degrees; west is negative
elevation => 17, # Meters, defaults to 0
name => 'White House', # Optional
);
$dmad->parse( 'sunrise today' );
$dmad->printf( 'Sunrise on %d-%b-%Y is %H:%M:%S' );DESCRIPTION
This Perl module implements a version of Date::Manip::Date that can parse a selection of almanac events. These are implemented using the relevant Astro::Coord::ECI classes.
This module is not an actual subclass of Date::Manip::Date, but holds a Date::Manip::Date object to perform a lot of the heavy lifting, and implements all its public methods, usually by delegating directly to Date::Manip::Date. This implementation was chosen because various portions of the Date::Manip::Date interface want an honest-to-God Date::Manip::Date object, not a subclass. The decision to implement this way may be revisited if the situation warrants.
In the meantime, be aware that if you are doing something like instantiating a Date::Manip::TZ from this object, you will have to use $dmad->dmd(), not $dmad.
Note that most almanac calculations are for a specific point on the Earth's surface. It would be nice to default this via the computer's geolocation API, but for at least the immediate future you must specify it explicitly. Failure to do this will result in an exception from parse() or parse_time() if an almanac event was actually specified.
The functional interface to Date::Manip::Date is not implemented. Neither is Date::Manip::DM5 functionality.
METHODS
This class provides the following public methods which are either in addition to those provided by Date::Manip::Date or provide additional functionality. Any Date::Manip::Date methods not mentioned below should Just Work.
new
my $dmad = Date::ManipX::Almanac::Date->new();The arguments are the same as the Date::Manip::Date new() arguments, but CONFIGURATION items specific to this class are supported.
new_date
my $dmad_2 = $dmad->new_date();The arguments are the same as the Date::Manip::Date new_date() arguments, but CONFIGURATION items specific to this class are supported.
new_config
my $dmad = Date::ManipX::Almanac::Date->new_config();The arguments are the same as the Date::Manip::Date new_config() arguments, but CONFIGURATION items specific to this class are supported.
calc
If the first argument is a Date::ManipX::Almanac::Date object, it is replaced by the underlying Date::Manip::Date object.
cmp
If the first argument is a Date::ManipX::Almanac::Date object, it is replaced by the underlying Date::Manip::Date object.
config
my $err = $dmad->config( ... );All Date::Manip::Date arguments are supported, plus those described under CONFIGURATION, below.
dmd
my $dmd = $dmad->dmd();This method returns the underlying Date::Manip::Date object.
err
This method returns a description of the most-recent error, or a false value if there is none. Errors detected in this package trump those in Date::Manip::Date.
get_config
my @config = $dmad->get_config( ... );All Date::Manip::Date arguments are supported, plus those described under CONFIGURATION, below.
parse
my $err = $dmad->parse( 'today sunset' );All Date::Manip::Date strings are supported, plus those described under ALMANAC EVENTS in Date::ManipX::Almanac::Lang.
parse_time
my $err = $dmad->parse_time( 'sunset' );All Date::Manip::Date strings are supported, plus those described under ALMANAC EVENTS in Date::ManipX::Almanac::Lang.
CONFIGURATION
This class uses the Date::Manip config() interface, but adds or modifies the following configuration items:
AlmanacConfigFile
This specifies a configuration file. This is formatted like a Date::Manip file, but can not have sections or any of the configuration items allowed in them. A Date::Manip-style section definition is treated as end-of-file, with a warning. This means you can not use AlmanacConfigFile to define holidays or events.
On the other hand, it can have any configuration items valid for this class, plus any valid in the top section of a Date::Manip configuration file.
Specifically, you can include other configuration files, via either AlmanacConfigFile or ConfigFile. Files included by ConfigFile can include anything a Date::Manip config file can (including event and holiday sections), but nothing specific to Date::ManipX::Almanac.
ConfigFile
This only modifies the embedded Date::Manip::Date object, though after all the dust settles the language of the embedded object is retrieved.
Caveat: It appears to be a restriction in Date::Manip::Date that if you configure (at least) Language after configuring a ConfigFile, any events and/or holidays configured by the nested file will not be retained. This makes sense when you think about it, because if you configure
December 25 = Christmasand then change the language to Spanish, you still can't say 'mediodia Navidad' unless you load a new holiday definition that supports this.
Defaults
In addition to its action on the superclass, this clears the location, and populates the sky with Astro::Coord::ECI::Sun and Astro::Coord::ECI::Moon.
Elevation
This specifies the elevation of the location, in meters above sea level.
Latitude
This specifies the latitude of the location, in degrees north (positive) or south (negative) of the Equator.
Language
In addition to its action on the superclass, this loads the almanac event definitions for the specified language. Note that this will fail unless a Date::ManipX::Almanac::Lang subclass has been implemented for the language.
Location
This specifies the location for which to compute the almanac. This can be specified as an Astro::Coord::ECI object, or undef to clear the location. Setting or clearing this also sets or clears Elevation, Latitude, Longitude, and Name.
Longitude
This specifies the longitude of the location, in degrees east (positive) or west (negative) of Greenwich.
Name
This specifies the name of the location. The name is used for display only, and is optional.
Sky
This can be specified as:
undefor the empty string ('').The previously-configured sky is cleared.
An Astro::Coord::ECI object (or subclass).
This is appended to the configured objects in the sky.
The name of an Astro::Coord::ECI class.
This class is instantiated, and the resultant object appended to the configured objects in the sky.
In general, you can only usefully specify objects this way if they can be instantiated by a call to
new(), without arguments.But there is a special case for Astro::Coord::ECI::Star. These can be specified by appending name, right ascension (in h:m:s), declination (in degrees), and optionally range in parsecs. The appended fields are parsed using
Text::ParseWords::shellwords(), so star names containing spaces can be either quoted (e.g.'Deneb Algedi') or reverse-solidus-escaped (e.g.Cor\ Caroli).A reference to an array of the above
The contents of the array replace the previously-configured sky.
Twilight
This specifies how far the Sun is below the horizon at the beginning or end of twilight. You can specify this in degrees, or as one of the following strings for convenience: 'civil' (6 degrees); 'nautical' (12 degrees); or 'astronomical' (18 degrees).
The default is civil twilight.
SEE ALSO
SUPPORT
Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Date-ManipX-Astro-Base, https://github.com/trwyant/perl-Date-ManipX-Astro-Base/issues/, or in electronic mail to the author.
AUTHOR
Thomas R. Wyant, III wyant at cpan dot org
COPYRIGHT AND LICENSE
Copyright (C) 2021-2022 by Thomas R. Wyant, III
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.