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 NASA
$satpass2->spacetrack( qw{ spaceflight -all } );
# 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 NASA
satpass2> spacetrack spaceflight -all
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

This is alpha code. It has been tested on my box, but has limited exposure to the wild. Also, the public interface may not be completely stable, though I will try to call attention to any incompatible changes.

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/. 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 can install the latest version of Date::Manip.

* If you a Perl before 5.10, the latest version of Date::Manip will not work, and you will have to install version 5.56. This version of Date::Manip is known not to support summer time (or daylight saving time, if you will), 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::Geocoder::US

This module is used by the default geocoder for the geocode() method. If you are not interested in using the geocode() method you do not need this module.

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::Coder::TomTom

This module is used by the Tom Tom geocoder for the geocode()|/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.

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

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

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.

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.

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.

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

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 related Perl modules by specifying the appropriate arguments, 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 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 the http://search.cpan.org/ page for this package, and arguments will be ignored.

In any case, nothing is returned.

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.

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.

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

For semi-compatibility backward, each of these 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.

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

For subcommands other than 'define', 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.

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:

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

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

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

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

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.

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.

-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 option is available:

-dump produces debugging output.

The -dump option should be considered a troubleshooting tool, which may change or disappear without notice.

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.

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' adds an object to the background. The first argument is the name of the object. 'Sun' and 'Moon' (not case-sensitive) are special cases, and cause the Sun or Moon to be added. Anything else 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.

'Clear' clears all background objects. It takes no arguments. Nothing is returned.

'Drop' 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' 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' 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:

-all specifies the retrieval of all manned spaceflight elements;
-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.

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 option is allowed:

-verbose produces an expanded list, with data labeled.

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.

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 http://www.iso.org/iso/en/prods-services/iso3166ma/index.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, or via the formatter() method.

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 http://www.openbsd.org/cgi-bin/man.cgi?query=strftime&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html, 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 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 parameter corresponds to the same-named Astro::Coord::ECI parameter.

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

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::Satpass::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.

The default is the first of Astro::App::Satpass2::Geocode::Geocoder::US, Astro::App::Satpass2::Geocode::OSM, or Astro::App::Satpass2::Geocode::TomTom that can be loaded. See the documentation for details of these, but basically each Astro::App::Satpass2::Geocode::* class wraps a correspondingly-named Geo::Coder::* class, which must be installed.

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.

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.

lit

This boolean attribute is deprecated. It is provided for backward compatibility with the satpass script. The edge_of_earths_shadow attribute is preferred, and lit is implemented in terms of that attribute. Note that any non-zero value of edge_of_earths_shadow will cause $app->get( 'lit' ) to return true.

Like the current satpass script, every use of this attribute will result in a warning. In the first release on or after March 1 2013, this will become fatal.

This boolean attribute specifies how to determine if a body is lit by the Sun. If true (i.e. 1) it is considered to be lit if the upper limb of the sun is above the horizon, as seen from the body. If false (i.e. 0), the body is considered lit if the center of the sun is above the horizon.

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

local_coord

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.

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.

perltime

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

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.

time_format

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 http://www.openbsd.org/cgi-bin/man.cgi?query=strftime&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html, among other places.

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 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 the help for this package on http://search.cpan.org/. 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.

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.

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 time, even if that absolute time was specified by default. Relative times in subsequent arguments to the same method are relative to the previously-specified time, whether absolute 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 meta-characters except single quotes are recognized inside double quotes.

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 either an argument (specified by its number, starting from 1), an attribute of the object, an environment variable, or any of the following special characters:

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

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 at the moment are > (output redirection), >> (output redirection with append), and << (here documents, which are not really a redirection). Unless the here document terminator is enclosed in single quotes, interpolation is done inside the here document.

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

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:

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

Support for http://geocoder.ca/ has been dropped, because the web service changed its access policy. This functionality became unsupported in satpass 0.021 (Astro-satpass 0.021 13-Feb-2009) for pretty much the same reason.

Instead, geocoding is handled by external modules, typically those that do not require the registration of an application key. Wrapper classes have been provided for three of these: Geo::Coder::Geocoder::US, Geo::Coder::OSM, and Geo::Coder::TomTom. 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

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

BUGS

Bugs can be reported to the author by mail, or through http://rt.cpan.org/.

AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)

COPYRIGHT AND LICENSE

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.

To install Astro::App::Satpass2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::App::Satpass2

CPAN shell

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

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)