Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Astro::App::Satpass2::UseraContributedsPeo::App::Satpass2::Format::Template(3)

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.

       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.

       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>, or in electronic mail to the author.

AUTHOR
       Thomas R. Wyant,	III wyant at cpan dot org

COPYRIGHT AND LICENSE
       Copyright (C) 2010-2020 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.

perl v5.32.1			  202Astro::App::Satpass2::Format::Template(3)

NAME | SYNOPSIS | DETAILS | METHODS | SUPPORT | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Astro::App::Satpass2::Format::Template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help