view release on metacpan or  search on metacpan

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

Obviously a flare that would be fairly bright at night might be
completely invisible during the day, so day and night have separate
settings to control the minimum reportable brightness.
C<Astro::App::Satpass2> uses the C<flare_mag_day> setting to determine
the dimmest reportable flare during the day; this defaults to C<-6>. The
dimmest reportable flare at night is determined by the
C<flare_mag_night> setting, which defaults to C<0>.

In order to duplicate (fairly closely) the Iridium flares reported by
L<https://www.heavens-above.com/>, you will want to tweak
C<Astro::App::Satpass2>'s settings a bit:

 satpass2> set twilight -1.8 flare_mag_night -1

seems to come fairly close.

=head1 OTHER CUSTOMIZATIONS

There are other customizations of the output that you may want.

=head2 Location

If you want to display your location, just issue the

 satpass2> location

command. The output of this can be directed to a file, just as the
output of any other command. For a nice list of passes and flares for
your refrigerator door, you can do something like this:

 satpass2> location >this_week.txt
 satpass2> spacetrack spaceflight -all -effective
 satpass2> pass >>this_week.txt
 satpass2> spacetrack celestrak iridium
 satpass2> flare -pm >>this_week.txt
 satpass2> exit

=head2 Date and Time Format

By default, date and time are displayed in an ISO-8601-ish format. If
you want something friendlier, you can specify a C<strftime (3)> format
independently for the date and the time. These settings can be saved to
your initialization file just like any other setting.

The date and time format settings belong to the formatter object, which
is a separate subsystem all to itself. So:

 satpass2>
 satpass2> # Display the date as weekday day-month-year
 satpass2> formatter date_format '%a %d-%b-%Y'
 satpass2>
 satpass2> # Display the time as 1-12 AM or PM
 satpass2> formatter time_format '%I:%M:%S %p'
 satpass2>
 satpass2> # Save the configuration, overwriting any previous one
 satpass2> save -changes -overwrite

=head2 The Julian Calendar

No, there were no satellites in orbit when the last known holdout
(Romania) adopted the Gregorian calendar. But the Sun and Moon have been
rising and setting much longer than satellites have.

If you install
L<DateTime::Calendar::Christian|DateTime::Calendar::Christian> and
properly configure C<satpass2>, you will be able to both parse and
display dates in both the Gregorian and Julian calendars.

=head3 Parsing Julian Calendar Dates

The primary date parser is L<Date::Manip|Date::Manip>, which does not
support Julian dates. But if you use the C<ISO8601> parser, you can
configure it to parse a date as either Julian or Gregorian, depending on
the date itself.

What you have to do, in general, is use date parser
L<Astro::App::Satpass2::ParseTime::ISO8601>, and set its
L<back_end|Astro::App::Satpass2::Utils/back_end> attribute
to C<'DateTime::Calendar::Christian'>. You must, of course have this
module installed, and you can shorten the setting to just
C<'Christian'>.  You should see the documentation for full details, but
with the C<satpass2> script the configuration would look something like
this:

 satpass2> # Configure the ISO8601 parser, with back end
 satpass2> set time_parser ISO8601,back_end=Christian

The L<DateTime::Calendar::Christian|DateTime::Calendar::Christian>
module takes, as one of the arguments to C<new()>, a reform date, which
defaults to the date it was first adopted in Italy, on October 15 1582
(Gregorian). If you want something different you can append it to the
value of C<back_end> and quote the whole value. The quotes must be
either escaped or surrounded with outer quotes to protect them from the
command parser. For example, to set the UK reform date, use

 satpass2> set time_parser "ISO8601,back_end='Christian,reform_date=uk'"

=head3 Formatting Julian Calendar Dates

Here, you need to use the C<DateTime> date formatter, which will be the
default if the L<DateTime|DateTime> module is installed. Since
L<DateTime|DateTime> is a prerequisite for
L<DateTime::Calendar::Christian|DateTime::Calendar::Christian>,
installing this will make the proper date formatter the default. But
before you can actually get Julian output dates, you need to configure
the time formatter to use this class.  Because the date formatter is
managed by the formatter object, the C<satpass2> commands to configure
it are

 satpass2> # Configure the time formatter and reform date
 satpass2> formatter time_formatter \
 > DateTime::Strftime,back_end=Christian

A non-default reform date is specified the same way as for the parser,
and the two reform dates need not be the same.

The C<DateTime> C<strftime> formatter also supports, as a special case,
format pattern C<'%{calendar_name}'>, which renders as either
C<'Julian'> or C<'Gregorian'> as appropriate. Given

 satpass2> formatter time_format \
 > '%{year_with_era}-%m-%d %{calendar_name}'

The date of the assassination of Julius Caesar would be displayed as

 '44BC-03-15 Julian'

In point of fact, the way the C<%{calendar_name}> machinery works is
that if the back end provides the C<is_julian()> method, you get
C<'Julian'> if that method returns a true value, and C<'Gregorian'> if
it does not. If the back end does not provide the C<is_julian()> method,
whatever follows C<'DateTime::Calendar::'> in the back end's class name
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