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

FreeBSD Manual Pages

  
 
  

home | help
Astro::App::Satpass2::UseraContributed Perl DocAstro::App::Satpass2::Format(3)

NAME
       Astro::App::Satpass2::Format - Format Astro::App::Satpass2 output

SYNOPSIS
       No user-serviceable parts inside.

DETAILS
       This formatter is an abstract class providing output formatting
       functionality for Astro::App::Satpass2. It should not be	instantiated
       directly.

       This class is a subclass	of Astro::App::Satpass2::Copier.

METHODS
       This class supports the following public	methods:

   Instantiator
       new

	$fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(...);

       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:

	$fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(
	    date_format	=> '%Y%m%d',
	    time_format	=> 'T%H:%M:%S',
	);

   Accessors and Mutators
       date_format

	print 'Date format: ', $fmt->date_format(), "\n";
	$fmt->date_format( '%d-%b-%Y' );

       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.

       desired_equinox_dynamical

	print 'Desired equinox:	',
	    strftime( '%d-%b-%Y	%H:%M:%S dynamical',
		gmtime $fmt->desired_equinox_dynamical() ),
	    "\n";
	$fmt->desired_equinox_dynamical(
	    timegm( 0, 0, 12, 1, 0, 100	) );   # J2000.0

       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.

       gmt

	print 'Time zone: ', ( $fmt->gmt() ? 'GMT' : 'local' ),	"\n";
	$fmt->gmt( 1 );

       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.

       local_coord

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

       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:

	az_rng --------- azimuth and range;
	azel ----------- azimuth and elevation;
	azel_rng ------- azimuth, elevation and	range;
	equatorial ----- right ascension and declination;
	equatorial_rng - right ascension, declination and range.

       It is further recommended that "azel_rng" be the	default.

       provider

	print 'Provider: ', $fmt->provider(), "\n";
	$fmt->provider(	'Astro::App::Satpass2 v' . Astro::App::Satpass2->VERSION() );

       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.

       round_time

	print 'Time rounded to:	', $fmt->round_time(), " seconds\n";
	$fmt->round_time( 60 );

       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.

       time_format

	print 'Time format: ', $fmt->time_format(), "\n";
	$fmt->time_format( '%H:%M:%S' );

       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.

       time_formatter

       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.

       tz

	print 'Time zone: ', $fmt->tz()->name(), "\n";
	$fmt->tz( 'MST7MDT' );

       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.

       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.

       value_formatter

       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.

   Formatters
       There is	actually only one formatter method. The	subclass must provide
       it, because this	class does not.

       format

	print $fmt->format( template =>	$name, data => $data );

       This method takes named arguments.

       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:

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

       flare
	   The $data argument is expected to be	a reference to an array	of
	   hash	references, which are presumed to be output from the
	   Astro::Coord::ECI::TLE::Iridium "flare()" method.

       list
	   The $data argument is expected to be	a reference to an array	of
	   Astro::Coord::ECI or	Astro::Coord::ECI::TLE::Set objects. The
	   description generated by this method	should be appropriate for a
	   satellite.

       location
	   The $data argument is expected to be	an Astro::Coord::ECI object.
	   This	description should be appropriate for a	ground station.

       pass
	   The $data argument is expected to be	a reference to an array	of
	   hash	references, which are presumed to be output from the
	   Astro::Coord::ECI::TLE "pass()" method.

       pass_events
	   The $data argument is expected to be	a reference to an array	of
	   hash	references, which are presumed to be output from the
	   Astro::Coord::ECI::TLE "pass()" method.

	   This	template is expected to	format a description of	individual
	   events of satellite passes for the pass command with	the "-events"
	   option.

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

       position
	   This	template is intended to	format the position (and possibly
	   other data) of a set	of bodies for the position command.

	   The $data argument is expected to be	a hash containing relevant
	   data.  The following	hash keys are required:

	    {bodies} - a reference to an array of bodies to report;
	    {station} -	the observing station;
	    {time} - the time to be reported;

	   Both	"{bodies}" and "{station}" must	contain	Astro::Coord::ECI or
	   "Astro::Coord::ECI::TLE::Set|Astro::Coord::ECI::TLE::Set" objects.
	   The bodies must already have	had their times	set to the desired
	   time.

	   In addition,	the following keys are recommended:

	    {questionable} - true to do	flare calculations for questionable
		    sources;
	    {twilight} - twilight, in radians (negative).

	   If the "{twilight}" key is omitted, it will be set to civil
	   twilight (i.e. the radian equivalent	of -6 degrees).

	   Yes,	this is	more complex than the others, but the function is more
	   ad-hoc.

       tle The $data argument is expected to be	a reference to an array	of
	   Astro::Coord::ECI::TLE objects. The output should be	compatible
	   with	the normal TLE format as documented at <http://celestrak.com>.

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

   Other Methods
       The following other methods are provided.

       config

	use YAML;
	print Dump ( $pt->config( changes => 1 ) );

       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.

       There are two named arguments:

       changes
	   If this boolean argument is true (in	the Perl sense), only changes
	   from	the default configuration are reported.

       decode
	   If this boolean argument is true (in	the Perl sense), the decode()
	   method is used to obtain the	configuration values.

       Subclasses that add other ways to configure the object must override
       this method. The	override must call "SUPER::config()", and include the
       result in the returned data.

   decode
	$fmt->decode( 'desired_equinox_dynamical' );

       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:

       desired_equinox_dynamical
	   If called as	an accessor, the returned time is converted to an
	   ISO-8601 time in the	GMT zone. If called as a mutator, you still
	   get back the	object reference.

       time_formatter
	   If called as	an accessor, the class name of the object being	used
	   to format the time is returned. 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".

SEE ALSO
       Astro::App::Satpass2, which is the intended user	of this	functionality.

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

       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

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			  2020-08-02   Astro::App::Satpass2::Format(3)

NAME | SYNOPSIS | DETAILS | METHODS | SEE ALSO | 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&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help