view release on metacpan or  search on metacpan

lib/Astro/App/Satpass2/TUTORIAL.pod  view on Meta::CPAN

 satpass2> formatter tz MST7MDT

(for Mountain time). If it works, fine. If not, you can make it work by
installing L<DateTime|DateTime> and
L<DateTime::TimeZone|DateTime::TimeZone>. Doing this also gives you the
Olson database zone names (e.g. C<America/New_York>) if you prefer
these.

Similarly, if you install the optional L<Date::Manip|Date::Manip>
module, you can set a default input zone other than your own by
something like

 satpass2> time_parser tz MST7MDT

The C<time_parser> and C<formatter> time zones are set separately not
only so that you can make them different, but because the author can not
guarantee that the underlying modules will accept the same settings.

=head2 Command Macros

A command macro is simply a named set of C<Astro::App::Satpass2>
commands, somewhat like a C<bash> shell function. A command macro is
executed by giving its name, so in essence command macros are ways of
creating new commands.

The definition of a macro is simply the list of commands it issues. Each
command is a single argument, and therefore probably needs to be quoted.
When the command to be issued itself contains quotes, you either use a
different style (single versus double quotes) or you escape the quote
mark with a back slash (C<'\'>). A simple macro definition would be
something like

 satpass2> macro defined hi 'echo "Hello world!"'

When a command macro is executed it can be passed arguments. The details
of how these work will be deferred for the sake of getting on with the
tutorial, but a case of interest is the fact that C<"$@"> (the quotes
being part of the syntax) expands to all the arguments passed to the
macro.

=head2 Multiple Locations

What this topic actually describes is a way to have multiple locations
on tap, so that if you are going to be at point 'A' from Monday through
Wednesday, and point 'B' Thursday and Friday you can easily switch
between them.

The first thing our hypothetical user needs is a command macro to set
the location to his or her home location. The definition comes from our
first example:

 satpass2> macro define home \
 > "set location '1600 Pennsylvania Ave, Washington DC'" \
 > "set latitude 38d53m55.5s longitude -77d2m15.7s" \
 > "set height 54.72ft"
 satpass2>

Normally, this would all have to go on the same line, but
C<Astro::App::Satpass2> recognizes an end-of-line back slash as a
continuation mark, so all four lines above are parsed as though they are
the same line. C<Astro::App::Satpass2> changes the prompt for a
continuation line, just to keep you on your toes.

Now we need another place to visit -- say, the residence of the Prime
Minister of Canada:

 satpass2> macro define sussex_drive \
 > "set location '24 Sussex Drive, Ottawa, ON'" \
 > "set latitude 45.444348 longitude -75.693934" \
 > "set height 50m"
 satpass2>

Now, to switch locations to the Prime Minister's residence, just say

 satpass2> sussex_drive
 satpass2>
 satpass2> # and to confirm it,
 satpass2> location
 Location: 24 Sussex Drive, Ottawa, ON
           Latitude 45.4443, longitude -75.6939, height 50 m
 satpass2>

And to return home, just say

 satpass2> home

Of course, these are really only useful if they are in your
initialization file. And they can be, with the usual incantation:

 satpass2> save -changes -overwrite

=head2 Temporary Settings

As you recall from the section on L<IRIDIUM FLARES|/IRIDIUM FLARES>, if
you are trying to imitate the results from Heavens Above you have to
tweak the default settings a bit. These settings stay tweaked until you
put them back to their original values. If you always want the tweaks
when you do Iridium flare predictions, you can put them into a command
macro along with the flare prediction. Values of settings can be
localized to a macro (among other things), so that the old values are
restored when the macro exits. The example could be defined as a command
macro like this:

 satpass2> macro define iridium_flare \
 > 'localize twilight flare_mag_night' \
 > 'set twilight -1.8 flare_mag_night -1' \
 > 'flare "$@"'
 satpass2>

Note the use of single quotes rather than double quotes to enclose the
C<flare> command. In double quotes, or outside quotes altogether, the
C<$> is magical, and introduces something to be interpolated into the
command. Exactly what is interpolated depends on what follows the C<$>.
The C<$@> is replaced by the arguments of the command macro (or
whatever), but we do not want this to happen until the command macro is
expanded. Enclosing the C<$@> in double quotes ensures that macro
arguments containing spaces remain single arguments; without the double
quotes they would become multiple arguments.

So if you say