Instantiator

new

 $fmt = Astro::App::Satpass2::Format::Template->new();

This static method instantiates a new formatter.

Accessors and Mutators

local_coord

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

This method overrides the Astro::App::Satpass2::Format local_coord() method, and performs the same function.

Out of the box, legal values for this are consistent with the superclass' documentation; that is, 'az_rng', 'azel', 'azel_rng', 'equatorial', and 'equatorial_rng'. These are actually implemented as templates, as follows:

    az_rng        => <<'EOD',
    [% data.azimuth( arg, bearing = 2 ) %]
        [%= data.range( arg ) -%]
    EOD
 
    azel        => <<'EOD',
    [% data.elevation( arg ) %]
        [%= data.azimuth( arg, bearing = 2 ) -%]
    EOD
 
    azel_rng        => <<'EOD',
    [% data.elevation( arg ) %]
        [%= data.azimuth( arg, bearing = 2 ) %]
        [%= data.range( arg ) -%]
    EOD
 
    equatorial        => <<'EOD',
    [% data.right_ascension( arg ) %]
        [%= data.declination( arg ) -%]
    EOD
 
    equatorial_rng        => <<'EOD',
    [% data.right_ascension( arg ) %]
        [%= data.declination( arg ) %]
        [%= data.range( arg ) -%]
    EOD

These definitions can be changed, or new local coordinates added, using the template() method.

permissive

 print 'Formatter is ', $fmt->permissive() ? "permissive\n" : "not
permissive\n";
 $fmt->permissive( 1 );

This method is accessor and mutator for the "permissive" attribute. This attribute controls whether "Template-Toolkit" is permissive in the matter of what files it will load. By default it will only load files specified by relative paths without the 'up-directory' specification (.. under *nix). If true, absolute paths, and path containing the 'up-directory' specification are allowed.

If called with no argument, this method is an accessor, and returns the current value of the attribute.

If called with an argument, this method is a mutator, and sets a new value of the attribute. In this case, the invocant is returned.

The default is false, because that is the "Template-Toolkit" default. The reason for this is (in terms of this module)

 $fmt->format( template => '/etc/passwd' );

Formatters

As stated in the Astro::App::Satpass2::Format documentation, there is actually only one formatter method:

format

  print $fmtr->format( template => 'location', data => $sta );

This formatter implements the format() method using Template-Toolkit. The "template" argument is required, and selects one of the canned templates provided. The "data" argument is required unless your templates are capable of calling Astro::App::Satpass2 methods on their own account, and must (if provided) be whatever is expected by the template. See Templates below for the details.

This method can also execute an arbitrary template if you pass an Astro::App::Satpass2 object in the "sp" argument. These templates can call methods on the "sp" object to generate their data. If a method which calls the format() method on its own behalf (like almanac()) is called on the "sp" object, the recursive call is detected, and the data are passed back to the calling template. If arguments for Astro::App::Satpass2 methods are passed in, it is strongly recommended that they be passed in the "arg" argument.

Except for the "template" argument, all named arguments to format() are provided to the template. In addition, the following arguments will be provided:

instantiate

You can pass one or more class names as arguments. The argument is a class name which is loaded by the Astro::App::Satpass2::Utils load_package() subroutine. If the load succeeds, an object is instantiated by calling new() on the loaded class name, and that object is returned. If no class can be loaded an exception is thrown.

localize

This is a code reference to localization code. It takes two arguments: the string to localize, and an optional default if the string can not be localized for some reason. The second argument defaults to the first. A typical use would be something like

 [% localize( 'Location' ) %]
    

The localization comes from the locale system, specifically from key "{"-$template"}{string}{$string}", where $template is the name of the main template being used, and $string is the string to localize.

provider

This is simply the value returned by provider().

time

This is the current time wrapped in an Astro::App::Satpass2::FormatValue object.

title

This is an Astro::App::Satpass2::FormatValue configured to produce field titles rather than data.

TITLE_GRAVITY_BOTTOM

This manifest constant is defined in Astro::App::Satpass2::FormatValue. See the title_gravity() documentation for the details.

If the "title" object has its title_gravity() set to this value after template processing, and the output of the template has a leading newline, that newline is removed. See the Astro::App::Satpass2::FormatValue title_gravity() documentation for why this hack was imposed on the output.

TITLE_GRAVITY_TOP

This manifest constant is defined in Astro::App::Satpass2::FormatValue. See the title_gravity() documentation for the details.

In addition to any variables passed in, the following array methods are defined for "Template-Toolkit" before it is invoked:

bodies

If called on an array of objects, returns a reference to the results of calling body() on each of the objects. This is good for (e.g.) recovering a bunch of Astro::Coord::ECI::TLE objects from their containing Astro::App::Satpass2::FormatValue objects.

events

If called on an array of passes, returns all events in all passes, in chronological order.

fixed_width

If called on an array of Astro::App::Satpass2::FormatValue objects, calls fixed_width() on them. You may specify an argument to fixed_width().

Nothing is returned.

first_tle

If called on an array of Astro::App::Satpass2::FormatValue objects, returns the first whose body() method is an Astro::Coord::ECI::TLE or Astro::Coord::ECI::TLE::Set. If none is found, nothing is returned.

If called on an array of anything else the results are undefined.

Also, the following subroutines are defined:

localize

 [% localize( text ) %]
    

