new

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

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

add

 $satpass2->add( @bodies );

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

The invocant is returned.

alias

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

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

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

almanac

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

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

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

The following options are recognized:

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

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

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

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

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

begin

 $satpass2->begin();
 satpass2> begin

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

cd

 $satpass2->cd();
 satpass2> cd

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

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

choose

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

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

The following options may be specified:

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

Nothing is returned.

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

clear

 $satpass2->clear();
 satpass2> clear

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

dispatch

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

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

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

drop

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

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

Nothing is returned.

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

dump

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

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

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

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

A reference specifies that the referent is dumped;

'frame' specifies that the frame stack is dumped;

'tokens' specifies that the next argument is tokenized and dumped;

'twilight' specifies the twilight settings are dumped;

Anything else causes the specified body to be dumped.

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

echo

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

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

The following option may be specified:

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

elsif

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

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

else

 $satpass2->else();
 satpass2> else

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

end

 $satpass2->end();
 satpass2> end

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

error

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

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

execute

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

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

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

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

exit

 $satpass2->exit();
 satpass2> exit

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

export

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

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

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

Either way, nothing is returned.

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

flare

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

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

The following options are available:

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

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

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

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

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

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

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

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

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

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

formatter

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

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

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

desired_equinox_dynamical

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

format

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

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

An example may help:

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

is equivalent to

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

This method takes the following options:

-changes

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

The default is "-nochanges".

-raw

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

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

geocode

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

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

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

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

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

The results of the lookup are returned.

geodetic

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

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

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

get

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

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

height

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

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

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

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

help

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

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

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

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

The viewer is whatever is the default for your system.

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

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

In any case, nothing is returned.

if

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

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

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

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

For example (assuming OID 99999 is not loaded)

 $satpass2->dispatch( qw{ if loaded 99999 then begin } );
 
 # The following will do nothing because the above if()
 # was not satisfied.
 $satpass2->dispatch( qw{ echo hello there } );
 
 # The following will be executed even though the if()
 # was not satisfied, because it is not being routed
 # through dispatch()
 $satpass2->spacetrack( retrieve => 25544 );
 
 # The following ends the scope of the if()
 $satpass2->execute( qw{ end } );
 
 # The following will be executed because we are no longer
 # in the scope of the unsatisfied if().
 $satpass2->execute( qw{ echo we are back } );

The following operators and functions are implemented:

( ... )

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

-n

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

-z

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

and

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

attr

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

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

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

 if attr spacetrack and attr spacetrack.username ...
    

env

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

loaded

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

not

This prefix operator computes the Boolean negation of its operand.

or

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

os

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

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

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

then

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

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

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

init

 $output = $satpass2->init();

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

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

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

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

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

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

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

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

initfile

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

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

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

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

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

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

There are two options to this method:

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

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

list

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

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

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

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

 satpass2> list hst

is equivalent to

 satpass2> list -choose hst

but

 satpass2> list -choose hst iss

will only list 'hst'.

load

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

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

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

Nothing is returned.

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

localize

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

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

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

location

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

This interactive method returns the current location.

macro

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

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

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

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

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

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

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

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

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

The 'define'> subcommand supports the following options:

-completion

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

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

The 'load' subcommand supports the following options:

-lib

 -lib ~/lib
    

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

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

-verbose

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

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

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

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

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

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

magnitude_table

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

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

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

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

"clear" - clears the magnitude table.

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

"list" - a synonym for "show".

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

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

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

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

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

pass

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

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

The following options are available:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

perl

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

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

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

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

phase

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

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

position

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

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

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

The following options may be specified:

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

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

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

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

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

pwd

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

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

quarters

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

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

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

The following options are available:

-choose

 -choose moon
    

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

-dump

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

-q0, or -new, or -spring

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

-q1, or -first, or -summer

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

-q2, or -full, or -fall

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

-q3, or -last, or -winter

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

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

run

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

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

The valid options are:

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

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

The steps in running the application are:

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

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

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

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

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

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

