The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Date-ManipX-Almanac-0.000_903
River stage zero No dependents
++
/ Date::ManipX::Almanac::Date

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 = Christmas

and 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:

  • undef or 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

Date::Manip::Date.

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