view release on metacpan or  search on metacpan

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

is used. If the back end does not begin with C<'DateTime::Calendar::'>,
C<'Gregorian'> is used.

Formatting Julian calendar dates in
L<Astro::App::Satpass2::FormatTime::DateTime::Cldr|Astro::App::Satpass2::FormatTime::DateTime::Cldr>
is unsupported, because
L<DateTime::Calendar::Christian|DateTime::Calendar::Christian> lacks the
C<format_cldr()> method. You may find that it works, because this module
patches in C<format_cldr()> when it loads
L<DateTime::Calendar::Christian|DateTime::Calendar::Christian> if it
finds that that method does not already exist. But you may find that it
does not work, because the patch messes with the internals of
L<DateTime::Calendar::Christian|DateTime::Calendar::Christian>, and
those might change without warning. I<Caveat coder.>

=head1 INTERMEDIATE TOPICS

This section covers things that are beyond just getting the application
up and running.

=head2 Time Zones

By default, times are reported in your local zone. Summer time/daylight
saving time is accounted for (unless the underlying Perl is broken),
even when predictions cross the boundary between standard and summer
time. But you may want some other zone. There are two cases here,
depending on what optional modules you have installed.

Without any optional modules, the only supported zone other than your
default local zone is GMT. You can get GMT output by

 satpass2> formatter gmt 1

The default ISO-8601-ish time parser does not have a corresponding
setting, but does allow you to append a C<'Z'> to the time to specify
GMT.

The default formatter object also has a C<tz> setting, but this is
unsupported because it relies on the C<TZ> environment variable, and the
author has no control over whether your OS' POSIX code supports this.
You can try it with something like

 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

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

(those set with a C<set> command) can be localized; attributes of helper
objects can not be. But you B<can> localize the entire helper object.
For example, for a temporary change to the
L<Astro::SpaceTrack|Astro::SpaceTrack> object,

 satpass2> localize spacetrack

inside the appropriate scope. Yes, you can localize outside a command
macro (or any other localization scope, such as inside a C<source> file
or a C<begin>-C<end> block), but it does no good to do so, because the
old value is not restored until you exit, and what good is that?

=head2 Reporting Position

By default, anything that reports a satellite position does it in
elevation, azimuth and range. You may want some other units, such as
right ascension and declination.

Deciding what to display is the job of the C<formatter> helper object.
Normally this is an
L<Astro::App::Satpass2::Format::Template|Astro::App::Satpass2::Format::Template>,
and for the full story you should see the documentation to that class.

But there are a number of prepackaged coordinate sets:

 az_rng --------- azimuth (with bearing) and range
 azel ----------- elevation and azimuth (with bearing)
 azel_rng ------- elevation, azimuth (with bearing) and range
 equatorial ----- right ascension and declination
 equatorial_rng - right ascension, declination and range

By default, you get C<azel_rng>, but you can get any of the others via
the L<local_coord()|Astro::App::Satpass2::Format/local_coord>
method of the formatter object. For example, if you want right
ascension, declination and range, just

 satpass2> formatter local_coord equatorial_rng

=head2 User-defined Position Coordinates

L<Astro::App::Satpass2::Format::Template|Astro::App::Satpass2::Format::Template>
defines these local coordinates in terms of L<Template-Toolkit|Template>
templates, so you can add definitions, or change the existing
definitions, in the same way that you would change one of the reporting
templates, using that formatter's
L<template()|Astro::App::Satpass2::Format::Template/template> method.
For example, to make C<azel> report azimuth first,

 satpass2> formatter template azel <<'EOD'
 > [% data.azimuth( bearing = 2 ) %]
 >     [%= data.elevation %]
 > EOD

See the
L<Astro::App::Satpass2::FormatValue|Astro::App::Satpass2::FormatValue>
documentation for what format effectors are available. Inside the
template, the C<data> object will contain the data you want to format.

=head1 ADVANCED TOPICS

=head2 Code Macros

In addition to L<Command Macros|/Command Macros>, a macro can be defined
using Perl code. This allows one to add new functionality to
C<Astro::App::Satpass2>, over and above that provided by interactive
methods.

Code macros are currently unsupported, though it might be better to call
them experimental. The real situation is that I have been looking for
ways to plug bits of code into the system, and handling them like macros
seemed to be the best way. So I knocked something together along those
lines, and played with it. Further experience may show that the
interface or the implementation was ill-chosen, or even that there is
something deeply flawed about the whole idea. The bottom line is that if
you want this to become supported, you should tell me what you like or
do not like about it.

In order to implement code macros, a number of previously-private
methods of L<Astro::App::Satpass2|Astro::App::Satpass2> have been
exposed. The names of these begin with a double underscore (C<__>), and
these are documented as unsupported. These will not go away even if code
macros do, but their calling sequences may change. On the other hand, if
code macros become fully supported, these will too.

A code macro is simply a Perl subroutine which is called by
C<Astro::App::Satpass2> more or less as though it were an interactive
method. In the following discussion, some words are used with particular
meanings:

=over

=item must

means that the code macro will not work unless this is done;

=item should

means that the code macro will work without doing this, but you might
not like the results;

=item may

means that the code macro will work without doing this, but you might
want the functionality described.

=back

Now, Perl subroutines do not live in a vacuum. They in fact live in Perl
modules; that is, F<.pm> files defining a C<package> whose name reflects
the path name of the file. A module that defines a code macro can be
installed like a normal Perl module, but can also live in the F<lib/>
directory in the user's C<Astro::App::Satpass2> configuration directory
(which is the default for C<< $satpass2->macro( load => ... ) >>), or
anywhere if you specify the location via the C<lib> option (e.g.
C<< $satpass2->macro( load => { lib => something }, ... >>).

In addition to the things that go into making a Perl module, a module
that provides code macros:

=over

=item must be a subclass of C<Astro::App::Satpass2>;