Instantiator

 $fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(...);

This method instantiates a formatter. It may not be called on this class, but may be called on a subclass. If you wish to modify the default attribute values you can pass the relevant name/value pairs as arguments. For example:

 $fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(
     date_format => '%Y%m%d',
     time_format => 'T%H:%M:%S',
 );

Accessors and Mutators

 print 'Date format: ', $fmt->date_format(), "\n";
 $fmt->date_format( '%d-%b-%Y' );

The "date_format" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to format dates. This method may be overridden by subclasses, but the override must call "SUPER::date_format", and return values consistent with the following description.

This method acts as both accessor and mutator for the "date_format" attribute. Without arguments it is an accessor, returning the current value of the "date_format" attribute.

If passed an argument, that argument becomes the new value of "date_format", and the object itself is returned so that calls may be chained.

The interpretation of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses interpret this value as a "POSIX::strftime" format producing a date (but not a time), if they use this attribute at all.

The default value, if used by the subclass at all, should produce a numeric date of the form year-month-day. For formatters that use "strftime()", this will be '%Y-%m-%d'.

Note that this value will be reset to its default if the time_formatter attribute is modified and the new object has a different "FORMATTER_TYPE()" than the old one.

desired_equinox_dynamical

 print 'Desired equinox: ',
     strftime( '%d-%b-%Y %H:%M:%S dynamical',
         gmtime $fmt->desired_equinox_dynamical() ),
     "\n"; 
 $fmt->desired_equinox_dynamical(
     timegm( 0, 0, 12, 1, 0, 100 ) );   # J2000.0

The "desired_equinox_dynamical" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to calculate inertial coordinates. If the subclass does not make use of this attribute it must document the fact.

This method may be overridden by subclasses, but the override must call "SUPER::desired_equinox_dynamical", and return values consistent with the following description.

This method acts as both accessor and mutator for the "desired_equinox_dynamical" attribute. Without arguments it is an accessor, returning the current value of the "desired_equinox_dynamical" attribute.

If passed an argument, that argument becomes the new value of "desired_equinox_dynamical", and the object itself is returned so that calls may be chained.

The interpretation of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses interpret this value as a dynamical time (even though it is represented as a normal Perl time) if they use this attribute at all. If the value is true (in the Perl sense) inertial coordinates should be precessed to the dynamical time represented by this attribute. If the value is false (in the Perl sense) they should not be precessed.

gmt

 print 'Time zone: ', ( $fmt->gmt() ? 'GMT' : 'local' ), "\n";
 $fmt->gmt( 1 );

The "gmt" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to decide whether to display dates in GMT or in the local time zone. This method may be overridden by subclasses, but the override must call "SUPER::gmt", and return values consistent with the following description.

This method acts as both accessor and mutator for the "gmt" attribute. Without arguments it is an accessor, returning the current value of the "gmt" attribute. This value is to be interpreted as a Boolean under the usual Perl rules.

If passed an argument, that argument becomes the new value of "gmt", and the object itself is returned so that calls may be chained.

local_coord

 print 'Local coord: ', $fmt->local_coord(), "\n";
 $fmt->local_coord( 'azel_rng' );

The "local_coord" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to determine what coordinates to display. This method may be overridden by subclasses, but the override must call "SUPER::local_coord", and return values consistent with the following description.

This method acts as both accessor and mutator for the "local_coord" attribute. Without arguments it is an accessor, returning the current value of the "local_coord" attribute.

If passed an argument, that argument becomes the new value of "local_coord", and the object itself is returned so that calls may be chained. The interpretation of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses support at least the following values if they use this attribute at all:

 az_rng --------- azimuth and range;
 azel ----------- azimuth and elevation;
 azel_rng ------- azimuth, elevation and range;
 equatorial ----- right ascension and declination;
 equatorial_rng - right ascension, declination and range.

It is further recommended that "azel_rng" be the default.

provider

 print 'Provider: ', $fmt->provider(), "\n";
 $fmt->provider( 'Astro::App::Satpass2 v' . Astro::App::Satpass2->VERSION() );

