NAME

Astro::Coord::ECI::Mixin - Provide common methods without multiple inheritance.

SYNOPSIS

In a class that wishes to add the next_quarter() method:

 use Astro::Coord::ECI::Mixin qw{ next_quarter };
 
 use constant NEXT_QUARTER_INCREMENT => 6 * 86400;      # Seconds

DESCRIPTION

This package provides code re-use without multiple inheritance. Classes that wish to make use of the methods simply import them. Some of the methods require manifest constants to be defined; these are specified with the method.

This package is private to the Astro::Coord::ECI package. Documentation is for the benefit of the author only. I am not opposed to making the interface public, but in the early going would like the liberty of being able to modify it without prior notice.

METHODS

This package supplies the following public methods:

almanac

 my @almanac = $body->almanac( $station, $start, $end );

This method produces almanac data for the $body for the given observing station, between the given start and end times. The station is assumed to be Earth-Fixed - that is, you can't do this for something in orbit.

The $station argument may be omitted if the station attribute has been set. That is, this method can also be called as

 my @almanac = $body->almanac( $start, $end )

The start time defaults to the current time setting of the $sun object, and the end time defaults to a day after the start time.

The almanac data consists of a list of list references. Each list reference points to a list containing the following elements:

 [0] => time
 [1] => event (string)
 [2] => detail (integer)
 [3] => description (string)

The @almanac list is returned sorted by time.

This mixin makes use of the following methods:

__almanac_event_type_iterator

 my $iterator = $self->__almanac_event_type_iterator( $station );

This method is passed an object representing the observing station, and must return a code reference to be used as an iterator.

The iterator is called without arguments. Each call returns a list representing a specific event to be reported on. The list consists of

 ( $invocant, $method, $args, $name, $detail )

where:

 $invocant is the object that generates the event;
 $method is the name of the method to call on the invocant;
 $args is a reference to an array of arguments to be passed
     to the method when it is called;
 $name is the name of the event type;
 $detail is the event detail.

The $detail return is either a reference to an array of event detail descriptions, or the name of a method to be called on the invocant and passed the event detail number. In the latter case the method is to return the event detail description.

almanac_hash

 my @almanac = $body->almanac_hash( $station, $start, $end );

This convenience method wraps $body->almanac(), but returns a list of hash references, sort of like Astro::Coord::ECI::TLE->pass() does. The hashes contain the following keys:

  {almanac} => {
    {event} => the event type;
    {detail} => the event detail (typically 0 or 1);
    {description} => the event description;
  }
  {body} => the original object ($sun);
  {station} => the observing station;
  {time} => the time the quarter occurred.

The {time}, {event}, {detail}, and {description} keys correspond to elements 0 through 3 of the list returned by almanac().

next_quarter

 my ( $time, $quarter, $desc ) = $body->next_quarter( $want );

This method calculates the time of the next quarter event after the current time setting of the $body object. The return is the time, which event it is as a number from 0 to 3, and a string describing the event. If called in scalar context, you just get the time.

The optional $want argument says which event you want.

As a side effect, the time of the $body object ends up set to the returned time.

The method of calculation is successive approximation, and actually returns the second after the calculated event.

This mixin makes use of the following methods:

NEXT_QUARTER_INCREMENT

This manifest constant is the approximate number of seconds to the next event. The approximation must undershoot in all cases.

__next_quarter_coordinate

This method calculates the coordinate that determines the next quarter. Typically it would be an alias for a longitude or phase method. This method is called in scalar context.

__quarter_name

This method calculates the name of a quarter given its number, and an optional reference to an array of quarter names. The optional argument is for the benefit of localization code.

next_quarter_hash

 my $hash_reference = $body->next_quarter_hash( $want );

This convenience method wraps $body->next_quarter(), but returns the data in a hash reference, sort of like Astro::Coord::ECI::TLE->pass() does. The hash contains the following keys:

  {body} => the original object ($body);
  {almanac} => {
    {event} => 'quarter',
    {detail} => the quarter number (0 through 3);
    {description} => the quarter description;
  }
  {time} => the time the quarter occurred.

The {time}, {detail}, and {description} keys correspond to elements 0 through 2 of the list returned by next_quarter().

This mixin makes use of the following method:

next_quarter

This is assumed to be the mixin described above.

ATTRIBUTES

This package can not define any public attributes.

SEE ALSO

The Astro::Coord::ECI::OVERVIEW|Astro::Coord::ECI::OVERVIEW documentation for a discussion of how the pieces/parts of this distribution go together and how to use them.

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2012-2016 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.

cpanm Astro::Coord::ECI

perl -MCPAN -e shell
install Astro::Coord::ECI