GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Astro::App::Satpass2::Format::Template(3) User Contributed Perl Documentation Astro::App::Satpass2::Format::Template(3)

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

 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,
     } );

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.

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

new

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

This static method instantiates a new formatter.

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' );

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.

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.

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.

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.

The following other methods are provided.

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

Thomas R. Wyant, III wyant at cpan dot org

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

2021-11-04 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.