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:

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.

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.

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.

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:

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.

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.

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.

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.

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.

If no argument is passed, the current value of tz is returned.

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.

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.

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:

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.

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.

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

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.

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:

Astro::Coord::ECI and associated modules, which are the intended providers of data for this functionality.

Astro::App::Satpass2::Format::Classic, which is a subclass of this module. It is a templating system producing text output which, by default, resembles the output of the original satpass script.

Astro::App::Satpass2::Format::Dump, which is a subclass of this module. It is intended for debugging, and simply dumps its arguments in Data::Dumper, JSON, or YAML format depending on how it is configured and what modules are installed