This localizes the given text. It is (more pr less) a wrapper for __localize(), which is called as

 scalar __localize(
     text    => [ "-$report", string => $text ],
     default => $text,
 );
    

where $report is the template being executed.

format_detail

 [% format_detail( 'event', evt ) %]
    

This is a generalized (though probably not generalized enough) mechanism for inserting data formatted by sub-templates that are selected based on the data being formatted. The arguments are the desired data type (which must be a method on Astro::App::Satpass2::FormatValue) and an object of type Astro::App::Satpass2::FormatValue). In practice, the specified method should return an enumerated value.

At the moment, 'event' is the only data type being used.

The implementation uses the first-found template named "$report:event:$type", "$report:event", where $report is the name of the main template (e.g. 'pass_ics', the 'event' is the method called to retrieve the data, and the $type is a specific value returned by the method.

Note that localize() is available, but it refers to the main template, not the sub-template.

add_formatter_method

 $tplt->add_formatter_method( \%definition );

This experimental method adds the named formatter to any Astro::App::Satpass2::FormatValue objects created. The argument is a reference to a hash that defines the format. The name of the formatter must appear in the "{name}" element of the hash, and this name may not duplicate any formatter built in to Astro::App::Satpass2::FormatValue, nor any formatter previously added by this method. The other elements in the hash are purposefully left undocumented until the whole business of adding a formatter becomes considerably less wooly and experimental.

What this really does is instantiate a Astro::App::Satpass2::FormatValue::Formatter and add that object to any Astro::App::Satpass2::FormatValue objects created.

Templates

The required values of the "template" argument are supported by same-named Template-Toolkit templates, as follows. The "data" provided should be as described in the documentation for the Astro::App::Satpass2 formatter() method. If the "data" value is not provided, each of the default templates will call an appropriate Astro::App::Satpass2 method on the "sp" value, passing it the "arg" value as arguments.

The following documentation no longer shows the default templates, since it has proven difficult to maintain. Instead it simply (and probably more helpfully) documents the circumstances under which each template is used. If you wish to display a default template you can do something like the following:

 $ satpass2 -initfile /dev/null
 satpass2> # Display the 'almanac' template
 satpass2> formatter -raw template almanac

Specifying the null device for -initfile ensures you get the default template, rather than one your own initialization file may have loaded. The example is for a Unix system; Windows and VMS users should substitute something appropriate. The "-raw" simply displays the value, rather than formatting it as a command to set the value.

almanac

This template is used by the almanac() and quarters() methods.

flare

This template is used by the flare() method.

list

This template is used by the list() method.

location

This template is used by the location() method.

pass

This template is used by the pass() method, unless the "-events" option is specified.

pass_events

This template is used by the pass() method if the "-events" option is specified. It orders events chronologically without respect to their source.

pass_ics

This template is used by the pass() method if the "-ics" option is specified. It formats passes as iCal entries.

phase

This template is used by the phase() method.

position

This template is used by the position() method.

tle

This template is used by the tle() method, unless "-verbose" is specified. Note that the default template does not generate a trailing newline, since the result of the body's tle() method is assumed to provide this.

tle_verbose

This template is used by the tle() method if "-verbose" is specified. It is assumed to provide some sort of formatted version of the TLE.

Other Methods

The following other methods are provided.

decode

 $fmt->decode( format_effector => 'azimuth' );

This method overrides the Astro::App::Satpass2::Format decode() method. In addition to the functionality provided by the parent, the following methods return something different when invoked via this method:

format_effector

If called as an accessor, the name of the formatter accessed is prepended to the returned array. If this leaves the returned array with just one entry, the string 'undef' is appended. The return is still an array in list context, and an array reference in scalar context.

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

format

 $fmt->format( template => $template, ... );

This method represents the interface to Template-Toolkit, and all the formatter methods come through here eventually.

The arguments to this method are name/value pairs. The "template" argument is required, and is either the name of a template file, or a reference to a string containing the template. All other arguments are passed to "Template-Toolkit" as variables. If argument "arg" is specified and its value is an array reference, the value is enclosed in an Astro::App::Satpass2::Wrap::Array object, since by convention this is the argument passed back to Astro::App::Satpass2 methods.

In addition to any variables passed in, the following array methods are defined for "Template-Toolkit" before it is invoked:

events

If called on an array of passes, returns all events in all passes, in chronological order.

fixed_width

If called on an array of Astro::App::Satpass2::FormatValue objects, calls fixed_width() on them. You may specify an argument to fixed_width().

Nothing is returned.

The canned templates can also be run as reports, and in fact will be taken in preference to files of the same name. If you do this, you will need to pass the relevant Astro::App::Satpass2 object as the "sp" argument, since by convention the canned templates all look to that variable to compute their data if they do not already have a "data" variable.

template

 print "Template 'almanac' is :\n", $fmt->template( 'almanac' );
 $fmt->template( almanac => <<'EOD' );
 [% UNLESS data %]
     [%- SET data = sp.almanac( arg ) %]
 [%- END %]
 [%- FOREACH item IN data %]
     [%- item.date %] [% item.time %]
         [%= item.almanac( units = 'description' ) %]
 [% END -%]
 EOD

This method is not inherited from Astro::App::Satpass2::Format.

If called with a single argument (the name of a template) this method is an accessor that returns the named template. If the named template does not exist, this method croaks.

If called with two arguments (the name of a template and the template itself), this method is a mutator that sets the named template. If the template is "undef", the named template is deleted. The object itself is returned, to allow call chaining.