7) Further commands are read as described below.

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

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

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

The exit command causes the method to return.

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

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

save

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

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

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

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

The following options are allowed:

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

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

set

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

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

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

show

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

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

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

sky

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

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

The possible subcommands are:

add

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

class

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

-add

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

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

-delete

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

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

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

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

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

clear

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

drop

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

list

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

lookup

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

source

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

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

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

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

spacetrack

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

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

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

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

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

show

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

config

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

This method takes the following options:

-changes

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

The default is "-nochanges".

-raw

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

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

st

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

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

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

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

The following options are allowed on any retrieval:

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

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

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

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

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

status

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

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

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

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

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

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

"list" - a synonym for "show".

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

There are two options:

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

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

station

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

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

system

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

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

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

time

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

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

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

You can not time the end() method.

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

time_parser

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

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

This method takes the following options:

-changes

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

The default is "-nochanges".

-raw

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

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

tle

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

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

The following options are allowed:

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

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

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

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

 satpass2> tle -verbose -json

uses template 'tle_json' to display the output.

unexport

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

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

validate

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

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

The only valid option is

 -quiet - suppress output of validation failures.

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

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

version

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

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

wail

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

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

want_pass_variant

 $satpass2->want_pass_variant( 'brightest' );

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

weep

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

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

whinge

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

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

__add_to_observing_list( @bodies );

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

__choose

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

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

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

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

invert

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

bodies

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

 satpass2> list
    

)will be aggregated and appended to the @list.

sky

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

 satpass2> sky list
    

) will be appended to the @list.

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

The contents of @choice are interpreted as follows:

strings

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

Regexp objects

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

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

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

__format_data

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

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

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

__parse_angle

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

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

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

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

accept

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

__parse_distance

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

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

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

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

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

Specified units are converted to lower case before use.

__parse_time

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

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

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

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

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

appulse

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

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

backdate

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

background

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

continuation_prompt

The default is '> '.

country

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

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

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

The default is 'us'.

date_format

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

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

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

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

debug

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

The default is 0.

edge_of_earths_shadow

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

ellipsoid

The default is 'WGS84'.

error_out

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

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

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

events

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

exact_event

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

explicit_macro_delete

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

extinction

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

filter

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

flare_mag_day

The default is -6.

flare_mag_night

The default is 0.

formatter attribute

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

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

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

geocoder

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

geometric

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

gmt

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

There is no default; you must specify a value.

horizon

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

The default is 20 degrees.

initfile attribute

This attribute may not be set.

The default is "undef".

illum

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

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

latitude

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

There is no default; you must specify a value.

local_coord

This string attribute 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

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

longitude

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

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

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

model

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

pass_threshold

pass_variant

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

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

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

For example,

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

perltime

This boolean attribute 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

The default is 'satpass2> '.

refraction

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

simbad_url

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

singleton

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

"undef" - the output is returned;

scalar reference - the output is appended to the scalar;

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

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

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

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

The default is the "STDOUT" file handle.

output_layers

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

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

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

time_format

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

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

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

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

time_parser attribute

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

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

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

visible

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

warning

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

warn_on_empty

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

webcmd

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

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

2018-11-01: First use of deprecated value will warn;

2019-05-01: All uses of deprecated value will warn;

2019-11-01: Any use of deprecated value is fatal;

2020-05-01: Attribute is treated as Boolean.

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

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

Absolute time

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

Epoch time

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

* Pass a reference to the epoch time.

Relative time

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

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

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

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

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

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

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

Tokenization

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

add

Added in version 0.021.

begin, end

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

location

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

if

Added in version 0.032.

pwd

This seems to go with "cd()".

time

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

Deprecated commands

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

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

almanac

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

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

flare

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

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

geocode

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

pass

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

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

position

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

Dropped attributes

simbad_version

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

Modified attributes

backdate

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

country

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

date_format

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

desired_equinox_dynamical

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

explicit_macro_delete

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

gmt

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

local_coord

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

time_format

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

twilight

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

tz

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