The "provider" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to identify the provider of the data for informational purposes. This method may be overridden by subclasses, but the override must call "SUPER::provider", and return values consistent with the following description.

This method acts as both accessor and mutator for the "provider" attribute. Without arguments it is an accessor, returning the current value of the "provider" attribute.

If passed an argument, that argument becomes the new value of "provider", and the object itself is returned so that calls may be chained.

round_time

 print 'Time rounded to: ', $fmt->round_time(), " seconds\n";
 $fmt->round_time( 60 );

The "round_time" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to format times. This method may be overridden by subclasses, but the override must call "SUPER::round_time", and return values consistent with the following description.

This method acts as both accessor and mutator for the "round_time" attribute. Without arguments it is an accessor, returning the current value of the "round_time" attribute.

If passed an argument, that argument becomes the new value of "round_time", and the object itself is returned so that calls may be chained.

The interpretation of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses interpret this value in the same way as Astro::App::Satpass2::FormatTime if they use this attribute at all.

time_format

 print 'Time format: ', $fmt->time_format(), "\n";
 $fmt->time_format( '%H:%M:%S' );

The "time_format" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to format times. This method may be overridden by subclasses, but the override must call "SUPER::time_format", and return values consistent with the following description.

This method acts as both accessor and mutator for the "time_format" attribute. Without arguments it is an accessor, returning the current value of the "time_format" attribute.

If passed an argument, that argument becomes the new value of "time_format", and the object itself is returned so that calls may be chained.

The interpretation of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses interpret this value as a "POSIX::strftime" format producing a time (but not a date), if they use this attribute at all.

The default value, if used by the subclass at all, should produce a numeric time of the form hour:minute:second. For formatters that use "strftime()", this will be '%H:%M:%S'.

Note that this value will be reset to its default if the time_formatter attribute is modified and the new object has a different "FORMATTER_TYPE()" than the old one.

time_formatter

This method acts as both accessor and mutator for the object used to format times. It will probably be a Astro::App::Satpass2::FormatTime object of some sort, and will certainly conform to that interface. When setting the value, you can specify either a class name or an object. If a class name, the leading "Astro::App::Satpass2::FormatTime::" can be omitted.

Note that setting this will reset the date_format and time_format attributes to values appropriate to the new time formatter's class, if the new formatter object has a different "FORMATTER_TYPE()" than the old one.

tz

 print 'Time zone: ', $fmt->tz()->name(), "\n";
 $fmt->tz( 'MST7MDT' );

The "tz" attribute is maintained on behalf of subclasses of this class, which may (but need not) use it to format times. This method may be overridden by subclasses, but the override must call "SUPER::tz", and return values consistent with the following description.

This method acts as both accessor and mutator for the "tz" attribute. Without arguments it is an accessor, returning the current value of the "tz" attribute.

If passed an argument, that argument becomes the new value of "tz", and the object itself is returned so that calls may be chained.

The use of the argument is up to the subclass, but it is recommended for sanity's sake that the subclasses interpret this value as a time zone to be used to derive the local time if they use this attribute at all.

A complication is that subclasses may need to validate zone values. It is to be hoped that their digestions will be rugged enough to handle the usual conventions, since convention rather than standard seems to rule here.

value_formatter

This method acts as both accessor and mutator for the object used to format values. It will probably be a Astro::App::Satpass2::FormatValue object of some sort, and will certainly conform to that interface. When setting the value, you can specify either a class name or an object. If a class name, the leading "Astro::App::Satpass2::" can be omitted.

Author's note:

This method is experimental and unsupported. Documentation is for the benefit of the author and the curious. I wanted to screw around with extra formatters, and the best way to do that seemed to be to subclass "Astro::App::Satpass2::FormatValue", but then I needed a way to put the subclass into use. But I am not really ready to document the necessary interface (and therefore commit to not changing it, or at least not doing so without going through a deprecation cycle). If you have a need for this kind of thing, please contact me.

Formatters

format

 print $fmt->format( template => $name, data => $data );

This method takes named arguments.

