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

FreeBSD Manual Pages

  
 
  

home | help
Astro::App::Satpass2(3User Contributed Perl DocumentatiAstro::App::Satpass2(3)

NAME
       Astro::App::Satpass2 - Forecast satellite visibility.

SYNOPSIS
	use Astro::App::Satpass2;
	# Instantiate and set our location
	my $satpass2 = Astro::App::Satpass2->new(
	    location =>	'1600 Pennsylvania Ave,	Washington DC',
	    latitude =>	38.898748,    #	degrees
	    longitude => -77.037684,  #	degrees
	    height => 16.68,	      #	meters
	);
	# Acquire ISS data from	Celestrak
	$satpass2->spacetrack( qw{ celestrak stations }	);
	# Remove other bodies in the Celestrak 'stations' catalog
	$satpass2->choose( 25544 );
	# Display our location
	$satpass2->location();
	# Display visible ISS passes over our location
	$satpass2->pass();

       Or equivalently,	from the satpass2 script which is installed with this
       package,

	$ satpass2
		 ... front matter displayed here ...
	satpass2> # set	our location
	satpass2> set location '1600 Pennsylvania Ave, Washington DC'
	satpass2> set latitude 38.898748 longitude -77.037684
	satpass2> set height 16.68
	satpass2> # Acquire ISS	data from Celestrak
	satpass2> spacetrack celestrak stations
	satpass2> # Remove other bodies	in the Celestrak 'stations' catalog
	satpass2> choose 25544
	satpass2> # Display our	location
	satpass2> location
	satpass2> # Display visible ISS	passes over our	location
	satpass2> pass
	satpass2> # Guess what
	satpass2> exit

       The script is implemented in terms of the run() method. Blank lines and
       comments	are ignored. The first token in	the line is the	method name,
       and subsequent tokens are arguments to that method. See run() for the
       details of that method, and "TOKENIZING"	for details of the tokenizer.
       Finally,	see initfile() for where to put	your initialization file,
       which is	just a script that gets	executed every time you	invoke the
       run() method.

       If you want to be interactive, simply

	use Astro::App::Satpass2;
	Astro::App::Satpass2->run(@ARGV);

       which is	essentially the	content	of the satpass2	script.	 In this last
       case, the user will be prompted for commands once the commands in @ARGV
       are used	up, unless those commands include 'exit'.

NOTICE
       Geocoding using TomTom has been dropped as of version 0.024.  The old,
       undocumented interface has been dropped,	and the	new one	requires an
       API key.

       The eventual plan is to retire the satpass script in favor of this
       package,	and to rename the satpass-less Astro-satpass distribution to
       Astro-Coord-ECI.

OVERVIEW
       This class implements an	application to predict satellite visibility
       and related phenomena. It is a mostly-compatible	rewrite	and eventual
       replacement of the satpass script in distribution "Astro-satpass",
       aimed at	making it easier to test, and removing some of the odder cruft
       that has	accumulated in the satpass script.

       The easiest way to make use of this class is via	the bundled satpass2
       script, which simply calls the run() method.
       Astro::App::Satpass2::TUTORIAL covers getting started with this script.
       If you do nothing else, see the tutorial	on setting up an
       initialization file, since the satpass2 script will be much more	easy
       to use if you configure some things up front.

       You can also instantiate	an "Astro::App::Satpass2" object yourself and
       access all its functionality programmatically. If you are doing this
       you may still want to consult the TUTORIAL, because the satpass2
       commands	correspond directly to "Astro::App::Satpass2" methods.

Optional Modules
       An attempt has been made	to keep	the requirements of this module
       reasonably modest. But there are	a number of optional modules which, if
       installed, give you increased functionality. If you do not install
       these initially and find	you want the added functionality, you can
       always install them later. The optional modules are:

       Astro::SIMBAD::Client
	   This	module looks up	the positions of astronomical bodies in	the
	   SIMBAD database at <http://simbad.u-strasbg.fr/simbad/>. This is
	   only	used by	the "lookup" subcommand	of the sky() method.

       Astro::SpaceTrack
	   This	module retrieves satellite orbital elements from various
	   sources.  Since you have to have these to predict satellite
	   positions, this is the least	optional of the	optional modules.
	   Without it, you would have to download orbital elements some	other
	   way and then	use the	load() method to import	them into
	   "Astro::App::Satpass2".

       Date::Manip
	   This	module is a very flexible (and very large) time	parser.	If it
	   is installed, "Astro::App::Satpass2"	will use it to parse times. If
	   it is not available a home-grown ISO-8601-ish parser	will be	used.
	   There are really three options here:

	   * If	you have Perl 5.10 or above, you have the full functionality
	   of Date::Manip.

	   * If	you a Perl before 5.10,	you can	(as of this writing) install
	   the latest Date::Manip, but you will	be using the version 5 back
	   end,	which may not support summer time (a.k.a. daylight saving
	   time) and may have other deficiencies versus	the current release.

	   * The home-grown parser is
	   Astro::App::Satpass2::ParseTime::ISO86O1.  This does	not support
	   summer time,	nor time zones other than the user's default time and
	   GMT.	Dates and times	must be	specified as numeric year-month-day
	   hour:minute:second, though there is some flexibility	on
	   punctuation,	and as a convenience you can use "yesterday", "today",
	   or "tomorrow" in lieu of the	"year-month-day".

       DateTime	and DateTime::TimeZone
	   If both of these are	available, "Astro::App::Satpass2" will use
	   them	to format dates. If they are not, it will use
	   "POSIX::strftime". If you are using "POSIX::strftime", time zones
	   other than the default time zone and	GMT are	not supported, though
	   if you set the tz attribute "Astro::App::Satpass2" will place its
	   value in $ENV{TZ} before calling "strftime()" in case the
	   underlying code pays	attention to this.

	   If you have DateTime	and DateTime::TimeZone installed,
	   "Astro::App::Satpass2" will let you use "Cldr" time formats if you
	   like, instead of "strftime" formats.

       Geo::Coder::OSM
	   This	module is used by the Open Street Map geocoder for the
	   geocode() method. If	you are	not interested in using	the geocode()
	   method you do not need this module.

       Geo::WebService::Elevation::USGS
	   This	module is only used by the height() method, or indirectly by
	   the geocode() method. If you	are not	interested in these you	do not
	   need	this module.

       LWP::UserAgent
	   This	module is only used directly if	you are	specifying URLs	as
	   input (see "SPECIFYING INPUT	DATA").	It is implied, though, by a
	   number of the other optional	modules.

       LWP::Protocol
	   This	module is only used directly if	you are	specifying URLs	as
	   input (see "SPECIFYING INPUT	DATA").	It is implied, though, by a
	   number of the other optional	modules.

       Term::ReadLine
	   If this can be loaded and it	can load "Term::ReadLine::Perl"	you
	   get interactive command editing and completion.

       Time::HiRes
	   This	module is only used by the time() method. If you are not
	   interested in finding out how long things take to run, you do not
	   need	this module.

       Time::y2038
	   This	module is only needed if you are interested in times outside
	   the range of	times representable in your Perl. This was typically
	   1970	through	2038 in	32-bit Perls before Perl 5.12. In Perl 5.12
	   the Y2038 bug was fixed, and	a much wider range of times is
	   available. You may also find	that a wider range of times is
	   available in	64-bit Perls.

	   At least some versions of Time::y2038 have had trouble on Windows-
	   derived systems, including Cygwin. Caveat user.

       URI This	module is only used directly if	you are	specifying URLs	as
	   input (see "SPECIFYING INPUT	DATA").	It is implied, though, by a
	   number of the other optional	modules, including LWP::UserAgent.

METHODS
       Most methods simply correspond to commands in the "satpass2" script,
       and the arguments correspond to arguments in the	script.	Such methods
       will be identified in the following as 'interactive methods.'

       An interactive method call is one that is made via the dispatch()
       method, however called, and includes methods called via execute() or
       run() (i.e. satpass2 scripts).

       When the	documentation specifies	that an	interactive method takes
       options,	they may be specified either as	command-style options or as a
       hash.

       If options are specified	command-style, the option name must be
       preceded	by a dash, and may be abbreviated. Option arguments are	either
       specified as a separate argument	or appended to the option name.

       If options are specified	in a hash, a reference to the hash must	be the
       first argument to the method. The hash keys are the option names	(in
       full, but without leading dashes), and the hash values are the values
       of the options.

       For example, hypothetical method	"foo()"	may be called with boolean
       option "bar" and	string option "baz" in any of the following ways:

	$satpass2->foo(	'-bar',	-baz =>	'burfle' );
	$satpass2->foo(	'-bar',	'-baz=burfle' );
	$satpass2->foo(	{ bar => 1, baz	=> 'burfle' } );

       In addition to the documented options (if any) any interactive method
       will accept option "default". This takes	a string, which	is parsed to
       provide defaults	for positional arguments. If calling the method	from
       code you	can also specify an array reference and	bypass the parsing.
       This option is probably only useful in source files. As an example, a
       source file that	does a two-day almanac starting	at noon	of the current
       day (but	allowing the user to override this by specifying arguments to
       "source") might contain

	almanac	-default "'today noon' +2" "$@"

       For ease	of use with templating systems such as Template-Toolkit	most
       interactive methods flatten array references in their argument list.
       The only	exception is the "set()" method, which may need	to receive an
       array reference as the value of an attribute.

       A few methods are used for manipulating the "Astro::App::Satpass2"
       object itself, or for doing things not available	to the "satpass2"
       script.	These are identified as	'non-interactive methods.'

       When the	documentation says 'nothing is returned', this means the
       subroutine returns with a "return" statement without an argument, which
       returns "undef" in scalar context, and an empty list in list context.

   new
	$satpass2 = Astro::Satpass2->new();

       This non-interactive method instantiates	a new Astro::Satpass2 object.
       Any arguments are passed	to the set() method.

   add
	$satpass2->add(	@bodies	);

       This non-interactive method adds	its arguments to the observing list.
       An exception is raised if any argument does not represent an
       Astro::Coord::ECI::TLE object.

       The invocant is returned.

   alias
	$output	= $satpass2->alias();
	satpass2> alias

       This interactive	method just wraps the Astro::Coord::ECI::TLE "alias()"
       method, which returns the known class name aliases. The output is zero
       or more lines of	text, each line	giving an alias	and its	equivalent
       class.

       If arguments are	given, they should be pairs of aliases and class
       names, and will add to or replace the currently-known aliases. If the
       class name is false in the Perl sense (i.e. '', 0, or undef) the	alias,
       if it exists, is	deleted.

   almanac
	$output	= $satpass2->almanac(...);
	satpass2> almanac

       This interactive	method returns almanac data for	the current location.
       This consists of	all data returned by the "almanac()" method for	all
       objects in the sky which	support	this method.

       It takes	up to two arguments, which represent start time	and end	time.
       The default start time is midnight of the current day in	the local time
       zone, or	in GMT if the "gmt" attribute is true. The default end time is
       a day after the current start time. See "SPECIFYING TIMES" for how to
       specify times.

       The following options are recognized:

	-choose	chooses	objects	to report;
	-dump produces debugging output;
	-horizon produces rise/set times;
	-quarter produces quarter events;
	-rise is a synonym for -horizon;
	-set is	a synonym for -horizon;
	-transit reports transit across	zenith or (sometimes) nadir;
	-twilight reports begin/end of twilight.

       Option "-dump" is unsupported in	the sense that the author makes	no
       commitments as to what it does, nor does	he commit not to change	or
       remove it without notice.

       Option "-choose"	chooses	which objects to report. It takes as an
       argument	the names of one or more bodies	(case-insensitive), separated
       by commas, and it can be	specified multiple times. If "-choose" is not
       specified, all objects in the sky are reported.

       The other options specify what output to	produce. If none are
       specified, all are turned on by default.	If only	negated	options	are
       specified (e.g. -noquarter), unspecified	options	are asserted by
       default.	 Otherwise unspecified options are considered to be negated.

       Note well that unlike the satpass script, the output from this method
       does not	normally include location. The location	is included only if
       the command is issued from a satpass initialization file	(as opposed to
       an "Astro::App::Satpass2" initialization	file), or from a macro defined
       in a satpass initialization file. This functionality will be revoked
       when support for	the satpass script is dropped.

   begin
	$satpass2->begin();
	satpass2> begin

       This interactive	method begins a	localization block, which extends to
       the corresponding end() or to the end of	the source file	or macro.
       Nothing is returned.

   cd
	$satpass2->cd();
	satpass2> cd

       This interactive	method changes to the users' home directory, or	to the
       given directory if one is specified as an argument. Tilde expansion is
       done on the argument if appropriate. Nothing is returned.

       Caveat: I get a test failure in the no-argument case under FreeBSD 6.2.
       The failure is because "File::HomeDir->my_home()" thinks	the user's
       home directory is /home/foo, but	when I do a "chdir()" to that
       directory, "Cwd::cwd" reports that I am in /usr/home/foo.  All the
       other CPAN testers are running 9.0, and under this the test passes. So
       I am unsure of the extent to which this is a problem. If	this turns out
       to be a problem for you,	I am willing to	fix it,	but will probably need
       some guidance on	what is	actually going on. In the meantime I have had
       t/whole_app.t make the test for this a "TODO" under FreeBSD before 7.0.

   choose
	$satpass2->choose( 25544, 'hst'	)
	satpass2> choose 25544 hst

       This interactive	method drops from the observing	list any objects that
       do not meet the given selection criteria. Numbers greater than 999 are
       taken to	represent OID numbers, and compared to each object's 'id'
       attribute.  Anything else is made into a	regular	expression and matched
       to the object's 'name' attribute.

       The following options may be specified:

	-epoch to select the best item for the given epoch.

       Nothing is returned.

       An exception is raised if the operation would leave the observing list
       empty.

   clear
	$satpass2->clear();
	satpass2> clear

       This interactive	method clears the observing list. It takes no
       arguments. Nothing is returned.

   dispatch
	$output	= $satpass2->dispatch( 'flare',	'today 12:00:00', '+1' );

       This non-interactive method takes as its	arguments the name of an
       interactive method and its arguments, calls the method, and returns
       whatever	the method calls.

       Any method executed via this method is considered to have been executed
       interactively.

   drop
	$satpass2->drop( 25544,	'hst' );
	satpass2> drop 25544 hst

       This interactive	method inverts the sense of choose(), removing from
       the observing list all bodies that match	the selection criteria.

       Nothing is returned.

       An exception is raised if the operation would leave the observing list
       empty.

   dump
	$output	= $satpass2->dump();
	satpass2> dump

       This interactive	method is unsupported, and is used for debugging
       purposes. It may	disappear, or its functionality	change,	without
       notice.

       Currently it loads a dumper class (either some "YAML" module or
       "Data::Dumper") and returns a dump of the "Astro::App::Satpass2"
       object.

       If it is	given arguments, those arguments are dumped. Specifically:

       A reference specifies that the referent is dumped;
       'frame' specifies that the frame	stack is dumped;
       'tokens'	specifies that the next	argument is tokenized and dumped;
       'twilight' specifies the	twilight settings are dumped;
       Anything	else causes the	specified body to be dumped.

       This interactive	method will be executed	even inside an unsatisfied
       if().

   echo
	$output	= $satpass2->echo( 'Hello, sailor!' );
	satpass2> echo 'Hello, sailor!'

       This interactive	method joins its arguments with	spaces,	appends	a
       newline,	and returns the	result.	It is so named because it is
       anticipated that	the caller will	print the result.

       The following option may	be specified:

	-n to suppress the newline at the end of the echoed text.

   elsif
	$output	= $satpass2->elsif( qw{	env FUBAR then } );
	satpass2> elsif	env FUBAR then

       This interactive	method can appear only after an	"if ...	then begin" or
       another "elsif ... then". It is not evaluated if	the previous "if()" or
       any previous "elsif()" was true,	and causes all subsequent "elsif()" or
       "else()"	not to be evaluated until the closing "end()".

   else
	$satpass2->else();
	satpass2> else

       This interactive	method can appear only after an	"if ...	then begin".
       It inverts the sense of the original test, so that if it	was true
       statements after	the "else" are not executed, and vice versa.

   end
	$satpass2->end();
	satpass2> end

       This interactive	method ends a localization block. Nothing is returned.
       It is an	error to have an end without a corresponding begin().

   error
	$satpass2->error( 'Something happened' );
	satpass2> error	'Something happened'

       This interactive	method declares	an error, terminating the processing
       of the macro or include file in which it	appears. The arguments are
       used as the text	of the error message. If none are provided a default
       (and unhelpful) error message is	provided.

   execute
	$output	= $satpass2->execute( <<'EOD' );
	spacetrack set direct 1
	spacetrack celestrak stations
	choose iss
	pass 'today 12:00:00' +7
	EOD

       This non-interactive method takes as its	arguments lines	of text. The
       arguments are split on "\n". Each line is tokenized (see	"TOKENIZING"
       for the details), output	redirection is performed, and the tokens are
       passed to dispatch() for	execution.  Exceptions raised by dispatch() or
       the methods it calls will not be	trapped.

       The output of dispatch()	is sent	to whatever output is selected.	If no
       output at all is	selected (that is, if the "stdout" attribute is
       "undef" and no output redirection was specified)	the output will	be
       returned.  Otherwise undef will be returned.

       Blank lines, and	lines beginning	with '#' (comments) are	ignored.

   exit
	$satpass2->exit();
	satpass2> exit

       This interactive	method is used to unwind the context stack and
       terminate execution. If executed	in a block labeled SATPASS2_EXECUTE
       (as in the "run"	method for example), it	does a 'last' on that block.
       Otherwise it displays a warning to STDERR and exits Perl. Nothing is
       returned.

   export
	$satpass2->export( $name [, $value] );
	satpass2> export name [	value ]

       This interactive	method exports the value of the	named attribute	to an
       environment variable having the same name. If the optional value
       argument	is passed, the value of	the attribute is set.

       If the named attribute does not exist, an environment variable of the
       given name is created, and assigned the given value, which in this case
       is not optional.

       Either way, nothing is returned.

       Once an attribute has been exported, the	environment variable tracks
       changes in the value of the attribute. This includes not	only explicit
       changes,	but those made as a result of leaving a	localization block.

   flare
	$output	= $satpass2->flare( 'today 18:00', '+1'	);
	satpass2> flare	'today 18:00' +1

       This interactive	method predicts	flares from any	bodies in the
       observing list capable of flaring. The optional arguments are the start
       time of the prediction (defaulting to the current day at	noon) and the
       end time	of the prediction (defaulting to '+7').	See "SPECIFYING	TIMES"
       for how to specify times.

       The following options are available:

       "-am" displays morning flares --	that is, those after midnight but
       before morning twilight.	This can be negated by specifying "-noam".

       "-choose" chooses bodies	from the observing list. It works the same way
       as the choose method, but does not alter	the observing list. You	can
       specify multiple	bodies by specifying -choose multiple times, or	by
       separating your choices with commas. If -choose is not specified, the
       whole observing list is used.

       "-day" displays daytime flares -- that is, those	between	morning
       twilight	and evening twilight. This can be negated by specifying
       "-noday".

       "-pm" displays evening flares --	that is, those between evening
       twilight	and midnight. This can be negated by specifying	"-nopm".

       "-questionable" requests	that satellites	whose status is	questionable
       (i.e. 'S') be included. Typically these are spares, or moving between
       planes. You may use "-spare" as a synonym for this.

       "-quiet"	suppresses any errors generated	by running the orbital model.
       These are typically from	obsolete data, and/or decayed satellites.
       Bodies that produce errors will not be included in the output.

       "-tz=zone" allows you to	specify	an explicit time zone for the
       "-pm"/"-am" determination. If you do not	specify	this, it relies	on the
       "formatter" "gmt" and "tz" settings, in that order.

       "-zone=zone" is a synonym for "-tz=zone".

       Note well that the sense	of the "-am", "-day", and "-pm"	options	is
       opposite	to that	in the satpass script. However,	if they	are used in a
       satpass initialization script, or in a macro defined in a satpass
       initialization script, the satpass sense	of these options will be used,
       and they	will be	inverted internally to the "Astro::App::Satpass2"
       sense. This satpass compatibility will be retracted when	the satpass
       script is retired.

       Once the	"-am", "-day", and "-pm" options have their
       "Astro::App::Satpass2" sense, unspecified options are defaulted to
       false if	any of these options is	asserted, or true otherwise. For
       example,	specifying "-noam" has the same	effect as specifying "-day
       -pm", and specifying none of the	three options is the same as
       specifying "-am -day -pm".

   formatter
	$satpass2->formatter( date_format => '%d-%b-%Y'	);
	satpass2> formatter date_format	%d-%b-%Y

	say $satpass2->formatter( 'date_format'	);
	satpass2> formatter date_format

       This interactive	method takes as	its arguments the name of a method,
       and any arguments to be passed to that method. This method is called on
       the object which	is stored in the formatter attribute, and any results
       returned.  Normally it will be used to configure	the formatter object.
       See the documentation on	the formatter class in use for further
       details.

       When calling formatter methods via this method (as opposed to
       retrieving the formatter	method with "get( 'formatter' )" and then
       calling the methods directly on the formatter object) there are a
       couple cases in which the input is transformed:

       desired_equinox_dynamical
	   The argument, if any, is parsed using the time parser.

       format
	   The following arguments are passed to
	   Astro::App::Satpass2::Format::Template format():

	    sp	     =>	the invocant of	this method;
	    template =>	the first argument to this method;
	    arg	     =>	[ all arguments	after the first	].

	   An example may help:

	    my $output = $self->formatter( format => qw{ foo bar baz } )

	   is equivalent to

	    my $fmtr = $self->get( 'formatter' );
	    my $output = $fmtr->format(
		template => 'foo',
		arg	 => [ qw{ bar baz } ],
		sp	 => $self,
	    );

       This method takes the following options:

       -changes
	   This	option is only useful with the formatter's config() method. It
	   causes this method to return	only changes from the default. It can
	   be negated by prefixing "no".

	   The default is "-nochanges".

       -raw
	   This	option causes the method to return whatever the	underlying
	   method call returned. If negated (as	"-noraw"), the return is
	   formatted for text display.

	   The default is "-noraw" if called interactively, and	"-raw"
	   otherwise.

   geocode
	$output	= $satpass2->geocode('1600 Pennsylvania	Ave, Washington	DC');
	satpass2> geocode '1600	Pennsylvania Ave, Washington DC'

       This interactive	method looks up	its argument using the currently-set
       geocoder. It will fail if no geocoder is	set.

       If exactly one match is found, the location, latitude, and longitude
       attributes are set accordingly.

       If exactly one match is found and the autoheight	attribute is true, the
       height()	method will be called on the resultant position. This
       operation may fail if the location is outside the USA.

       The argument can	be defaulted, in which case the	current	location
       attribute is looked up.

       The results of the lookup are returned.

   geodetic
	$satpass2->geodetic( $name, $latitude, $longitude, $elevation );
	satpass2> geodetic name	latitude longitude elevation

       This interactive	method adds a geodetic position	to the observing list.
       The arguments are the name of the object, the latitude and longitude of
       the object (in degrees by default, see "SPECIFYING ANGLES" for
       details), and the height	of the object (in kilometers by	default, see
       "SPECIFYING DISTANCES" for details) above the current ellipsoid (WGS84
       by default). Nothing is returned.

       The motivation was to try to judge the observability of those Wallops
       Island cloud studies. The "pass"	method will not	report on these, but
       the "position" method will.

   get
	$value = $satpass2->get( $name );

       This non-interactive method returns the value of	the given attribute.
       See show() for the corresponding	interactive method.

   height
	$output	= $satpass2->height( $latitude,	$longitude );
	satpass2> height latitude longitude

       This interactive	method queries the USGS	online database	for the	height
       of the ground above sea level at	the given latitude and longitude. If
       these were not specified, they default to the current settings of the
       "latitude" and "longitude" attributes.

       If the query succeeds, this method returns the 'set' command necessary
       to set the height to the	retrieved value.

       This method will	fail if	the Geo::WebService::Elevation::USGS module
       can not be loaded.

   help
	$output	=  $satpass2->help(...)
	satpass2> help

       This interactive	method can be used to get usage	help. Without
       arguments, it displays the documentation	for this class (hint: you are
       reading this now). You can get documentation for	other Perl modules by
       specifying their	names. For convenience,	there are abbreviations	for
       some modules, as	follows:

	eci -------- Astro::Coord::ECI
	iridium	---- Astro::Coord::ECI::TLE::Iridium
	moon ------- Astro::Coord::ECI::Moon
	sun -------- Astro::Coord::ECI::Sun
	spacetrack - Astro::SpaceTrack
	star ------- Astro::Coord::ECI::Star
	tle -------- Astro::Coord::ECI::TLE
	utils ------ Astro::Coord::ECI::Utils

       The "iridium" help is available only if Astro::Coord::ECI::TLE::Iridium
       can be loaded.

       The viewer is whatever is the default for your system.

       Under Mac OS 9 or below,	this method simply returns an apology, since
       Pod::Usage appears not to work there.

       If you set the webcmd attribute properly, this method will launch a web
       browser displaying the desired documentation from
       <https://metacpan.org>.

       In any case, nothing is returned.

   if
	$output	= $satpass2->if(
	    qw{	env FUBAR then echo FUBAR is defined } );
	satpass2> if env FUBAR then echo FUBAR is defined
	satpass2> if "$FUBAR" then echo	FUBAR is defined

       This interactive	method performs	a test,	and executes the specified
       method if the test is true. The test is an infix	expression, with
       prefix operators	binding	more tightly than infix	operators, but
       otherwise all operators having the same precedence. You can use
       parentheses to group operations.	Anything that is not an	operator is
       assumed to be a value.  Values coming from substitution may need	to be
       quoted to guard against embedded	white space.

       The method name after 'then' may	not be 'else' or 'end'.

       The method name after 'then' may	be 'begin' only	if "if()" was called
       interactively. If you do	this and the "if()" is not satisfied, nothing
       called interactively will be executed until after the corresponding
       interactive call	to end() (or whenever the frame	created	by the
       "begin()" is popped off the stack, which	may be the end of a macro or
       source file.) Non-interactive methods will still	be executed. See
       METHODS above for what it means to be called interactively.

       For example (assuming OID 99999 is not loaded)

	$satpass2->dispatch( qw{ if loaded 99999 then begin } );

	# The following	will do	nothing	because	the above if()
	# was not satisfied.
	$satpass2->dispatch( qw{ echo hello there } );

	# The following	will be	executed even though the if()
	# was not satisfied, because it	is not being routed
	# through dispatch()
	$satpass2->spacetrack( retrieve	=> 25544 );

	# The following	ends the scope of the if()
	$satpass2->execute( qw{	end } );

	# The following	will be	executed because we are	no longer
	# in the scope of the unsatisfied if().
	$satpass2->execute( qw{	echo we	are back } );

       The following operators and functions are implemented:

       ( ... )
	   Parentheses perform grouping	of their contents, to force precedence
	   on the operations.

       -n  This	prefix operator	is true	if its operand is not the null string.

       -z  This	prefix operator	is true	if its operand is the null string.

       and This	infix operator computes	the Boolean "and" of its operands.
	   This	operator shortcuts; if the first operand is false the second
	   operand is not evaluated.

       attr
	   This	prefix operator	computes the value of the attribute specified
	   by its operand. If the operand is 'formatter', 'spacetrack' or
	   'time_parser', you can follow the attribute name by a dot and the
	   name	of an attribute	of the specified object, for example
	   'spacetrack.username'.

	   An attempt to access	a non-existent attribute will result in	an
	   exception.

	   Note	that Astro::SpaceTrack is an optional module. If it is not
	   installed we	can not	determine which	attributes are valid, so the
	   results of trying to	access any spacetrack attribute	result in an
	   exception. If you wish to share the same configuration among
	   installations that may or may not have Astro::SpaceTrack installed,
	   you can guard against the exception by using	something like

	    if attr spacetrack and attr	spacetrack.username ...

       env This	prefix operator	computes the value of the environment variable
	   named as its	operand.

       loaded
	   This	prefix operator	computes the number of loaded bodies chosen by
	   its operand,	which can be a comma-delimited list of values like
	   those taken by the "choose()|/choose" method.

       not This	prefix operator	computes the Boolean negation of its operand.

       or  This	infix operator computes	the Boolean "or" of its	operands. This
	   operator shortcuts; if the first operand is true the	second operand
	   is not evaluated.

       os  This	prefix operator	is true	if and only if the Perl	script is
	   running under the operating system named in its operand, as
	   determined by a case-insensitive match against $^O.

	   You can specify multiple operating systems by separating the	names
	   with	the pipe character ('|'). If you do this the operator is true
	   if $^O matches any one of the names.	If using this interactively,
	   you will need to quote the operand or escape	the pipes to hide them
	   from	the command line tokenizer. For	example:

	    satpass2> if os 'mswin32|dos|os2' then echo	DOS-ish

       then
	   This	infix operator causes everything to the	right of it to be
	   executed if the left	operand	was true. The first token to the right
	   must	be the name of a method.

       This was	actually implemented just so I could share the configuration
       file between operating systems. The problem I was addressing was	that
       the pinentry program in the MacPorts version of GnuPG does not seem to
       work nicely when	you log	in over	ssh. With the above functionality, my
       configuration file could	contain	the lines

	if not ( os darwin and env SSH_CONNECTION ) then \
	    spacetrack set identity 1
	if not attr spacetrack.username	then \
	    echo You will need to set your spacetrack identity manually.

   init
	$output	= $satpass2->init();

       This non-interactive method computes the	name of	the initialization
       file, and executes it if	it is present. The output (if any) is the
       output of the individual	commands executed by the initialization	file.

       If you pass a defined value as an argument, that	value will be taken as
       a file name, and	that file will be executed if possible.	 That is, this
       method's	functionality becomes the same as source(), but	without	the
       possibility of passing the '-optional' option. It is an error if	a file
       name is specified and that file does not	exist.

       If you do not pass a defined value as an	argument, the following	files
       are checked for,	and the	first one found	is executed:

	- The file specified by	the SATPASS2INI	environment variable;
	- The file returned by the initfile interactive	method;
	- The file specified by	the SATPASSINI environment variable;
	- The file used	by the satpass script.

       If none of these	is found, this method returns nothing.

       If the initialization file is for satpass rather	than
       "Astro::App::Satpass2", any commands issued in it will be interpreted
       in their	satpass	meaning, to the	extent possible. Also, an attempt will
       be made to rewrite the commands in any macros defined into their
       "Astro::App::Satpass2" equivalents. This	rewriting is a purely textual
       operation, and you may want to verify your macro	definitions.

       As a side effect, the name of the file actually used is stored in the
       "initfile attribute". This is cleared if	the initialization file	was
       not found.

       This method uses	a generic input	mechanism, and can initialize from a
       number of sources. See "SPECIFYING INPUT	DATA" for the details.

   initfile
	$output	= $satpass2->initfile();
	satpass2> initfile

       This interactive	method simply returns the name of the default
       initialization file, which is heavily OS-specific. This method is
       actually	used to	find the default initialization	file, but it is
       exposed to give an easy way for the user	to figure out where this code
       expects to find the initialization file.	See also the init() method for
       other places initialization files may be	found, and the "initfile
       attribute", which records the name of the actual	file loaded by the
       last call to init(),

       The initialization file is always named satpass2rc. It is located in
       the directory specified by

	File::HomeDir->my_dist_config( 'Astro-App-Satpass2' )

       Unfortunately, this method returns "undef" unless the directory
       actually	exists,	and is sketchily documented. As	of this	writing,
       though (February	2011), the Astro-App-Satpass2/ directory will be found
       in directory Perl/ in your documents directory, or in directory
       ".perl/"	if File::HomeDir thinks	your documents directory is your home
       directory. The exception	is on FreeDesktop.org systems (e.g. Linux),
       where the Perl/ directory is found by default in	".config/" under your
       home directory.

       Note that under macOS 10.15 Catalina this directory is not accessible
       by a "launchd" job, even	running	as the owner of	the directory. In
       order to	work around this, an alternate location	under macOS is
       "File::HomeDir->my_dist_data( 'Astro-App-Satpass2' )", which will
       probably	be ~/Library/Application
       Support/Perl/dist/Astro-App-Satpass2/.  See my_dist_config() in
       Astro::App::Satpass2::Utils for the gory	details.

       There are two options to	this method:

       * "-create-directory" causes the	directory for the initialization file
       to be created;

       * "-quiet" suppresses the exception which is normally thrown if the
       directory for the initialization	file is	not found, and
       "-create-directory" was not asserted, and instead causes	the method to
       simply return.

   list
	$output	= $satpass2->list(...);
	satpass2> list

       This interactive	method returns a listing of all	bodies in the
       observing list. If the observing	list is	empty and the "warn_on_empty"
       attribute is true, a warning is issued.

       The "-choose" option may	be used	to select which	bodies are listed.
       This selects bodies to list just	like the choose() method, but the
       observing list is unaffected. To	choose multiple	bodies,	either specify
       the option multiple times, separate the choices with commas, or both.

       If the "-choose"	option is not present but arguments are	given, they
       are made	into a "-choose" specification.	Thus,

	satpass2> list hst

       is equivalent to

	satpass2> list -choose hst

       but

	satpass2> list -choose hst iss

       will only list 'hst'.

   load
	$satpass2->load( $filename, ...	);
	satpass2> load filename

       This interactive	method does glob and bracket expansion on its
       arguments (which	have already been tilde-expanded by the	tokenizer) by
       running them through File::Glob::bsd_glob(). The	resultant files	are
       assumed to contain orbital elements which are loaded into the observing
       list. An	exception is thrown if no files	remain after the glob
       operation, or if	any file can not be opened.

       The "-verbose" option causes each file name to be listed	to "STDERR"
       before the file is processed.

       Nothing is returned.

       This method uses	a generic input	mechanism, and can load	data from a
       number of sources. See "SPECIFYING INPUT	DATA" for the details.

   localize
	$satpass2->localize( qw{ formatter horizon } );
	satpass2> localize formatter horizon

	$satpass2->localize( { all => 1	} );
	satpass2> localize -all

	$satpass2->localize( { except => 1 }, qw{ formatter horizon } );
	satpass2> localize -except formatter horizon

       This interactive	method localizes the values of the attributes given in
       the argument list to the	current	macro, source file, or begin block.
       Nested macros or	source files will see the changes, but commands
       outside the scope of the	localization will not. The arguments must be
       the names of valid attributes. Attempts to localize a value more	than
       once in the same	scope will be ignored. Nothing is returned.

       The "-except" option causes the argument	list to	be used	as an
       exception list, and all attributes except those in the argument list
       are localized. You can use "-all" as a synonym for "-except"; it	may
       look more natural when there are	no arguments.

   location
	$output	= $satpass2->location();
	satpass2> location

       This interactive	method returns the current location.

   macro
	$output	= $satpass2->macro( $subcommand, $arg ...);
	satpass2> macro	subcommand arg ...

       This interactive	method manipulates macros. The following subcommands
       are available:

	'brief'	lists the names	of defined macros;
	'list' lists the definitions of	macros;
	'delete' deletes macros;
	'define' defines a command macro;
	'load' loads a code macro.

       For semi-compatibility backward,	each of	these except 'load' can	be
       specified with a	leading	dash (e.g. '-delete'). With the	leading	dash
       specified, subcommands can be abbreviated as long as the	abbreviation
       is unique.  For example,	'-del' is equivalent to	'delete', but 'del' is
       not. This compatibility functionality will go away when support for
       compatibility with the satpass script does.

       If no arguments at all are provided to "macro()", 'brief' is assumed.

       If a single argument is provided	that does not match a subcommand name,
       'list' is assumed.

       If more than one	argument is provided, and the first does not match a
       subcommand name,	'define' is assumed.

       The first argument of the 'define' subcommand is	the macro name,	and
       subsequent arguments are	the commands that make up that macro. For
       example,	'say' can be defined in	terms of 'echo'	by

	$satpass2->macro( define => say	=> 'echo $@' );

       The 'define'> subcommand	supports the following options:

       -completion
	   This	option specifies a space-delimited list	of completions for the
	   macro arguments. It can be specified	more than once,	in which case
	   all completion specifications will be concatenated.

       The first argument of the 'load'	subcommand is the name of a Perl
       module (e.g. "My::Macros") that implements one or more code macros.
       Subsequent arguments, if	any, are the names of macros to	load from the
       module. If no subsequent	arguments are given, all macros	defined	by the
       macro are loaded.

       The 'load' subcommand supports the following options:

       -lib
	    -lib ~/lib

	   This	option specifies a directory from which	to load	macro modules.
	   The value is	added to @INC before the code macro is loaded.

	   The default is the lib/ subdirectory	of the user's configuration
	   directory.

       -verbose
	   This	option specifies that extra output be generated	if the load is
	   successful. This output will	appear before any output from the
	   "after_load"	macro if any.

	   This	option is intended as a	debugging aid, and the output
	   generated by	it may change without notice.

       Code macros are experimental. See Astro::App::Satpass2::TUTORIAL	for
       how to write one.

       For subcommands other than 'define' and 'load', the arguments are macro
       names.

       The "brief" and "list" subcommands return their documented output. The
       "delete"	and "define" subcommands return	nothing.

       Macros can be called programmatically via the dispatch()	method.

   magnitude_table
	$output	= $satpass2->magnitude_table( $subcommand, ... );
	satpass2> magnitude_table subcommand ...

       This interactive	method manipulates the satellite magnitude table. This
       provides	intrinsic magnitudes for satellites loaded via the load()
       method. The arguments are a subcommand (defaulting to 'show'), and
       possibly	further	arguments that depend on that subcommand.  Briefly,
       the valid subcommands are:

       "add" - adds a body's magnitude to the table, possibly replacing	an
       existing	entry. The arguments are OID and intrinsic magnitude, the
       latter defined as the magnitude at range	1000 kilometers	when half
       illuminated.

       "adjust"	- If an	argument is given, provides an adjustment to the
       magnitude table data when loading TLE data. This	adjustment, in
       magnitudes, is added to whatever	value is in the	table. If no argument
       is given, returns the current adjustment.

       "clear" - clears	the magnitude table.

       "drop" -	drops an entry from the	magnitude table. The argument is the
       OID.

       "list" -	a synonym for "show".

       "magnitude" - Load the magnitude	table from a hash (not available
       interactively). The loaded data replace whatever	was there before.

       "molczan" - Load	the magnitude table from a Molczan-format data file.
       The loaded data replace whatever	was there before.

       "molczan" - Load	the magnitude table from a Quicksat-format data	file.
       The loaded data replace whatever	was there before.

       "show" -	displays the magnitude table, formatted	as a series of
       'magnitude_table	add' commands.

       This method is really just a front-end for the Astro::Coord::ECI::TLE
       "magnitude_table()" method. See the documentation for that for more
       details.

   pass
	$output	= $satpass2->pass( 'today 12:00:00', '+7' );
	satpass2> pass 'today 12:00:00'	+7

       This interactive	method computes	and returns the	visible	passes of any
       bodies in the observing list. The optional arguments are	the start time
       of the prediction (defaulting to	the current day	at noon) and the end
       time of the prediction (defaulting to '+7'). See	"SPECIFYING TIMES" for
       how to specify times.

       The following options are available:

       "-am" selects morning passes (i.e. between midnight and noon).

       "-appulse" selects appulses for display.	It can be negated by
       specifying "-noappulse",	though a more efficient	way to not get
       appulses	is to clear the	sky.

       "-brightest" specifies (rather than selecting) that the moment the
       satellite is brightest should be	calculated. If specified, this
       modifies	the corresponding pass_variant bit for the duration of the
       call. If	not specified, it defaults to the value	of the corresponding
       "pass_variant" bit. Formatters may display magnitude if the
       corresponding "pass_variant" bit	is set,	but need not do	so.

       "-choose" chooses bodies	from the observing list	to report on. Multiple
       bodies can be chosen either by providing	a comma-delimited list as an
       argument, specifying "-choose" multiple times, or both. The choice is
       made in the same	way as by the choose() method, but the observing list
       is not affected.

       "-chronological"	causes the output to be	in chronological order by
       pass. If	this option is not asserted (or	is explicitly negated using
       "-nochronological") the order is	by satellite, though it	remains
       chronological for a particular satellite.

       "-dump" is a debugging tool. It is unsupported in the sense that	the
       author reserves the right to change or revoke its functionality without
       notice.

       "-events" causes	the output to be individual events rather than passes.
       These events will be displayed in chronological order irrespective of
       satellite. This is implemented by template "pass_events". The
       "-chronological"	option is not needed for this.

       "-horizon" selects the satellite	rise and set for display. Synonyms are
       "-rise" and "-set" -- that is "-rise" selects both rise and set,	as
       does "-set". This can be	negated	by specifying "-nohorizon", "-norise",
       or "-noset".

       "-ics" causes the output	to be in iCal format, as implemented by
       template	"pass_ics".

       "-illumination" selects passage of the satellite	into or	out of the
       Earth's shadow for display. This	can be negated by specifying
       "-noillumination".

       "-magnitude" is a synonym for "-brightest". See the documentation to
       that option (above) for more information.

       "-pm" selects evening passes (i.e. between noon and midnight).

       "-quiet"	suppresses any errors generated	by running the orbital model.
       These are typically from	obsolete data, and/or decayed satellites.
       Bodies that produce errors will not be included in the output.

       "-transit" selects the satellite	transit	across the meridian for
       display.	Synonyms are "-maximum"	and "-culmination". These can be
       negated by specifying "-notransit", "-nomaximum", or "-noculmination".

       The "-appulse", "-horizon", "-illumination" and "-transit" options (and
       their synonyms) specify what output to produce. If none are specified,
       all are turned on by default. If	only negated options are specified
       (e.g. -noappulse), unspecified options are asserted by default.
       Otherwise, unspecified options are considered to	be negated.

       The "-am" and "-pm" select morning or evening passes for	output.	By
       default,	both are selected. These can be	negated: "-noam" is equivalent
       to "-pm", and vice versa.

       Actually, the presence of any template whose name begins	with 'pass_'
       causes the trailing part	of the name to be valid	as an option selecting
       that template. For example, loading eg/pass_json.tt as template
       'pass_json' makes "-json" a valid option	that uses template 'pass_json'
       to format the TLE.

       Note well that unlike the satpass script, the output from this method
       does not	normally include location. The location	is included only if
       the command is issued from a satpass initialization file	(as opposed to
       an "Astro::App::Satpass2" initialization	file, or from a	macro defined
       in a satpass initialization file. This functionality will be revoked
       when support for	the satpass script is dropped.

   perl
	$output	= $satpass2->perl( $perl_file );
	satpass2> perl perl_file

       This interactive	method runs the	given Perl file	using the "do" built-
       in. The file is entered with $ARGV[0] set to a reference	to the
       invocant, and subsequent	@ARGV entries set to the arguments, if any.
       The return is the result	of the last statement in the file unless the
       file returns an instance	of "Astro::App::Satpass2", in which case
       nothing is returned.

       If you provide the option "-eval", the argument is passed to the	"eval"
       built-in	instead.

       If you provide the option "-setup", you are identifying the Perl	as
       containing set-up code. This does not cause the method to function any
       differently, but	it does	cause it to record the arguments so that the
       save() method will emit the invocation into a setup file. Both the file
       name and	the arguments will be preserved	without	tilde expansion.

   phase
	$output	= $satpass2->phase();
	satpass2> phase

       This interactive	method computes	and returns the	phase of any bodies in
       the sky which support this. The optional	argument is the	time of	the
       prediction (defaulting to the current time). See	"SPECIFYING TIMES" for
       how to specify times.

   position
	$output	= $satpass2->position(...);
	satpass2> position ...

       This interactive	method computes	and returns the	positions of all
       bodies in the observing list and	in the sky. For	bodies on the
       observing list that can flare, flare status is displayed	for all
       sources of flares on the	body.

       There is	one argument, which is the time	for the	computation, which
       defaults	to the current time.

       The following options may be specified:

       "-choose=choice"	selects	bodies to display. This	can be specified
       multiple	times to select	multiple bodies, or the	"choice" argument can
       be a comma-separated list of things to choose, or both. The choices are
       implemented in exactly the same way as for the choose() method, but the
       observing list is not affected, and the choice is applied to objects in
       the sky as well.

       "-questionable" causes flare data to be provided	on bodies whose
       ability to produce predictable flares is	questionable.

       "-quiet"	suppresses any errors generated	by running the orbital model.
       These are typically from	obsolete data, and/or decayed satellites.
       Bodies that produce errors will not be included in the output.

       "-spare"	is a synonym for "-questionable".

       The "endtime" and "interval" arguments and the "-realtime" option,
       which were present in the original satpass script, have been retracted.
       If you need any of these, please	contact	the author.

   pwd
	$output	= $satpass2->pwd();
	satpass2> pwd

       This interactive	method simply returns the name of the current working
       directory, terminated with a "\n".

   quarters
	$output	= $satpass2->quarters($start_time, $end_time, ...);
	satpass2> quarters start_time end_time ...

       This interactive	method computes	and returns the	quarters for any
       objects in the sky that have this functionality.

       It takes	up to two arguments, which are the start and end time covered.
       The start time defaults to midnight of the current day in the local
       time zone, or GMT if the	"gmt" attribute	is true. The end time defaults
       to 30 days after	the start time.	See "SPECIFYING	TIMES" for how to
       specify times.

       The following options are available:

       -choose
	    -choose moon

	   This	option selects the body	whose quarters are to be computed. It
	   can be specified multiple times to select multiple bodies. If
	   omitted, all	bodies in the sky are selected.	Note that in any event
	   bodies that do not support the "next_quarter_hash()"	method are
	   skipped.

       -dump
	   This	option produces	debugging output. It should be considered a
	   troubleshooting tool, which may change or disappear without notice.

       -q0, or -new, or	-spring
	   This	option causes the time of the zeroth quarter to	be displayed.
	   The synonyms	are appropriate	to the Moon and	Sun respectively. See
	   below for how this is defaulted.

       -q1, or -first, or -summer
	   This	option causes the time of the first quarter to be displayed.
	   The synonyms	are appropriate	to the Moon and	Sun respectively. See
	   below for how this is defaulted.

       -q2, or -full, or -fall
	   This	option causes the time of the second quarter to	be displayed.
	   The synonyms	are appropriate	to the Moon and	Sun respectively. See
	   below for how this is defaulted.

       -q3, or -last, or -winter
	   This	option causes the time of the third quarter to be displayed.
	   The synonyms	are appropriate	to the Moon and	Sun respectively. See
	   below for how this is defaulted.

       The "-q0", "-q1", "-q2",	and "-q3" options (and their synonyms) are
       defaulted as a group. If	none of	the group is specified,	all are
       asserted	by default. If none is asserted	but at least one is negated
       (e.g. "-nonew"),	all unspecified	members	of the group are asserted by
       default.	If at least one	member of the group is asserted, all
       unspecified members are negated by default.

   run
	Astro::App::Satpass2->run(...);

       This non-interactive method runs	the application. The arguments are the
       options and commands to be passed to the	application.

       The valid options are:

	-echo to turn on command echoing;
	-filter	to suppress banner text;
	-gmt to	output time in GMT;
	-initfile name of the initialization file to use;
	-version to display the	output of version() and	return.

       The -filter option defaults to true if STDIN is not a terminal.

       The steps in running the	application are:

       1) If the first argument	is a code reference, it	is pulled off the
       argument	list and used for input. Otherwise default input code is
       generated as described later.

       2) The arguments	are parsed as though they are a	command	line.

       3) If the input is from a terminal and the -filter option was not
       specified, a banner is printed.

       4) The initialization file is located and run. If you specified an
       initialization file via the "-initfile" option, you will	be warned if
       it was not found. If the	initialization file contains the "exit"
       command,	it will	be executed, and the run will end at this step.

       5) Any remaining	options	corresponding to attribute values (currently
       only "-gmt") are	applied.

       6) Any remaining	arguments after	removing all options are assumed to be
       commands, and passed to the execute() method. If	one of these is	the
       "exit" command, the run will end	at this	step.

       7) Further commands are read as described below.

       By default, commands come from "STDIN", but any commands	passed as
       arguments are executed first. How commands are read from	"STDIN"
       depends on a number of factors. If "STDIN" is a terminal	and
       Term::ReadLine can be loaded, a Term::ReadLine object is	instantiated
       and used	to read	input.	If "STDIN" is a	terminal and Term::ReadLine
       can not be loaded, the prompt is	printed	to "STDERR" and	"STDIN"	is
       read.  If "STDIN" is not	a terminal, it is read.

       If Term::ReadLine is in use and can load	"Term::ReadLine::Perl",
       command editing,	history, and completion	are available. Completion will
       include at least	command, macro,	and option names, in addition to the
       file name completion built into "Term::ReadLine::Perl".

       The default command acquisition behavior	can be changed by passing, as
       the first argument, a code reference. This should refer to a subroutine
       that expects the	prompt as its only argument, and returns the next
       input. This code	should return "undef" to indicate a logical end-of-
       file.

       The exit	command	causes the method to return.

       This method can also be called on an Astro::App::Satpass2 object. For
       example:

	use Astro::App::Satpass2;
	my $app	= Astro::App::Satpass2->new(
	    prompt => 'Your wish is my command:	'
	);
	$app->run();

   save
	$satpass2->save( $file_name );
	satpass2> save file_name

       This interactive	method saves your current settings to the named	file.
       If no file is named, they are saved to the default configuration	file.
       If the file already exists, you will be prompted	unless you specified
       the "-overwrite"	option.	Nothing	is returned.

       File name - is special, and causes output to go wherever	standard
       output is being sent.

       This method saves all attribute values of the "Astro::App::Satpass2"
       object, all attributes of the Astro::SpaceTrack object being used to
       retrieve	TLE data, and all defined macros. If you overwrite a
       configuration file, any other contents of the file will be lost.

       The following options are allowed:

       "-changes" causes only changes from the default attributes to be
       written to the output file.

       "-overwrite" causes the output file to overwrite	an existing file of
       the same	name (if any) without getting confirmation from	the user.

   set
	$satpass2->set($name =>	$value ...);
	satpass2> set name value ...

       This interactive	method sets the	values of the given attributes.	More
       than one	attribute can be set at	a time.	 Nothing is returned.

       When this method	is being executed interactively	(i.e. via the
       "dispatch" method, as opposed to	being called directly as a method),
       certain attributes may not be set. Also,	the literal 'undef' is taken
       to represent the	undefined value.

   show
	$output	= $satpass2->show( $name, ... );
	satpass2> show name ...

       This interactive	method returns the values of the given attributes,
       formatted as 'set' commands. If no arguments are	given, the values of
       all non-deprecated attributes that may be set interactively are
       returned.

       If you specify the "-changes" option, only those	values that have been
       changed from the	default	are returned.

   sky
	$output	= $satpass2->sky( $subcommand ...);
	satpass2> sky subcommand ...

       This interactive	method manipulates the background objects. The
       $subcommand argument determines what manipulation is done, and the
       interpretation of subsequent arguments depends on this. The
       interpretation of the subcommand	names is not case-sensitive. If	no
       subcommand is given, 'list' is assumed.

       The possible subcommands	are:

       add

       This subcommand adds an object to the background. The first argument is
       the name	of the object. If the case-insensitive name of the object
       appears in the sky class	list (see below) it is instantiated and	added.
       Otherwise the name is assumed to	be the name of a star, and its
       coordinates must	be given, in the following order: right	ascension (in
       either degrees or hours,	minutes, and seconds), declination (in
       degrees), range (optionally with	units of meters	('m'), kilometers
       ('km'), astronomical units ('au'), light	years ('ly'), or parsecs
       ('pc', the default) appended), proper motion in right ascension and
       declination (in degrees per year) and in	recession (in kilometers per
       second).	All but	right ascension	and declination	may be omitted.	It is
       an error	to attempt to add an object which is already listed among the
       background objects. Nothing is returned.

       class

       This subcommand maintains the classes of	background objects. It takes
       the following subcommand-specific options:

       -add
	   If this Boolean option is asserted, the object is added to the sky
	   once	it is successfully defined.

	   You may not specify both "-add" and "-delete" on the	same command.

       -delete
	   If this Boolean option is asserted, the arguments are the case-
	   insensitive names of	class definitions to remove. The definition
	   for the Sun can not be removed, and any class actually instantiated
	   in the sky can not be removed. Nothing is returned.

	   You may not specify both "-add" and "-delete" on the	same command.

       Options can be specified	either command-line style (with	leading	dashes
       or double dashes, as documented above) or as an optional	hash reference
       appearing immediately after the subcommand name.	In the latter case
       option names must be specified in full.

       Unless the "-delete" option is specified	(see above), the arguments are
       the case-preserved name of the object being defined, the	name of	the
       class that implements it, and optional attribute	values (specified as
       name/value pairs). You may not specify the "name" attribute, because
       this is derived from the	first argument.	This information is added to
       the known object	definitions, replacing the previous definition if any.
       Nothing is returned.

       If only a name is specified, the	definition of that name	is returned,
       formatted as a 'sky class' command. If no arguments at all are
       specified, all defined classes are returned.

       clear

       This subcommand clears all background objects. It takes no arguments.
       Nothing is returned.

       drop

       This subcommand removes background objects. The arguments are the names
       of the background objects to be removed,	or portions thereof. They are
       made into a case-insensitive regular expression to perform the removal.
       Nothing is returned.

       list

       This subcommand returns a string	containing a list of the background
       objects,	in the format of the 'sky add' commands	needed to re-create
       them. If	no subcommand at all is	given, 'list' is assumed.

       lookup

       This subcommand takes as	its argument a name, looks that	name up	in the
       University of Strasbourg's SIMBAD database, and adds the	object to the
       background. An error occurs if the object can not be found. This
       subcommand will fail if the Astro::SIMBAD::Client module	can not	be
       loaded.	Nothing	is returned.

   source
	$output	= $satpass2->source( $file_name	);
	satpass2> source file_name

       This interactive	method takes commands from the given file and runs
       them. The concatenated output is	returned.

       Normally	an exception is	thrown if the file can not be opened. If the
       "-optional" option is specified,	open failures cause the	method to
       return "undef".

       This method uses	a generic input	mechanism, and can load	files from a
       number of sources. See "SPECIFYING INPUT	DATA" for the details.

   spacetrack
	$satpass2->spacetrack( set => username => 'yehudi' );
	satpass2> spacetrack set username yehudi

	say $satpass2->spacetrack( get => 'username' );
	satpass2> spacetrack get username

       This interactive	method takes as	its arguments the name of a method,
       and any arguments to be passed to that method. This method is called on
       the object which	is stored in the spacetrack attribute, and any results
       returned.  Normally it will be used to configure	the spacetrack object.
       See the Astro::SpaceTrack documentation for further details.

       If the Astro::SpaceTrack	method returns orbital elements, those
       elements	are added to "Astro::App::Satpass2"'s internal list.

       Similarly, if the Astro::SpaceTrack method returns Iridium status
       information, this will replace the built-in status.

       In addition to the actual Astro::SpaceTrack methods, this method
       emulates	methods	which it would be useful (to "Astro::App::Satpass2"
       for Astro::SpaceTrack to	have. These are:

       show
	   This	can be used to display multiple	Astro::SpaceTrack attributes.
	   If no attribute names are provided, all attributes are displayed.
	   If "-changes" is specified, only changed attributes are displayed.

       config
	   This	is really just an alias	for "show", provided for consistency
	   with	the formatter and time parser objects.

       This method takes the following options:

       -changes
	   This	option is only useful with the "config"	and "show" emulated
	   methods, as discussed above.	It causes these	to return only changes
	   from	the default. It	can be negated by prefixing "no".

	   The default is "-nochanges".

       -raw
	   This	option causes the method to return whatever the	underlying
	   method call returned. Where the underlying method returns an
	   HTTP::Response object, the content of that object is	returned. If
	   negated (as "-noraw"), the return is	formatted for text display.

	   The default is "-noraw" if called interactively, and	"-raw"
	   otherwise.

   st
	$output	= $satpass2->st( $method ...);
	satpass2> st method ...

       This interactive	method is deprecated in	favor of the spacetrack()
       method. If you don't like all the typing	that implies in	interactive
       mode, you can define 'st' as a macro:

	satpass2> macro	define st 'spacetrack "$@"'

       This interactive	method calls Astro::SpaceTrack (which must be
       installed) to load satellite data. The arguments	are the
       Astro::SpaceTrack method	name and any arguments to that method. As
       special cases, 'show' is	made equivalent	to 'get', 'get'	will display
       all attribute values if called without a	value, and 'localize' will
       localize	attribute values to a block. The return	is whatever the	method
       returns.

       The following options are allowed on any	retrieval:

	-descending specifies the return of data in descending order;
	-last5 specifies the return of the last	5 elements;
	-end specifies the end time for	the data to be fetched;
	-start specifies the start time	for the	data to	be fetched;
	-sort specifies	the type of sort to do on the data;
	-verbose gets output for normally-silent functions.

       All options except for -verbose are specific to Astro::SpaceTrack, and
       are silently ignored unless relevant to the method being	called.

       The following options are allowed on the	'get' or 'show'	commands:

	-changes reports only changes from the defaults	used by	Astro::App::Satpass2.

       This method will	fail if	the Astro::SpaceTrack module can not be
       loaded.

   status
	$output	= $satpass2->status( $subcommand, ... );
	satpass2> status subcommand ...

       This interactive	method manipulates the satellite status	cache. This
       currently only covers Iridium satellites. The arguments are a
       subcommand (defaulting to 'show'), and possibly further arguments that
       depend on that subcommand.  Briefly, the	valid subcommands are:

       "add" - adds a body to the status table,	possibly replacing an existing
       entry. The arguments are	OID, type, status, name, and comment. The type
       would typically be 'iridium', and status	typically '+' (operational),
       'S' (spare), or '-' (failed). Name and comment default to empty.

       "clear" - clears	the status table. You can specify a type, and only
       that type would be cleared, but currently there is only one type.

       "drop" -	drops an entry from the	status table. The argument is the OID.

       "iridium" - dropped in favor of "show", to remain compatible with
       satpass version 0.050. An exception will	be thrown if this subcommand
       is used.

       "list" -	a synonym for "show".

       "show" -	displays the status table, formatted as	a series of 'status
       add' commands.

       There are two options:

       -name specifies that the	data for the "show" subcommand be displayed in
       order by	name. It is allowed but	ignored	on any other subcommand.

       This method is really just a front-end for the Astro::Coord::ECI::TLE
       "status()" method. See the documentation	for that for more details.

   station
	my $sta	= $satpass2->station();

       This non-interactive method manufactures	and returns an
       Astro::Coord::ECI object	representing the observer from the current
       values of the latitude, longitude and height attributes.	It throws an
       exception if any	of the relevant	attributes are not defined.

   system
	$output	= $satpass2->system(...);
	satpass2> system ...
	satpass2> !...

       This interactive	method does glob and bracket expansion on its
       arguments (which	have already been tilde-expanded by the	tokenizer) by
       running them through File::Glob::bsd_glob(), and	executes them as a
       command on the system. Since tokenizing is done by
       Astro::App::Satpass2, there is no shell processing, and the quoting
       rules are those of Astro::App::Satpass2,	not those of the underlying
       operating system.

       If the "stdout" attribute is a terminal,	output goes directly to	the
       terminal, thus making things like 'less'	possible. Otherwise output is
       captured	and returned.

   time
	$output	= $satpass2->time( $method ...);
	satpass2> time method ...

       This interactive	method times the given method. The arguments are the
       name of an interactive method and the arguments to that method. The
       return is whatever the called method returns. The timings are written
       to standard error.

       You can only time the begin() method if "time()"	is called
       interactively. If you do	this, the timing will include everything
       through the corresponding interactive call to end() (or whenever	the
       frame created by	the "begin()" is popped	off the	stack, which may be
       the end of a macro or source file.) See METHODS above fore what it
       means to	be called interactively.

       You can not time	the end() method.

       This method will	fail if	the Time::HiRes	module can not be loaded.

   time_parser
	$satpass2->time_parser(	zone =>	'MST7MDT' );
	satpass2> time_parser zone MST7MDT

	say $satpass2->time_parser( 'zone' );
	satpass2> time_parser zone

       This interactive	method takes as	its arguments the name of a method,
       and any arguments to be passed to that method. This method is called on
       the object which	is stored in the time_parser attribute,	and any
       results returned. Normally it will be used to configure the time	parser
       object. See the documentation on	the time parser	class in use for
       further details.

       This method takes the following options:

       -changes
	   This	option is only useful with the time_parser's config() method.
	   It causes this method to return only	changes	from the default. It
	   can be negated by prefixing "no".

	   The default is "-nochanges".

       -raw
	   This	option causes the method to return whatever the	underlying
	   method call returned. If negated (as	"-noraw"), the the return is
	   formatted for text display.

	   The default is "-noraw" if called interactively, and	"-raw"
	   otherwise.

   tle
	$output	= $satpass2->tle(...);
	satpass2> tle ...

       This interactive	method returns the actual TLE data for the observing
       list. If	any arguments are passed, they select the items	to be
       displayed, in the same way that "choose"	does, though in	this case the
       contents	of the observing list are unaffected.

       The following options are allowed:

	-choose	explicitly chooses the bodies to display. The
	    contents of	the observing list are unaffected, and
	    arguments are ignored.
	-verbose produces an expanded list, with data labeled.

       Actually, the presence of any template whose name begins	with 'tle_'
       causes the trailing part	of the name to be valid	as an option selecting
       that template. For example, loading eg/tle_json.tt as template
       'tle_json' makes	"-json"	a valid	option that uses template 'tle_json'
       to format the TLE.

       The template selector options can be negated by prefixing 'no' to the
       option name (e.g. "-noverbose").	Negating the option specifies template
       'tle', the default.

       If more than one	template selector option is specified, the rightmost
       one riles. For example, given template 'tle_json',

	satpass2> tle -verbose -json

       uses template 'tle_json'	to display the output.

   unexport
	$satpass2->unexport( $name, ...	);
	satpass2> unexport name	...

       This interactive	method undoes the effects of export().	Unlike that
       method, multiple	things can be unexported with a	single call. It	is not
       an error	to unexport something that was never exported.

   validate
	$satpass2->validate( $options, $start_time, $end_time );
	satpass2> validate [ options ] start_time end_time

       This interactive	method validates the current observing list in the
       given time range	by performing position calculations at relevant	times
       in the range.

       The only	valid option is

	-quiet - suppress output of validation failures.

       The start time defaults to noon of the current day; the end time
       defaults	to seven days after the	start time.

       This method really just wraps the "validate()" methods in either
       Astro::Coord::ECI::TLE, or Astro::Coord::ECI::TLE::Set, as appropriate.

   version
	$output	= $satpass2->version();
	satpass2> version

       This interactive	method simply returns "Astro::App::Satpass2" version
       information.

   wail
	$satpass2->wail( 'Something went wrong'	);

       This non-interactive method is simply a wrapper for our
       "Astro::App::Satpass2::Warner" object's "wail()"	method,	which
       corresponds more	or less	to "Carp::croak()".

   want_pass_variant
	$satpass2->want_pass_variant( 'brightest' );

       This convenience	method returns a true value if the given pass variant
       is in effect, and false otherwise. The argument must be exactly one of
       the valid variant names documented for the pass_variant attribute, and
       must not	be 'none'.

   weep
	$satpass2->weep( 'Something went very wrong' );

       This non-interactive method is simply a wrapper for our
       "Astro::App::Satpass2::Warner" object's "weep()"	method,	which
       corresponds more	or less	to "Carp::confess()".

   whinge
	$satpass2->whinge( 'Something went a little wrong' );

       This non-interactive method is simply a wrapper for our
       "Astro::App::Satpass2::Warner" object's "whinge()" method, which
       corresponds more	or less	to "Carp::carp()".

   __add_to_observing_list( @bodies );
       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method adds	the given bodies to the	observing list.	All must
       represent Astro::Coord::ECI::TLE	objects, or an exception will be
       thrown and none will be added to	the observing list.

   __choose
	$chosen	= $self->__choose( \%opt, \@choice, @list )
	@chosen	= $self->__choose( \%opt, \@choice, @list )

       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method filters the list of bodies provided in @list	according to
       the criteria in @choice (possibly modified by the options in %opt, and
       returns all matching bodies. If called in scalar	context, it returns a
       reference to an array containing	all matching bodies.

       Argument	"\%opt"	is optional, and defaults to an	empty hash. If
       present,	it specifies modifiers for the choice operation. The supported
       options are:

       invert
	   If specified	as a true value, it inverts the	sense of the match;
	   that	is, the	return is everything not selected by the "\@choice"
	   argument.

       bodies
	   If specified	as a true value, all currently-loaded orbiting bodies
	   (that is, all objects displayed by

	    satpass2> list

	   )will be aggregated and appended to the @list.

       sky If specified	as a true value, all currently-loaded background
	   objects (that is, objects displayed by

	    satpass2> sky list

	   ) will be appended to the @list.

       The "\@choice" argument specifies things	to choose from the @list.  It
       must be specified, but may be specified as "undef". If "\@choice" is
       "undef" or a reference to an empty array, the entire contents of	@list
       are returned. Otherwise all objects in @list that match any item	in
       @choice are returned -- unless "invert" is in effect, in	which case all
       objects in @list	that match no item in @choice are returned.

       The contents of @choice are interpreted as follows:

       strings
	   Strings are split on	commas,	and the	resultant pieces used as
	   though they were specified separately. Numbers greater than 999 are
	   assumed to be OIDs, and select objects having that value of the
	   'id'	attribute of each item in @list. Anything else is made into an
	   unanchored regular expression and matched to	the value of the
	   'name' attribute of each item in @list.

       Regexp objects
	   These are matched against the value of the 'name' attribute of each
	   item	in @list.

       The @list argument is actually optional,	though if it is	omitted
       nothing interesting happens unless the "bodies" or "sky"	options	(or
       both) are specified.

       The @list argument is expected to contain "Astro::Coord::ECI" objects
       (or, of course, "Astro::Coord::ECI::TLE::Set" objects), or references
       to arrays of such objects. Any array references are flattened into
       @list before processing.

   __format_data
	$text =	$satpass2->__format_data( $template, $data, $opt );

       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method expects a "Template-Toolkit"	$template name,	the $data to
       be formatted by the template, and an optional $opt hash reference. If
       the {dump} key in $opt is true, the $data are formatted using a dumper
       template, otherwise they	are formatted by the current Template object.
       The $data are the data used by the template, typically (though not
       necessarily) an array reference.

   __parse_angle
	$angle = $satpass2->__parse_angle( $string );

       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method parses the $string as an angle in degrees,
       hours:minutes:seconds of	right ascension, or degreesDminutesMsecondsS
       of arc, and returns the angle in	degrees. If $string is "undef",	we
       simply return. An exception is thrown if	the $string can	not be parsed.

       A reference to an options hash can be passed before the $string
       argument. The supported options are:

       accept
	   If this is true (in the perl	sense) anything	not parsed as an angle
	   is simply returned. In this case the	caller is responsible for
	   being sure the return is valid.

   __parse_distance
	$distance = $self->__parse_distance( $string, $default_units );

       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method parses the $string as a distance, applying the
       $default_units if no units are specified, and returns the distance in
       kilometers.

       The $string is presumed to be a magnitude and optional appended units.
       Supported units are:

	au - astronomical units
	ft - feet
	km - kilometers
	ly - light years
	m -- metars
	mi - miles
	pc - parsecs

       Specified units are converted to	lower case before use.

   __parse_time
	$time =	$satpass2->__parse_time( $string, $default );

       This method is exposed for the use of code macros, and is unsupported
       until such time as code macros themselves are.

       This method parses the $string as a time	and returns the	time. If
       $string is false	(in the	Perl sense) we return $default.

       If $string begins with a	'+' or '-', it is assumed to be	an offset in
       "days hours:minutes:seconds" from the last explicitly-specified time.
       Otherwise it is handed to "Date::Manip" for parsing. Invalid times
       result in an exception.

       Epoch times can be specified either by prefixing	'epoch ' or by passing
       a reference to the value.

ATTRIBUTES
       The Astro::App::Satpass2	object has a number of attributes to configure
       its operation. In general:

       Attributes that represent angles	are in degrees,	but may	be set in
       other representations (e.g. degrees, minutes, and seconds). See
       "SPECIFYING ANGLES" for more detail.

       Boolean (i.e. true/false) attributes are	set by convention to 1 for
       true, or	0 for false. The evaluation rules are those of Perl itself: 0,
       '', and the undefined value are false, and everything else is true.

       There are a few attributes whose	names duplicate	the names of methods.
       These will be identified	as attributes, for the sake of internal	links.
       For example, "appulse", but "height attribute".

       The attributes are:

   appulse
       This numeric attribute specifies	the maximum angle reportable by	the
       "pass" method between the orbiting body and any of the background
       objects.	If the body passes closer than this, the closest point will
       appear as an event in the pass. The intent is to	capture	transits or
       near approaches.

       If this attribute is set	to 0, no check for close approaches to
       background objects will be made.

       See "SPECIFYING ANGLES" for ways	to specify an angle. This attribute is
       returned	in decimal degrees.

       The initial setting is 0.

   autoheight
       This boolean attribute determines whether the "geocode" method attempts
       to acquire the height of	the location above sea level.  It does this
       only if the parameter is	true and the geocoding returns exactly one
       location. You may wish to turn this off (i.e. set it to 0) if the USGS
       elevation service is being balky.

       The default is 1	(i.e. true).

   backdate
       This boolean attribute determines whether the "pass" method will
       attempt to use orbital elements before their effective date. It is
       actually	simply propagated to the "backdate" attribute of the
       individual TLE objects, and so takes effect on a	per-object basis. If
       it is false, the	"pass" method will silently move the start of the pass
       prediction to the effective date	of the data if the specified pass
       start is	earlier	than the effective date	of the data.

       The default is 0	(i.e. false). This is different	from the old satpass
       script, which defaulted it to true.

   background
       This boolean attribute determines whether the location of the
       background body is displayed when the "appulse" logic detects an
       appulse.

       The default is 1	(i.e. true).

   continuation_prompt
       This string attribute specifies the string used to prompt for
       continuations of	lines.

       The default is '> '.

   country
       This attribute is ignored and deprecated.

       This string attribute determines	the default country for	the "geocode"
       and "height" methods. The intent	is that	it be an ISO 3166 two-
       character country code. At the moment it	does nothing useful since
       there is	currently only one source for "geocode"	and "height" data.

       See <https://www.iso.org/iso-3166-country-codes.html> for the current
       list of country codes. Note that	these are not always the same as the
       corresponding top-level geographic domain names (e.g. Great Britain is
       'GB' in ISO 3166	but for	historical reasons has both 'gb' and 'uk' as
       top-level geographic domain name).

       The country codes are case-insensitive, since they will be converted to
       lower case for use.

       The default is 'us'.

   date_format
       This string attribute is	deprecated. It is provided for backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object (if you set it yourself
       and retained a reference), or via the formatter() method, e.g.:

	$satpass2->get(	'formatter' )->date_format( '%d-%b-%Y' );
	satpass2> formatter date_format	'%d-%b-%Y'

       This attribute allows access to and manipulation	of the formatter
       object's	date_format attribute.	This is	normally used as a "strftime
       (3)" format to format a date. See the date_format documentation for the
       default.	See the	documentation of the actual formatter class being used
       for what	it does.

       This string attribute specifies the format used to display dates.
       Documentation of	the "strftime (3)" subroutine may be found at
       <https://linux.die.net/man/3/strftime> among other places.

       The above is a long URL,	and may	be split across	multiple lines.	More
       than that, the formatter	may have inserted a hyphen at the break, which
       needs to	be taken out to	make the URL good. Caveat user.

   debug
       This numeric attribute turns on debugging output. The only supported
       value is	0. The author makes no representation of what will happen if a
       non-zero	value is set, not does he promise that the behavior for	a
       given non-zero value will not change from release to release.

       The default is 0.

   desired_equinox_dynamical
       This string attribute is	deprecated. It is provided for backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object,	or via the formatter()
       method.

       This attribute allows access to and manipulation	of the formatter
       object's	desired_equinox_dynamical attribute. This is normally used to
       specify the desired equinox for inertial	coordinates. See the
       desired_equinox_dynamical documentation for the default.	See the
       documentation of	the actual formatter class being used for what it
       does.

       Note that while the wrapped attribute is	a number, this class treats it
       as a string. This results in a certain lack of orthogonality among the
       behaviors of the	"set", "get", and "show" methods.

       The "set" method	runs its input through the time	parser object's
       parse_time method. Since	that expects to	parse a	string of some sort,
       you can not (unfortunately) pass	in a Perl time.	See the
       Astro::App::Satpass2::ParseTime documentation for the details.

       The "get" method	simply returns a Perl time.

       The "show" method formats the value of the attribute in a way that can
       (hopefully!) be parsed by any of	the time parsers supplied with this
       package.

   echo	attribute
       This boolean attribute causes commands that did not come	from the
       keyboard	to be echoed. Set it to	a non-zero value to watch your scripts
       run, or to debug	your macros, since the echo takes place	after
       parameter substitution has occurred.

       The default is 0.

   edge_of_earths_shadow
       This numeric attribute specifies	the offset in elevation	of the edge of
       the Earth's shadow from the center of the illuminating body (typically
       the Sun)	as seen	from a body in space. The offset is in units of	the
       apparent	radius of the illuminating body, so that setting it to 1
       specifies the edge of the umbra,	"-1" specifies the edge	of the
       penumbra, and 0 specifies the middle of the penumbra. This attribute
       corresponds to the same-named Astro::Coord::ECI attribute.

       The default is 1	(i.e. edge of umbra).

   ellipsoid
       This string attribute specifies the name	of the reference ellipsoid to
       be used to model	the shape of the earth.	Any reference ellipsoid
       supported by see	Astro::Coord::ECI may be used.

       The default is 'WGS84'.

   error_out
       This boolean attribute specifies	the behavior on	encountering an	error.

       If this attribute is true, all macros, source files, etc	are aborted on
       an error, and control is	returned to the	caller,	or to the run()	method
       if that is where	we came	from. If standard in is	not a terminal,	we
       exit.

       If this attribute is false, errors are reported,	but otherwise ignored.

       The default is 0	(i.e. false).

   events
       This attribute records the cumulative number of events generated	by the
       most-recent invocation of almanac, flare, pass, or quarters. In the
       case of pass(), the number of events is the number of passes reported.

       This attribute was added	on the speculation that	it would be useful in
       an if().	 It can	be modified by the user	(to restart the	accumulation,
       for example), though except for testing the value in an if() such
       modifications have no effect on the operation of	this package.

   exact_event
       This boolean attribute specifies	whether	the "pass" method should
       compute visibility events (rise,	set, max, into or out of shadow,
       beginning or end	of twilight) to	the nearest second. If false, such
       events are reported to the step size specified when the "pass" method
       was called.

       The default is 1	(i.e. true).

   explicit_macro_delete
       This boolean attribute is ignored and deprecated. It exists because the
       satpass script required it to deal with a change	in the functionality
       of the "macro" command.

       The default is 1	(i.e. true).

   extinction
       This boolean attribute specifies	whether	magnitude estimates take
       atmospheric extinction into account. It should be set true if you are
       interested in measured brightness, and false if you are interested in
       estimating magnitudes versus nearby stars.

       The default is 1	(i.e. true).

   filter
       Setting this boolean attribute true suppresses the front	matter that is
       normally	output by the run() method if standard input is	a terminal. If
       standard	input is not a terminal, the front matter is not provided
       anyway.

       The default is undef (i.e. false).

   flare_mag_day
       This numeric attribute specifies	the limiting magnitude for the flare
       calculation for flares that occur during	the day. For this purpose, it
       is considered to	be day if the elevation	of the Sun is above the
       twilight	attribute.

       The default is -6.

   flare_mag_night
       This numeric attribute specifies	the limiting magnitude for the flare
       calculation for flares that occur during	the night. For this purpose,
       it is considered	to be night if the elevation of	the Sun	is below the
       twilight	attribute.

       The default is 0.

   formatter attribute
       This attribute specifies	the class to be	used to	format output. You can
       set it to either	the actual formatter object, or	to the name of the
       class to	use. In	the latter case, an object of the appropriate class
       will be instantiated, so	"get( 'formatter' )" always returns an object.
       A call to "show(	'formatter' )",	however, will always show the class
       name.

       When setting the	formatter to a class name, the leading
       'Astro::App::Satpass2::Format::'	may be omitted.

       Minimal constraints on the formatter class are imposed, but while it
       need not	be a subclass of Astro::App::Satpass2::Format, it must conform
       to that class' interface.

       The default is Astro::App::Satpass2::Format::Template.

   geocoder
       This attribute specifies	which geocoding	service	can be used. It	takes
       as its value any	subclass of Astro::App::Satpass2::Geocode -- either an
       actual instantiated object or a class name. If the class	name is
       specified, the leading "Astro::App::Satpass2::Geocode::"	can be
       omitted.

       As of version 0.031_001,	support	for "Geo::Coder::Geocoder::US" has
       been retracted, so the default is Astro::App::Satpass2::Geocode::OSM.
       The problem with	"Geo::Coder::Geocoder::US" was the disappearance of
       the underlying web side,	leading	to the retraction of that module.

   geometric
       This boolean attribute specifies	whether	satellite rise and set should
       be computed versus the geometric	horizon	or the effective horizon
       specified by the	"horizon" attribute. If	true, the computation is
       versus the geometric horizon (elevation 0 degrees). If false, it	is
       versus whatever the "horizon" attribute specifies.

       The default is 1	(i.e. true).

   gmt
       This boolean attribute is deprecated. It	is provided for	backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object,	or via the formatter()
       method.

       This attribute allows access to and manipulation	of the formatter
       object's	gmt attribute. This is normally	used to	specify	whether	time
       is displayed in local or	Greenwich Mean Time (a.k.a. Universal Time).
       See the gmt documentation for the default. See the documentation	of the
       actual formatter	class being used for what it does.

       The default will	normally be 0 (i.e. false).

   height attribute
       This numeric attribute specifies	the height of the observer above mean
       sea level, in meters. To	specify	in different units, see	"SPECIFYING
       DISTANCES". The get() method returns meters.

       There is	no default; you	must specify a value.

   horizon
       This numeric attribute specifies	the minimum elevation a	body must
       attain to be considered visible,	in degrees. If the "geometric"
       attribute is false, the rise and	set of the satellite are computed
       versus this setting also.

       See "SPECIFYING ANGLES" for ways	to specify an angle. This attribute is
       returned	in decimal degrees.

       The default is 20 degrees.

   initfile attribute
       This string attribute records the name of the file actually used	by the
       most recent init() call.	It will	be "undef" if init() has not been
       called, or if the most recent init() call did not execute a file.

       This attribute may not be set.

       The default is "undef".

   illum
       This string specifies the name of the class to be used for the
       Astro::Coord::ECI::TLE "illum" attribute. If you	specify	"undef"	you
       get the default.

       The default is Astro::Coord::ECI::Sun.

       Note: I am less than happy about	the implementation of this attribute.
       Be alert	for changes.  If I decide to revoke the	above implementation
       completely there	will be	notice,	and if at all possible a deprecation
       process.

   latitude
       This numeric attribute specifies	the latitude of	the observer in
       degrees north of	the Equator. If	your observing location	is south of
       the Equator, specify a negative number.

       See "SPECIFYING ANGLES" for ways	to specify an angle. This attribute is
       returned	in decimal degrees.

       There is	no default; you	must specify a value.

   local_coord
       This string attribute is	deprecated. It is provided for backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object,	or via the formatter()
       method.

       This string attribute allows access to and manipulation of the
       formatter object's local_coord attribute.  This is normally used	to
       specify the desired coordinates displayed by the	"flare", "pass", and
       "position" methods. See the Astro::App::Satpass2::Format	local_coord
       documentation for the default. See the documentation of the actual
       formatter class being used for what it does.

       The formatter class should implement the	following values:

       'az_rng'	- displays azimuth and range;

       'azel' -	displays elevation and azimuth;

       'azel_rng' - displays elevation,	azimuth, and range;

       'equatorial' - displays right ascension and declination;

       'equatorial_rng'	- displays right ascension, declination, and range;

       undef - displays	the default ('azel_rng').

       The default is undef.

   location attribute
       This string attribute contains a	text description of the	observer's
       location.  This is not used internally, but if it is not	empty it will
       be displayed by the "location" method.

       There is	no default; the	attribute is undefined unless you supply a
       value.

   longitude
       This numeric attribute specifies	the longitude of the observer in
       degrees east of Greenwich, England.  If your observing location is west
       of Greenwich (as	it would be if you live	in North or South America),
       specify a negative number.

       See "SPECIFYING ANGLES" for ways	to specify an angle. This attribute is
       returned	in decimal degrees.

       There is	no default; you	must specify a value.

   max_mirror_angle
       This numeric attribute specifies	the maximum mirror angle for an
       Iridium flare, in degrees. This is the angle subtended by the observer
       and the reflection of the Sun as	seen from the satellite. See the
       Astro::Coord::ECI::TLE::Iridium documentation for more detail. You
       should not normally need	to modify this value.

       The default is the same as for Astro::Coord::ECI::TLE::Iridium.	Again,
       see that	documentation for more detail.

       If Astro::Coord::ECI::TLE::Iridium can not be loaded, the default is
       "undef".

   model
       This string attribute specifies the model to be used to predict the
       satellite position. This	is used	to set the Astro::Coord::ECI::TLE
       model attribute,	and the	valid values are the same as for that package.
       An attempt to set an invalid model will result in an exception.

       The default is 'model', which specifies whatever	model is favored.

   pass_threshold
       This numeric attribute specifies	the number of degrees of elevation
       above the horizon a pass	has to reach before it is reported. If visible
       passes are desired, it must be visible above that elevation.  This
       attribute corresponds to	the same-named Astro::Coord::ECI attribute.

   pass_variant
       This attribute specifies	the "pass_variant" value to set	when doing a
       "pass()"	computation. It	can be set to a	number or a string consisting
       of one or more of the following strings,	which are equivalent to	the
       given "Astro::Coord::ECI::TLE" manifest constants:

	   visible_events   => PASS_VARIANT_VISIBLE_EVENTS
	   fake_max	    => PASS_VARIANT_FAKE_MAX
	   start_end	    => PASS_VARIANT_START_END
	   no_illumination  => PASS_VARIANT_NO_ILLUMINATION
	   brightest	    => PASS_VARIANT_BRIGHTEST
	   none		    => PASS_VARIANT_NONE

       If more than one	value from the above table is specified, they can be
       punctuated by any character that	is not a word or a dash. They can also
       be abbreviated uniquely,	the underscores	can be specified as dashes,
       and they	can be preceded	by a dash, as though they were options.

       When you	specify	a string value,	the derived bits will be set in	the
       attribute value,	or cleared if the name is preceded by 'no'. The
       exception is 'none', which clears all variant bits when it is
       encountered.

       For example,

	satpass2> # Note quotes	in next	line
	satpass2> set pass_variant 'none brightest fake-max'
	satpass2> show pass_variant
	set pass_variant brightest,fake_max
	satpass2> set pass_variant nofake
	satpass2> show pass_variant
	set pass_variant brightest
	satpass2> set pass_variant nobrightest
	satpass2> show pass_variant
	set pass_variant none

   perltime
       This boolean attribute is deprecated. It	is provided for	backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object,	or via the
       time_parser() method.

       This boolean attribute allows access to and manipulation	of the time
       parser object's perltime	attribute.  This is normally used (if at all)
       to specify that the Perl	time built-ins be used to construct the	parsed
       time. See the perltime documentation for	the default. See the
       documentation of	the actual time	parser class being used	for what it
       does.

       This attribute was originally introduced	because	versions of
       Date::Manip prior to 6.0	did not	properly handle	the transition from
       standard	time to	summer time. Of	those time parsers distributed with
       this package, only Astro::App::Satpass2::ParseTime::Date::Manip::v5
       uses this attribute.

       The default will	normally be 0 (i.e. false).

   prompt
       This string attribute specifies the string used to prompt for commands.

       The default is 'satpass2> '.

   refraction
       This Boolean attribute specifies	whether	or not atmospheric refraction
       is taken	into account. It should	ordinarily not be changed, and was
       exposed only out	of curiosity about the size of the effect on (say) the
       time of Sunset.

       The default is 1	(i.e. true).

   simbad_url
       This string attribute does not, strictly	speaking, specify a URL, but
       does specify the	server to use to perform SIMBAD	lookups	(see the
       'lookup'	subcommand of the "sky"	method). Currently-legal values	are
       'simbad.u-strasbg.fr' (the original site) and 'simbad.harvard.edu'
       (Harvard	University's mirror).

       The default is 'simbad.u-strasbg.fr'.

   singleton
       If this boolean attribute is true, the script uses
       Astro::Coord::ECI::TLE::Set objects to represent	all bodies. If false,
       the set object is used only if the observing list contains more than
       one instance of a given NORAD ID. This is really	only useful for
       testing purposes.

       Use of the Astro::Coord::ECI::TLE::Set object causes calculations to
       take about 15% longer.

       The default is 0	(i.e. false).

   spacetrack attribute
       This attribute is the Astro::SpaceTrack object used by the spacetrack()
       method. You must	set it to an Astro::SpaceTrack object, or to undef to
       clear the attribute. If no Astro::SpaceTrack object has been explicitly
       set, the	spacetrack() method will attempt to load Astro::SpaceTrack and
       set this	attribute itself. If it	succeeds, this object will be
       available to the	"get" method.

       This attribute may only be manipulated programmatically;	it may not be
       gotten or set via the "dispatch"	method,	and therefore not by the
       satpass2	script.

       The default is undef.

   stdout
       This attribute determines what the "execute" method does	with its
       output. The possible values are interpreted as follows:

       "undef" - the output is returned;

       scalar reference	- the output is	appended to the	scalar;

       code reference -	the code is called, with the output as its argument;

       array reference - the output is split after newlines, and the result
       pushed onto the array;

       anything	else - the print() method is called on the attribute value,
       with the	output as its argument.

       This attribute may only be manipulated programmatically;	it may not be
       gotten or set via the "dispatch"	method,	and therefore not by the
       satpass2	script.

       The default is the "STDOUT" file	handle.

   output_layers
       This attribute determines which PerlIO layers (formerly known as
       "disciplines") are to be	applied	to newly-opened	output files.
       Already-open files are not affected.

       Note that in the	case of	redirections, the file is opened when the
       first output is done. This means	that you can redirect the output of a
       macro or	source file and	specify	the output layers in that macro	or
       source file, provided you do so before any output is done.

       Having this setting apply to already-opened files was rejected because
       when you	do multiple "binmode()"	calls, the specified layers simply
       accumulate, and there appears to	be no good way to clean	up unwanted
       ones.

       The default is ':encoding(utf-8)'.

   time_format
       This string attribute is	deprecated. It is provided for backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the formatter	object,	or via the formatter()
       method.

       This attribute allows access to and manipulation	of the formatter
       object's	time_format attribute.	This is	normally used as a strftime(3)
       format to format	a time.	See the	time_format documentation for the
       default.	See the	documentation of the actual formatter class being used
       for what	it does.

       The formatter class, if it makes	use of this attribute at all, should
       interpret the value of this attribute as	a strftime(3) format.

       This string attribute specifies the strftime(3) format used to display
       times.  Documentation of	the strftime(3)	subroutine may be found	at
       <https://linux.die.net/man/3/strftime> among other places.

       The above is a long URL,	and may	be split across	multiple lines.	More
       than that, the formatter	may have inserted a hyphen at the break, which
       needs to	be taken out to	make the URL good. Caveat user.

   time_parser attribute
       This attribute specifies	the class to be	used to	parse times.  You can
       set it to either	the actual parser object, or to	the name of the	class
       to use. In the latter case, an object of	the appropriate	class will be
       instantiated, so	"get( 'time_parser' )" always returns an object.  A
       call to "show( 'time_parser' )",	however, will always show the class
       name.

       When setting this attribute to a	class name, the	leading
       'Astro::App::Satpass2::ParseTime::' can be omitted.

       The time	parser must be a subclass of Astro::App::Satpass2::ParseTime.

       The default is 'Astro::App::Satpass2::ParseTime', which actually
       returns one of its subclasses, preferring the one that uses
       Date::Manip. If Date::Manip is not installed, you get
       Astro::App::Satpass2::ParseTime::ISO8601, which is a home-grown parser
       for ISO-8601-ish	times, and maybe better	than nothing.

   twilight
       This attribute specifies	the elevation of the Sun at which day becomes
       night or	vice versa, in degrees.	This will normally be a	negative
       number, since a positive	number says the	Sun is above the horizon.

       The words 'civil', 'nautical', or 'astronomical'	are also acceptable,
       as is any unique	abbreviation of	these words. They specify -6, -12, and
       -18 degrees respectively.

       See "SPECIFYING ANGLES" for ways	to specify an angle. This parameter is
       displayed in decimal degrees, unless 'civil', 'nautical', or
       'astronomical' was specified.

       The default is 'civil'.

   tz
       This string attribute is	deprecated. It is provided for backward
       compatibility with the satpass script. The preferred way	to manipulate
       this is either directly on the time parser and formatter	objects, or
       via the formatter() and time_parser() methods on	the relevant objects.

       This string attribute specifies both the	default	time zone for date
       parsing and the time zone for formatting	of local times.	This
       overloading exists for historical reasons, but will change in the
       future.	At any event it	takes effect to	the extent the date parser and
       formatter objects support it.

       If you are running under	Mac OS 9 or less, or under VMS,	you may	have
       to set this. Otherwise, you normally should not bother unless you are
       deliberately doing input	or producing output for	a time zone other than
       either your own,	or GMT.

   verbose
       This boolean attribute specifies	whether	the "pass" method should give
       the position of the satellite every step	that it	is above the horizon.
       If false, only rise, set, max, into or out of shadow, and the beginning
       or end of twilight are displayed.

       The default is 0	(i.e. false).

   visible
       This boolean attribute specifies	whether	the "pass" method should
       report only visible passes (if true) or all passes (if false). A	pass
       is considered to	have occurred if the satellite,	at some	point in its
       path, had an elevation above the	horizon	greater	than the horizon
       attribute.  A pass is considered	visible	if it is after the end of
       evening twilight	or before the beginning	of morning twilight for	the
       observer	(i.e. "it's dark"), but	the satellite is illuminated by	the
       Sun.

       The default is 1	(i.e. true).

   warning
       This boolean attribute specifies	whether	warnings and errors are
       reported	via "carp" and "croak",	or via "warn" and "die". If true, you
       get "warn" and "die", if	false "carp" and "croak". This is set true in
       the object instantiated by the run() method.

       The default is 0	(i.e. false).

   warn_on_empty
       This boolean attribute specifies	whether	the list() interactive method
       warns on	an empty list. If false, you just get nothing back from	it.

       The default is 1	(i.e. true).

   webcmd
       This string attribute specifies the system command to spawn to display
       a web page. If not the empty string, the	help method uses it to display
       <https://metacpan.org/dist/Astro-App-Satpass2>. Mac OS X	users will
       find 'open' a useful setting, and Windows users will find 'start'
       useful.

       This functionality was added on speculation, since there	is no good way
       to test it in the initial release of the	package.

       As of version 0.035_01, a value of '1' causes Browser::Open to be
       loaded, and the web command is taken from it. All other true values are
       deprecated, on the following schedule:

       2018-11-01: First use of	deprecated value will warn;
       2019-05-01: All uses of deprecated value	will warn;
       2019-11-01: Any use of deprecated value is fatal;
       2020-05-01: Attribute is	treated	as Boolean.

       The above schedule may be extended based	on what	other changes are
       needed, but will	not be compressed.

       The default is '' (i.e. the empty string), which	leaves the
       functionality disabled.

SPECIFYING ANGLES
       This class accepts angle	input in the following formats:

       * Decimal degrees.

       * Hours,	minutes, and seconds, specified	as "hours:minutes:seconds".
       You would typically only	use this for right ascension. You may specify
       fractional seconds, or fractional minutes for that matter.

       * Degrees, minutes, and seconds,	specified as
       "degreesDminutesMsecondsS".  The	letters	may be specified in either
       case, and trailing letters may be omitted. You may specify fractional
       seconds,	or fractional minutes for that matter.

       Examples:

	23.4 specifies 23.4 degrees.
	1:22.3 specifies an hour and 22.3 minutes
	12d33m5	specifies 12 degrees 33	minutes	5 seconds

       Right ascension is always positive. Declination and latitude are
       positive	for north, negative for	south. Longitude is positive for east,
       negative	for west.

SPECIFYING DISTANCES
       This class accepts distances in a number	of units, which	are specified
       by appending them to the	magnitude of the distance. The default unit is
       usually "km" (kilometers), but for the "height attribute" it is "m"
       (meters). The following units are recognized:

	au - astronomical units;
	ft - feet;
	km - kilometers;
	ly - light years;
	m -- meters;
	mi - statute miles;
	pc - parsecs.

SPECIFYING TIMES
       This class (or, more properly, the modules it is	based on) does not, at
       this point, do anything fancy with times. It simply handles them	as
       Perl scalars, with the limitations that that implies.

       Times may be specified absolutely, or relative to the previous absolute
       time, or	to the time the	object was instantiated	if no absolute time
       has been	specified.

   Absolute time
       Any time	string not beginning with '+' or '-' is	assumed	to be an
       absolute	time, and is fed to one	of the Astro::App::Satpass2::ParseTime
       modules for parsing. What is legal here depends on which	parser is in
       use. If you have	Date::Manip, you will get a parser based on that
       module, with all	the functionality that implies.	If Date::Manip is not
       installed, you get Astro::App::Satpass2::ParseTime::ISO8601, which
       parses a	subset of the ISO 8601 times, as a fall-back.

       Date::Manip has at least	some support for locales, so check the
       Date::Manip documentation before	you assume you must enter dates	in
       English.	The ISO	8601 format is all-numeric.

   Epoch time
       Epoch time can be specified directly, bypassing the time	parser.	There
       are two ways to do this:

       * Prefix	the string 'epoch ' to the epoch time;

       * Pass a	reference to the epoch time.

   Relative time
       A relative time is specified by '+' or '-' and an integer number	of
       days. The number	of days	must immediately follow	the sign. Optionally,
       a number	of hours, minutes, and seconds may be specified	by placing
       whitespace after	the day	number,	followed by hours:minutes:seconds. If
       you choose not to specify seconds, omit the trailing colon as well. The
       same applies if you choose not to specify minutes. For example:

       +7 specifies 7 days after the last-specified time.

       '+7 12' specifies 7 days	and 12 hours after the last-specified time.

       If a relative time is specified as the first time argument to a method,
       it is relative to the most-recently-specified absolute or epoch time,
       even if that time was specified by default. Relative times in
       subsequent arguments to the same	method are relative to the previously-
       specified time, whether absolute, epoch or relative. For	example:

	$satpass2->almanac( '',	'+5' );

       establishes the most-recently-specified time as 'today midnight', and
       does an almanac for 5 days from that time. If the next method call is

	$satpass2->almanac( '+5', '+3' );

       this produces almanac output for	three days, starting 5 days after
       'today midnight'.

SPECIFYING INPUT DATA
       Some of the methods of this class (currently init(), load() and
       source()) read data and do something with it. These data	can be
       specified in a number of	ways:

       o   As a	file name;

       o   As a	URL if LWP::UserAgent is installed;

       o   As a	scalar reference;

       o   As an array reference;

       o   As a	code reference.

	   The code reference is expected to return a line each	time it	is
	   called, and "undef" when the	data are exhausted.

	   Obviously, the specifications that involve references are not
	   available to	a user of the satpass2 script.

TOKENIZING
       When this class is used via the run() or	execute() methods, method
       names and arguments are derived by tokenizing lines of text. No attempt
       has been	made to	provide	full shell-style tokenization with all the
       bells and whistles, but such features as	do exist are based on bash(1).
       The tokenization	rules are:

       The line	is broken into tokens on spaces, unless	the spaces are quoted
       or escaped as described below.

       A back slash ("\") escapes the next character, turning a	meta-character
       into a normal one. Lines	can be continued by placing the	back slash at
       the end of the line.

       Single quotes ('') cause	everything inside them to be taken as a	single
       token, and almost anything inside them to be taken as a literal.
       Unlike bash(1), but like	perl(1), the back slash	is recognized, but its
       only use	is to escape a single quote or another back slash.

       Double quotes ("") cause	everything inside them to be taken as a	single
       token. Unlike single quotes, all	the usual "C" meta-characters except
       single quotes are recognized inside double quotes. In addition, Perl
       meta-characters "\E", "\F", "\L", "\U", "\l", and "\u" (though not
       "\Q") are recognized inside double quotes. Note,	though,	that before
       Perl 5.15.8 "\F"	is equivalent to "\L".

       The dollar sign ("$") introduces	an interpolation. If the first
       character after the dollar sign is not a	left curly bracket, that
       character and any following word	characters name	the thing to be
       interpolated, which may be one of the following things.

       One of the following special variables.
	    0 -	The name of the	Perl script ($0);
	    # -	The number of positional arguments;
	    * -	All arguments, but joined by white space inside	double
		quotes;
	    @ -	All arguments as individual tokens, even inside	double
		quotes;
	    $ -	The process ID;
	    _ -	The name of the	Perl executable	($^X).

       An argument, specified by its number, starting from 1.
       An attribute name.
	   If the attribute is 'formatter', 'spacetrack', or 'time_parser' the
	   attribute name can be followed by a dot ('.') and the name of an
	   attribute of	the resultant object.

       An environment variable.

       If the interpolation can	be more	than one of the	things on the above
       list, the first thing actually encountered will be used.	For example,
       $horizon	will interpolate the value of the "horizon|/horizon"
       attribute, even in the presence of an environment variable named
       'horizon'.

       The interpolated	value will be split on white space into	multiple
       tokens unless the interpolation takes place inside double quotes.

       The name	of the thing to	be interpolated	can be enclosed	in curly
       brackets	if needed to delimit it	from following text. This also allows
       the substitution	of text	for the	argument, as follows:

       "${parameter:-text}" causes the given text to be	substituted if the
       parameter is undefined.

       "${parameter:=text}" is the same	as above, but also causes the text to
       be assigned to the parameter if it is unassigned. Like bash(1), this
       assignment can not take place on	numbered parameters or special
       variables. If done on an	attribute or environment variable, it causes
       that attribute or environment variable to be set	to the given value.

       "${parameter:?text}" causes the parse to	fail with the error 'text' if
       the parameter is	undefined.

       "${parameter:+text}" causes the value of	the given text to be used if
       the parameter is	defined, otherwise '' is used.

       "${parameter:offset}" and "${parameter:offset:length}" take substrings
       of the parameter	value. The offset and length must be numeric.

       Note that token expansion takes place inside curly brackets.

       An exclamation mark ("!") in front of the name of an interpolated
       parameter introduces a level of indirection, provided it	occurs inside
       curly brackets. That is,	if environment variable	"FOO" is defined as
       'BAR', and environment variable "BAR" is	defined	as 'BAZ', then
       "${!FOO}" interpolates 'BAZ'.  Only one level of	indirection is
       supported.

       One of the angle	bracket	characters ("<"	or ">")	or the vertical	bar
       character ("|") introduce a redirection specification (and,
       incidentally, a new token). Anything after the meta-characters in the
       same token is taken to be the file or program name.

       The only	redirections that actually work	are ">"	(output	redirection)
       and ">>"	(output	redirection with append).  The "<" and "<<" look like
       input redirections but are not, at least	not in the sense of making
       data appear on standard in. The first is	replaced by the	contents of
       the given file or URL. The second works like a Perl here	document, and
       interpolates unless the here document terminator	is enclosed in single
       quotes.

       Note that in the	case of	output redirections, the file is not actually
       opened until output to it is done. See the documentation	on the
       output_layers attribute for the rationale for this.

       Caveat: redirection tests fail under MSWin32 -- or at least they	did
       until I bypassed	them under that	operating system. I do not know	if
       this is a failure of the	redirection mechanism or a problem with	the
       test. I suspect the latter, but will welcome evidence of	the former.

       Any unquoted token or redirection file name which begins	with a tilde
       ("~") has tilde expansion performed on everything up to the first slash
       ("/"), or the end of the	token, provided	the operating system supports
       this.  The empty	username is expanded using "getpwuid()"	if this	is
       supported, or various possibly-OS-specific environment variables	if
       not. Non-empty user names are expanded if "getpwnam()" is supported and
       the user	actually exists; otherwise an exception	is raised. Tilde
       expansion is not	done inside quotes (either single or double), even if
       the tilde is the	first character. This is consistent with bash(1).

       As special cases	of tilde expansion, "~." expands to the	current
       directory, and "~~" expands to the configuration	directory. The
       expansion of "~~" will throw an exception if the	configuration
       directory does not exist.

       Wild card expansion is never performed by the tokenizer.	If an
       individual method does wild card	expansion on its arguments, this will
       be noted	in its documentation.

DIFFERENCES FROM SATPASS
       The functionality provided by this package is similar, but not
       identical, to the functionality provided	by the satpass script included
       in package Astro-satpass. Compatibility has been	retained unless	there
       appeared	to be a	pressing reason	to make	a change, but this rewrite has
       also provided an	opportunity to rethink some things that	appeared to
       need rethinking.

       The following differences from satpass are known	to exist:

   Tokenization
       In the "satpass"	script,	all quotes interpolated, but in	this package
       only """	interpolates.

       Assigning a new value to	an undefined positional	parameter is no	longer
       allowed.	The satpass script allowed "${1:=Foo}",	but this package does
       not. The	idea was to be consistent with bash(1).

       Here documents are now supported.

   Added commands/methods
       Some methods have been added which do not appear	as commands in
       satpass.	Those methods, and the reason for their	addition, are:

       add Added in version 0.021.

       begin, end
	   The restructuring involved in the rewrite made it possible to have
	   explicit localization blocks, which I kind of wanted	all along.

       location
	   It was decided to have an explicit method to	display	the location,
	   rather than have certain methods (e.g. "pass()") display it,	and
	   others (e.g.	"flare()") not.	In other words,	I decided I was	not
	   smart enough	to know	when a user would want the location displayed.

       if  Added in version 0.032.

       pwd This	seems to go with "cd()".

       time
	   The satpass script had a "-time" option whenever I wanted to	time
	   something. The architecture of this package made it simpler to just
	   have	a separate interactive method.

   Deprecated commands
       Some commands are deprecated, but will remain for backward
       compatibility until support for "satpass" is dropped. After this
       happens,	they will be put through a deprecation cycle and disappear.

       st  This	command/method is deprecated in	favor of the spacetrack()
	   command/method.  It will remain until support for the satpass
	   script is dropped, and then be put through a	deprecation cycle and
	   removed.

	   People using	the 'st' command interactively can define 'st' as a
	   macro:

	    satpass2> macro define st 'spacetrack "$@"'

	   Note	that the elimination of	this command/method leaves you no way
	   to localize individual attributes of	the spacetrack attribute. You
	   can still localize the whole	object,	though.	Please contact me if
	   you need the	removed	functionality.

   Dropped commands
       Some commands that appear in the	satpass	script have been dropped, for
       various reasons.	The commands, and the reasons for eliminating them,
       are given below.

       check_version
	   This	command	was originally added because I wanted to split the
	   satpass script off from Astro::Coord::ECI, but CPAN does not	detect
	   changes in scripts.

	   It was dropped because the satpass2 script is trivial. Added
	   functionality will (almost always) go in "Astro::App::Satpass2",
	   and changes there will be detected by the "cpan", "cpanp", or
	   "cpanm" scripts.

       store, retrieve
	   These were added on a whim, and I have never	even come close	to
	   using them. If you have a need for them please contact me.

       times
	   This	was added because I was	working	on a way to extend the time
	   range and wanted a way to check the code. This work was stalled,
	   and the Time::y2038 module and Perl 5.12 both appear	to make	it
	   obsolete anyway.

   Modified commands/methods
       Some commands that appear in the	satpass	script have been modified.
       The commands, and the reasons for their modification, appear below.

       almanac
	   The location	of the observing station is no longer emitted as part
	   of the output; an explicit "location()" is needed. I	decided	that I
	   was not really smart	enough to know when the	user would want	this
	   output.

	   Until support for the satpass script	is dropped, though, output
	   from	this command will still	include	the location if	the command is
	   issued from a satpass initialization	file (as opposed to an
	   "Astro::App::Satpass2" initialization file),	or from	a macro
	   defined in a	satpass	initialization file.

       flare
	   The sense of	the "-am", "-day", and "-pm" options is	reversed from
	   the sense in	satpass. That is, in satpass, "-am" meant not to
	   display morning flares, whereas in "Astro::App::Satpass2", "-am"
	   means not to	display	morning	flares,	and "-noam" means to display
	   them. I personally found the	satpass	functionality confusing.

	   In order to ease the	transition to "Astro::App::Satpass2", these
	   options will	be taken in their satpass sense	(and inverted to their
	   new sense before use) if the	"flare"	command	is used	in a satpass
	   initialization file,	or in a	macro defined in a satpass
	   initialization file.	There is no supported way to get the satpass
	   behavior when using the "flare" command in any other	environment,
	   or when calling the "flare()" method. This functionality will be
	   revoked when	support	for satpass is dropped.

       geocode
	   Geocoding is	handled	by external modules, typically those that do
	   not require the registration	of an application key. A wrapper class
	   has been provided for Geo::Coder::OSM. The names of the wrapper
	   classes are (so far)	derived	from the names of the wrapped classes
	   by "s/\AGeo::Coder::/Astro::App::Satpass2::Geocode::/", and the
	   constant prefix on the wrapper name may be omitted when setting the
	   geocoder.

       pass
	   The location	of the observing station is no longer emitted as part
	   of the output; an explicit "location()" is needed. I	decided	that I
	   was not really smart	enough to know when the	user would want	this
	   output.

	   Until support for the satpass script	is dropped, though, output
	   from	this command will still	include	the location if	the command is
	   issued from a satpass initialization	file (as opposed to an
	   "Astro::App::Satpass2" initialization file),	or from	a macro
	   defined in a	satpass	initialization file.

       position
	   The method generates	position information for a single time.	The
	   satpass time	range and "-realtime" functions	have been revoked.
	   This	function was added when	I had vague dreams of figuring out how
	   to drive a telescope	off the	output,	but so far those dreams	are
	   unrealized, and I can think of no other use for the functionality.
	   The rewritten output	mechanism is not capable of actually
	   displaying output in	realtime, and handling multiple	times in a
	   system that separates formatting from computation appeared to be
	   too difficult to tackle without an incentive.

   Dropped attributes
       simbad_version
	   This	attribute was used to select the version of the	SIMBAD
	   protocol to use to access <http://simbad.u-strasbg.fr/simbad/>.
	   Since only version 4	is currently supported,	and this has been the
	   default in satpass for some time, this attribute is eliminated.

   Modified attributes
       backdate
	   This	attribute defaults to false (i.e. 0). In the satpass script,
	   it defaulted	to true.

       country
	   This	attribute existed to support selection of geocoding servers,
	   but since geocoding is now done with	plug-in	modules, this
	   attribute is	ignored.  This attribute will be dropped when support
	   for satpass is dropped.

       date_format
	   This	attribute is deprecated. It is properly	an attribute of
	   Astro::App::Satpass2::Format, and is	implemented as a wrapper for
	   that	class' "date_format" attribute.	It will	be dropped when
	   support for satpass is dropped.

       desired_equinox_dynamical
	   This	attribute is deprecated. It is properly	an attribute of
	   Astro::App::Satpass2::Format, and is	implemented as a wrapper for
	   that	class' "desired_equinox_dynamical" attribute. It will be
	   dropped when	support	for satpass is dropped.

       explicit_macro_delete
	   This	attribute is ignored and deprecated, since the
	   "Astro::App::Satpass2" macro() functionality	always requires	an
	   explicit "delete" to	delete a macro.	This attribute will be dropped
	   when	support	for satpass is

       gmt This	attribute is deprecated. It is properly	an attribute of
	   Astro::App::Satpass2::Format, and is	implemented as a wrapper for
	   that	class' "gmt" attribute.	It will	be dropped when	support	for
	   satpass is dropped.

       local_coord
	   This	attribute is deprecated. It is properly	an attribute of
	   Astro::App::Satpass2::Format, and is	implemented as a wrapper for
	   that	class' "local_coord" attribute.	It will	be dropped when
	   support for satpass is dropped.

       time_format
	   This	attribute is deprecated. It is properly	an attribute of
	   Astro::App::Satpass2::Format, and is	implemented as a wrapper for
	   that	class' "time_format" attribute.	It will	be dropped when
	   support for satpass is dropped.

       twilight
	   The satpass mutator forced the sign to be negative. The
	   "Astro::App::Satpass2" mutator does not. Note that a	positive
	   setting means the Sun is above the horizon.

       tz  This	attribute is deprecated. It is properly	an attribute of
	   "Astro::App::Satpass2::Format|Astro::App::Satpass2::Format" and
	   "Astro::App::Satpass2::ParseTime|Astro::App::Satpass2::ParseTime".
	   These should	not have been combined because there is	no way to
	   ensure that the packages underlying each of these takes the same
	   time	zone specifications.

ENVIRONMENT VARIABLES
       "SATPASS2INI" can be used to specify an initialization file to use in
       lieu of the default. This can still be overridden by the
       "-initialization_file" command option.

       "SATPASSINI" will be used in a last-ditch effort	to find	an
       initialization file, if "-initialization_file" is not specified,
       "SATPASS2INI" does not exist, and the initialization file was not found
       in its default location.

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

       TIGER/LineA(R) is a registered trademark	of the U.S. Census Bureau.

perl v5.32.1			  2021-11-04	       Astro::App::Satpass2(3)

NAME | SYNOPSIS | NOTICE | OVERVIEW | Optional Modules | METHODS | ATTRIBUTES | SPECIFYING ANGLES | SPECIFYING DISTANCES | SPECIFYING TIMES | SPECIFYING INPUT DATA | TOKENIZING | DIFFERENCES FROM SATPASS | ENVIRONMENT VARIABLES | 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&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help