/ 
Astro-App-Satpass2-0.051_01
River stage zero No dependents
/ Astro::App::Satpass2::Format::Template

NAME

Astro::App::Satpass2::Format::Template - Format Astro::App::Satpass2 output as text.

SYNOPSIS

 use strict;
 use warnings;
 
 use Astro::App::Satpass2::Format::Template;
 use Astro::Coord::ECI;
 use Astro::Coord::ECI::Moon;
 use Astro::Coord::ECI::Sun;
 use Astro::Coord::ECI::Utils qw{ deg2rad };
 
 my $time = time();
 my $moon = Astro::Coord::ECI::Moon->universal($time);
 my $sun = Astro::Coord::ECI::Sun->universal($time);
 my $station = Astro::Coord::ECI->new(
     name => 'White House',
 )->geodetic(
     deg2rad(38.8987),  # latitude
     deg2rad(-77.0377), # longitude
     17 / 1000);	# height above sea level, Km
 my $fmt = Astro::App::Satpass2::Format::Template->new();
 
 print $fmt->location( $station );
 print $fmt->position( {
	 bodies => [ $sun, $moon ],
	 station => $station,
	 time => $time,
     } );

DETAILS

This class is intended to perform output formatting for Astro::App::Satpass2, producing output similar to that produced by the satpass script distributed with Astro::Coord::ECI. It is a subclass of Astro::App::Satpass2::Format, and conforms to that interface.

The Astro::App::Satpass2::Format interface specifies a set of methods corresponding (more or less) to the interactive methods of Astro::App::Satpass2. This class implements those methods in terms of a canned set of Template-Toolkit templates, with the data from the Astro::App::Satpass2 methods wrapped in Astro::App::Satpass2::FormatValue objects to provide formatting at the field level.

The names and contents of the templates used by each formatter are described with each formatter. The templates may be retrieved or modified using the template() method.

METHODS

This class supports the following public methods. Methods inherited from Astro::App::Satpass2::Format are documented here if this class adds significant functionality.

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.

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.

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

Copyright (C) 2010-2023 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.