The only required argument is "template", which specifies what kind of data are expected, and how it is to be formatted. These are described below. The name of the "template" argument assumes an implementation in terms of some sort of templating system, but a subclass can implement formatting in any way it pleases.

The "data" argument is normally required, and must be the data expected by the specified "template". However, if the formatter supports it, the "sp" argument can be specified in lieu of "data". The "sp" argument should be an Astro::App::Satpass2 object, and it only does anything if the specific formatter is capable of handling it.

The supported template names, and the data required by each, are as follows:

almanac

The $data argument is expected to be a reference to an array of hash references, which are presumed to be output from the "almanac_hash()" method of such Astro::Coord::ECI subclasses that have such a method.

flare

The $data argument is expected to be a reference to an array of hash references, which are presumed to be output from the Astro::Coord::ECI::TLE::Iridium "flare()" method.

list

The $data argument is expected to be a reference to an array of Astro::Coord::ECI or Astro::Coord::ECI::TLE::Set objects. The description generated by this method should be appropriate for a satellite.

location

The $data argument is expected to be an Astro::Coord::ECI object. This description should be appropriate for a ground station.

pass

The $data argument is expected to be a reference to an array of hash references, which are presumed to be output from the Astro::Coord::ECI::TLE "pass()" method.

pass_events

The $data argument is expected to be a reference to an array of hash references, which are presumed to be output from the Astro::Coord::ECI::TLE "pass()" method.

This template is expected to format a description of individual events of satellite passes for the pass command with the "-events" option.

phase

The $data argument is expected to be a reference to an array of "Astro::Coord::ECI|Astro::Coord::ECI" objects which support the "phase()" method and which have already had their time set to the desired time.

position

This template is intended to format the position (and possibly other data) of a set of bodies for the position command.

The $data argument is expected to be a hash containing relevant data. The following hash keys are required:

 {bodies} - a reference to an array of bodies to report;
 {station} - the observing station;
 {time} - the time to be reported;
    

Both "{bodies}" and "{station}" must contain Astro::Coord::ECI or "Astro::Coord::ECI::TLE::Set|Astro::Coord::ECI::TLE::Set" objects. The bodies must already have had their times set to the desired time.

In addition, the following keys are recommended:

 {questionable} - true to do flare calculations for questionable
         sources;
 {twilight} - twilight, in radians (negative).
    

If the "{twilight}" key is omitted, it will be set to civil twilight (i.e. the radian equivalent of -6 degrees).

Yes, this is more complex than the others, but the function is more ad-hoc.

tle

The $data argument is expected to be a reference to an array of Astro::Coord::ECI::TLE objects. The output should be compatible with the normal TLE format as documented at <http://celestrak.com>.

tle_verbose

The $data argument is expected to be a reference to an array of Astro::Coord::ECI::TLE objects. The output should be an expanded output of the data in a TLE (say, one line per datum, labeled and with units).

Other Methods

config

 use YAML;
 print Dump ( $pt->config( changes => 1 ) );

This method retrieves the configuration of the formatter as an array of array references. The first element of each array reference is a method name, and the subsequent elements are arguments to that method. Calling the given methods with the given arguments should reproduce the configuration of the formatter. If called in scalar context, it returns a reference to the array.

There are two named arguments:

changes

If this boolean argument is true (in the Perl sense), only changes from the default configuration are reported.

decode

If this boolean argument is true (in the Perl sense), the decode() method is used to obtain the configuration values.

Subclasses that add other ways to configure the object must override this method. The override must call "SUPER::config()", and include the result in the returned data.

decode

 $fmt->decode( 'desired_equinox_dynamical' );

This method wraps other methods, converting their returned values to human-readable. The arguments are the name of the method, and its arguments if any. The return values of methods not explicitly documented below are not modified.

The following methods return something different when invoked via this method:

desired_equinox_dynamical

If called as an accessor, the returned time is converted to an ISO-8601 time in the GMT zone. If called as a mutator, you still get back the object reference.

time_formatter

If called as an accessor, the class name of the object being used to format the time is returned. If called as a mutator, you still get back the object reference.

If a subclass overrides this method, the override should either perform the decoding itself, or delegate to "SUPER::decode".