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:

• As a file name;

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

• As a scalar reference;

• As an array reference;

• 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/Line® is a registered trademark of the U.S. Census Bureau.

cpanm Astro::App::Satpass2

perl -MCPAN -e shell
install Astro::App::Satpass2