NAME

Astro::App::Satpass2::Format - Format Astro::App::Satpass2 output

SYNOPSIS

No user-serviceable parts inside.

DETAILS

This formatter is an abstract class providing output formatting functionality for Astro::App::Satpass2. It should not be instantiated directly.

This class is a subclass of Astro::App::Satpass2::Copier.

METHODS

This class supports the following public methods:

Instantiator

new

$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

date_format

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

There is actually only one formatter method. The subclass must provide it, because this class does not.

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

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

The following other methods are provided.

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.

SUPPORT

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-App-Satpass2, https://github.com/trwyant/perl-Astro-App-Satpass2/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

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.

To install Astro::App::Satpass2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::App::Satpass2

CPAN shell

perl -MCPAN -e shell
install Astro::App::Satpass2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)