blib/lib/Astro/App/Satpass2/Format.pm

filter: Statementstmt 90.8% 129 / 142 Branchbran 63.2% 43 / 68 Conditioncond 61.1% 11 / 18 MC/DCmcdc 33.3% 4 / 12 Subroutinesub 85.7% 24 / 28 Podpod 100% 9 / 9 totaltotal 79.4% 220 / 277 CC 40 SCAR 18.4
CC
40
Cov
80%
new
13.2
__ANON__
12.0
__ANON__
9.5
CRAP 6.3
« blib/lib/Astro/App/Satpass2/Copier.pm ↑ Summary blib/lib/Astro/App/Satpass2/ParseTime/Date/Manip.pm »
1 package Astro::App::Satpass2::Format;
2  
3 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 10 ▶use parent qw{ Astro::App::Satpass2::Copier };
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 10 ▶use Clone ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 10 ▶use Astro::App::Satpass2::FormatTime;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 10 ▶use Astro::App::Satpass2::Utils qw{
Subroutine BEGIN: called CC=1 SCAR=0.0
11 instance
12 load_package __parse_class_and_args
13 CODE_REF
14 @CARP_NOT
15 10 };
16 10 ▶use Scalar::Util 1.26 qw{ weaken };
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 10 our $VERSION = '0.059';
19  
20 10 ▶use constant DEFAULT_LOCAL_COORD => 'azel_rng';
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 # Note that the fact that new() works when called from
23 # My::Module::Test::App is unsupported and undocumented, and
24 # the functionality may be revoked or changed without warning.
25  
26 10 my %static = (
27 desired_equinox_dynamical => 0,
28 gmt => 0,
29 local_coord => DEFAULT_LOCAL_COORD,
30 provider => 'Astro::App::Satpass2',
31 value_formatter => 'Astro::App::Satpass2::FormatValue',
32 );
33  
34 12 ▶sub new {
Subroutine new: called CC=11 SCAR=25.8
Pod documented
35 12 my ( $class, %args ) = @_;
36 12 ▶ ref $class and $class = ref $class;
Branch: 1 branch
BranchTrueFalseTotal
ref $class and $class = ref $class 0 12 12
37  
38 12 my $self = { %static };
39 12 bless $self, $class;
40  
41 12 $self->warner( delete $args{warner} );
42  
43 12 ▶ $class eq __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$class eq __PACKAGE__ and "My::Module::Test::App" ne caller and $self->wail(__PACKAGE__, " may not be instantiated. Use a subclass") 0 12 12
Condition66%2/3
$class eq __PACKAGE__ and "My::Module::Test::App" ne caller
!ll&&!rl&&r
1110
MC/DC0%0/2
$class eq __PACKAGE__ and "My::Module::Test::App" ne caller
$class eq __PACKAGE__ "My::Module::Test::App" ne caller
Truth table66%2/3
A and B
A= $class eq __PACKAGE__B= "My::Module::Test::App" ne caller
ABresult
0X0
100
111
44 and 'My::Module::Test::App' ne caller
45 and $self->wail( __PACKAGE__,
46 ' may not be instantiated. Use a subclass' );
47  
48 12 $self->{parent} = delete $args{parent};
49  
50 # FIXME the below is verbatim from
51 # Astro::App::Satpass2::Macro->init(), ca. line 63.
52 defined $self->{parent}
53 12 ▶ or $self->wail( q{Attribute 'parent' is required} );
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"parent"} or $self->wail("Attribute 'parent' is required") 12 0 12
54 12 ▶ instance( $self->{parent}, 'Astro::App::Satpass2' )
Branch: 1 branch
BranchTrueFalseTotal
instance($self->{"parent"}, "Astro::App::Satpass2") or $self->wail("Attribute 'parent' must be an Astro::App::Satpass2") 12 0 12
55 or $self->wail( q{Attribute 'parent' must be an Astro::App::Satpass2} );
56 12 weaken( $self->{parent} );
57  
58 12 ▶ exists $args{tz} or $args{tz} = $ENV{TZ};
Branch: 1 branch
BranchTrueFalseTotal
exists $args{"tz"} or $args{"tz"} = $ENV{"TZ"} 0 12 12
59  
60 12 $self->time_formatter( delete $args{time_formatter} );
61 12 $self->time_formatter()->warner( $self->warner() );
62  
63 $args{date_format}
64 12 ▶ or $self->date_format( $self->time_formatter()->DATE_FORMAT() );
Branch: 1 branch
BranchTrueFalseTotal
$args{"date_format"} or $self->date_format($self->time_formatter->DATE_FORMAT) 0 12 12
65 $args{time_format}
66 12 ▶ or $self->time_format( $self->time_formatter()->TIME_FORMAT() );
Branch: 1 branch
BranchTrueFalseTotal
$args{"time_format"} or $self->time_format($self->time_formatter->TIME_FORMAT) 0 12 12
67 exists $args{round_time}
68 12 ▶ or $self->round_time( $self->time_formatter()->ROUND_TIME() );
Branch: 1 branch
BranchTrueFalseTotal
exists $args{"round_time"} or $self->round_time($self->time_formatter->ROUND_TIME) 0 12 12
69  
70 $self->value_formatter( delete $args{value_formatter} ||
71 12 ▶ $static{value_formatter} );
Condition33%1/3
delete $args{'value_formatter'} || $static{'value_formatter'}
l!l&&r!l&&!r
0120
MC/DC0%0/2
delete $args{'value_formatter'} || $static{'value_formatter'}
delete $args{'value_formatter'} $static{'value_formatter'}
Truth table33%1/3
A || B
A= delete $args{'value_formatter'}B= $static{'value_formatter'}
ABresult
1X1
011
000
72 12 $self->value_formatter()->warner( $self->warner() );
73  
74 12 $self->init( %args );
75  
76 12 return $self;
77 }
78  
79 463 ▶sub round_time {
Subroutine round_time: called CC=2 SCAR=6.9
Pod documented
80 463 my ( $self, @arg ) = @_;
81 463 ▶ if ( @arg ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@arg) { } 12 451 463
82 12 $self->time_formatter()->round_time( @arg );
83 12 $self->{round_time} = $arg[0];
84 12 return $self;
85 } else {
86 451 return $self->time_formatter()->round_time();
87 }
88 }
89  
90 32 ▶sub attribute_names {
Subroutine attribute_names: called CC=1 SCAR=0.0
Pod documented
91 32 my ( $self ) = @_;
92 32 return ( $self->SUPER::attribute_names(),
93 qw{ date_format desired_equinox_dynamical gmt
94 local_coord parent provider round_time
95 time_format time_formatter tz
96 value_formatter
97 } );
98 }
99  
100 {
101  
102 my %original_value = (
103 1 ▶ date_format => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
104 1 return $_[0]->time_formatter()->DATE_FORMAT()
105 },
106 1 ▶ round_time => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
107 1 return $_[0]->time_formatter()->ROUND_TIME()
108 },
109 1 ▶ time_format => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
110 1 return $_[0]->time_formatter()->TIME_FORMAT()
111 },
112 10 );
113  
114 10 foreach my $key ( keys %static ) {
115 5 ▶ $original_value{ $key } ||= sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
116 5 return $static{$key};
117 50 ▶ };
Condition33%1/3
$original_value{$key} ||= sub { return $static{$key}; }
l!l&&r!l&&!r
0500
MC/DC0%0/2
$original_value{$key} ||= sub { return $static{$key}; }
$original_value{$key} sub { return $static{$key}; }
Truth table33%1/3
A ||= B
A= $original_value{$key}B= sub { return $static{$key}; }
ABresult
1X1
011
000
118 }
119  
120 10 my %not_part_of_config = map { $_ => 1 } qw{ parent warner };
121  
122 2 ▶ sub config {
Subroutine config: called CC=9 SCAR=22.0
Pod documented
123 2 my ( $self, %args ) = @_;
124 2 my @data;
125  
126 2 foreach my $name ( $self->attribute_names() ) {
127  
128 24 ▶ $not_part_of_config{$name}
Branch: 1 branch
BranchTrueFalseTotal
$not_part_of_config{$name} and next 4 20 24
129 and next;
130  
131 20 my $val = $self->$name();
132 $args{decode}
133 20 ▶ and ref $val
Branch: 1 branch
BranchTrueFalseTotal
$args{"decode"} and ref $val and $val = $self->decode($name) 4 16 20
Condition66%2/3
$args{"decode"} and ref $val
!ll&&!rl&&r
0164
MC/DC50%1/2
$args{"decode"} and ref $val
$args{"decode"} ref $val
Truth table66%2/3
A and B
A= $args{"decode"}B= ref $val
ABresult
0X0
100
111
134 and $val = $self->decode( $name );
135  
136 10 ▶ no warnings qw{ uninitialized };
Subroutine BEGIN: called CC=1 SCAR=0.0
137  
138 next if $args{changes} &&
139 $val eq ( $original_value{$name} ?
140 20 ▶ $original_value{$name}->( $self, $name ) :
Branch: 2 branches
BranchTrueFalseTotal
if $args{"changes"} and $val eq ($original_value{$name} ? $original_value{$name}->($self, $name) : undef) 6 14 20
$original_value{$name} ? : 8 2 10
Condition100%3/3
$args{"changes"} and $val eq ($original_value{$name} ? $original_value{$name}->($self, $name) : undef)
!ll&&!rl&&r
1046
MC/DC100%2/2
$args{"changes"} and $val eq ($original_value{$name} ? $original_value{$name}->($self, $name) : undef)
$args{"changes"} $val eq ($original_value{$name} ? $original_value{$name}->($self, $name) : undef)
Truth table100%3/3
A and B
A= $args{"changes"}B= $val eq ($original_value{$name} ? $original_value{$name}->($self, $name) : undef)
ABresult
0X0
100
111
141 undef );
142  
143 14 push @data, [ $name, $val ];
144 }
145  
146 2 ▶ return wantarray ? @data : \@data;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 2 2
147 }
148  
149 }
150  
151 {
152  
153 10 my %decoder = (
154 0 ▶ desired_equinox_dynamical => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
155 0 my ( $self, $method, @args ) = @_;
156 0 my $rslt = $self->$method( @args );
157 0 ▶ @args and return $rslt;
Branch: 1 branch
BranchTrueFalseTotal
@args and return $rslt 0 0 0
158 0 ▶ $rslt or return $rslt;
Branch: 1 branch
BranchTrueFalseTotal
$rslt or return $rslt 0 0 0
159 return $self->{time_formatter}->format_datetime(
160 0 $self->{time_formatter}->ISO_8601_FORMAT(),
161 $rslt, 1 );
162 },
163 4 ▶ time_formatter => sub {
Subroutine __ANON__: called CC=2 SCAR=7.0
164 4 my ( $self, $method, @args ) = @_;
165 4 my $rslt = $self->$method( @args );
166 4 ▶ @args and return $rslt;
Branch: 1 branch
BranchTrueFalseTotal
@args and return $rslt 0 4 4
167 # return ref $rslt || $rslt;
168 4 return $rslt->class_name_of_record();
169 },
170 10 );
171 10 $decoder{value_formatter} = $decoder{time_formatter};
172  
173 11 ▶ sub decode {
Subroutine decode: called CC=4 SCAR=14.1
Pod documented
174 11 my ( $self, $method, @args ) = @_;
175 11 ▶ my $dcdr = $decoder{$method}
Branch: 1 branch
BranchTrueFalseTotal
my $dcdr = $decoder{$method} or return $self->$method(@args) 4 7 11
176 or return $self->$method( @args );
177 4 ▶ my $type = ref $dcdr
Branch: 1 branch
BranchTrueFalseTotal
my $type = ref $dcdr or $self->weep("Decoder for $method is scalar") 4 0 4
178 or $self->weep( "Decoder for $method is scalar" );
179 4 ▶ CODE_REF eq $type
Branch: 1 branch
BranchTrueFalseTotal
"CODE" eq $type or $self->weep("Decoder for $method is $type reference") 4 0 4
180 or $self->weep(
181 "Decoder for $method is $type reference" );
182 4 return $dcdr->( $self, $method, @args );
183 }
184 }
185  
186 10 ▶sub format : method { ## no critic (ProhibitBuiltInHomonyms,RequireFinalReturn)
Subroutine format: not called CC=1 SCAR=2.6
Pod documented
187 0 my ( $self ) = @_;
188 # ->weep() throws an exception.
189 0 $self->weep(
190 'The format() method must be overridden' );
191 }
192  
193 210 ▶sub local_coord {
Subroutine local_coord: called CC=3 SCAR=11.0
Pod documented
194 210 my ( $self, @args ) = @_;
195 210 ▶ if ( @args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args) { } 12 198 210
196 12 ▶ defined $args[0] or $args[0] = DEFAULT_LOCAL_COORD;
Branch: 1 branch
BranchTrueFalseTotal
defined $args[0] or $args[0] = "azel_rng" 10 2 12
197 12 $self->{local_coord} = $args[0];
198 12 return $self;
199 } else {
200 198 return $self->{local_coord};
201 }
202 }
203  
204 10 foreach my $attribute (
205 [ time_formatter => 'Astro::App::Satpass2::FormatTime',
206 0 ▶ 'Astro::App::Satpass2::FormatTime', sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
207 0 my ( $self, $old, $new ) = @_;
208 0 ▶ if ( $old->FORMAT_TYPE() ne $new->FORMAT_TYPE() ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($old->FORMAT_TYPE ne $new->FORMAT_TYPE) 0 0 0
209 0 $self->date_format( $new->DATE_FORMAT() );
210 0 $self->time_format( $new->TIME_FORMAT() );
211 }
212 0 return;
213 },
214 ],
215 [ value_formatter => 'Astro::App::Satpass2::FormatValue',
216 0 ▶ 'Astro::App::Satpass2', sub {} ],
Subroutine __ANON__: not called CC=1 SCAR=0.0
217 ) {
218 20 my ( $name, $class, $prefix, $pre_set ) = @{ $attribute };
219 20 ▶ __PACKAGE__->can( $name )
Branch: 1 branch
BranchTrueFalseTotal
__PACKAGE__->can($name) and next 0 20 20
220 and next;
221 10 ▶ no strict qw{ refs };
Subroutine BEGIN: called CC=1 SCAR=0.0
222 1548 ▶ *$name = sub {
Subroutine __ANON__: called CC=9 SCAR=22.5
223 1548 my ( $self, @args ) = @_;
224 1548 ▶ if ( @args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args) { } 24 1524 1548
225 24 my $fmtr = shift @args;
226 24 ▶ defined $fmtr and $fmtr ne ''
Branch: 1 branch
BranchTrueFalseTotal
defined $fmtr and $fmtr ne "" or $fmtr = $class 12 12 24
Condition66%2/3
defined $fmtr and $fmtr ne ""
!ll&&!rl&&r
12012
MC/DC50%1/2
defined $fmtr and $fmtr ne ""
defined $fmtr $fmtr ne ""
Truth table66%2/3
A and B
A= defined $fmtrB= $fmtr ne ""
ABresult
0X0
100
111
227 or $fmtr = $class;
228 24 my $old = $self->{$name};
229 24 ▶ ref $fmtr or do {
Branch: 1 branch
BranchTrueFalseTotal
ref $fmtr or do { () = ($self->__parse_class_and_args($fmtr), @args); my $fatal = $self->parent->get("error_out") ? "wail" : "whinge"; my $class = $self->load_package({"fatal", $fatal}, $pkg, $prefix) or return $self; $fmtr = $class->new("warner", scalar $self->warner, @fmtr_arg); ref $old and $old->copy($fmtr, @fmtr_arg) } 0 24 24
230 24 my ( $pkg, @fmtr_arg ) = (
231 $self->__parse_class_and_args( $fmtr ), @args );
232 24 ▶ my $fatal = $self->parent()->get( 'error_out' ) ?
Branch: 1 branch
BranchTrueFalseTotal
$self->parent->get('error_out') ? : 0 24 24
233 'wail' : 'whinge';
234 24 ▶ my $class = $self->load_package(
Branch: 1 branch
BranchTrueFalseTotal
my $class = $self->load_package({"fatal", $fatal}, $pkg, $prefix) or return $self 24 0 24
235 { fatal => $fatal }, $pkg, $prefix )
236 or return $self;
237 24 $fmtr = $class->new(
238 warner => scalar $self->warner(),
239 @fmtr_arg,
240 );
241 24 ▶ ref $old
Branch: 1 branch
BranchTrueFalseTotal
ref $old and $old->copy($fmtr, @fmtr_arg) 0 24 24
242 and $old->copy( $fmtr, @fmtr_arg );
243 };
244 24 ▶ ref $old
Branch: 1 branch
BranchTrueFalseTotal
ref $old and &$pre_set($self, $old, $fmtr) 0 24 24
245 and $pre_set->( $self, $old, $fmtr );
246 24 $self->{$name} = $fmtr;
247 24 return $self;
248 } else {
249 1524 return $self->{$name};
250 }
251 20 };
252 }
253  
254 24 ▶sub tz {
Subroutine tz: called CC=2 SCAR=6.9
Pod documented
255 24 my ( $self, @args ) = @_;
256 24 ▶ if ( @args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args) { } 20 4 24
257 20 $self->{tz} = $args[0];
258 20 return $self;
259 } else {
260 4 return $self->{tz};
261 }
262 }
263  
264 510 ▶sub warner {
Subroutine warner: called CC=3 SCAR=11.2
Pod documented
265 510 my ( $self, @args ) = @_;
266 510 ▶ if ( @args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args) 12 498 510
267 12 my $warner = $args[0];
268 12 ▶ if ( my $fmtr = $self->time_formatter() ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $fmtr = $self->time_formatter) 0 12 12
269 0 $fmtr->warner( $warner );
270 }
271 }
272 510 return $self->SUPER::warner( @args );
273 }
274  
275 10 __PACKAGE__->create_attribute_methods();
276  
277 10 1;
278  
279 =head1 NAME
280  
281 Astro::App::Satpass2::Format - Format Astro::App::Satpass2 output
282  
283 =head1 SYNOPSIS
284  
285 No user-serviceable parts inside.
286  
287 =head1 DETAILS
288  
289 This formatter is an abstract class providing output formatting
290 functionality for L<Astro::App::Satpass2|Astro::App::Satpass2>. It
291 should not be instantiated directly.
292  
293 This class is a subclass of
294 L<Astro::App::Satpass2::Copier|Astro::App::Satpass2::Copier>.
295  
296 =head1 METHODS
297  
298 This class supports the following public methods:
299  
300 =head2 Instantiator
301  
302 =head3 new
303  
304 $fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(...);
305  
306 This method instantiates a formatter. It may not be called on this
307 class, but may be called on a subclass. If you wish to modify the
308 default attribute values you can pass the relevant name/value pairs as
309 arguments. For example:
310  
311 $fmt = Astro::Satpass::Format::Some_Subclass_Thereof->new(
312 date_format => '%Y%m%d',
313 time_format => 'T%H:%M:%S',
314 );
315  
316 =head2 Accessors and Mutators
317  
318 =head3 date_format
319  
320 print 'Date format: ', $fmt->date_format(), "\n";
321 $fmt->date_format( '%d-%b-%Y' );
322  
323 The C<date_format> attribute is maintained on behalf of subclasses of
324 this class, which B<may> (but need not) use it to format dates. This
325 method B<may> be overridden by subclasses, but the override B<must> call
326 C<SUPER::date_format>, and return values consistent with the following
327 description.
328  
329 This method acts as both accessor and mutator for the C<date_format>
330 attribute. Without arguments it is an accessor, returning the current
331 value of the C<date_format> attribute.
332  
333 If passed an argument, that argument becomes the new value of
334 C<date_format>, and the object itself is returned so that calls may be
335 chained.
336  
337 The interpretation of the argument is up to the subclass, but
338 it is recommended for sanity's sake that the subclasses interpret this
339 value as a C<POSIX::strftime> format producing a date (but not a time),
340 if they use this attribute at all.
341  
342 The default value, if used by the subclass at all, should produce a
343 numeric date of the form year-month-day. For formatters that use
344 C<strftime()>, this will be '%Y-%m-%d'.
345  
346 B<Note> that this value will be reset to its default if the
347 L<time_formatter|/time_formatter> attribute is modified and the new
348 object has a different C<FORMATTER_TYPE()> than the old one.
349  
350 =head3 desired_equinox_dynamical
351  
352 print 'Desired equinox: ',
353 strftime( '%d-%b-%Y %H:%M:%S dynamical',
354 gmtime $fmt->desired_equinox_dynamical() ),
355 "\n";
356 $fmt->desired_equinox_dynamical(
357 timegm( 0, 0, 12, 1, 0, 100 ) ); # J2000.0
358  
359 The C<desired_equinox_dynamical> attribute is maintained on behalf of
360 subclasses of this class, which B<may> (but need not) use it to
361 calculate inertial coordinates. If the subclass does not make use of
362 this attribute it B<must> document the fact.
363  
364 This method B<may> be overridden by subclasses, but the override B<must>
365 call C<SUPER::desired_equinox_dynamical>, and return values consistent
366 with the following description.
367  
368 This method acts as both accessor and mutator for the
369 C<desired_equinox_dynamical> attribute. Without arguments it is an
370 accessor, returning the current value of the
371 C<desired_equinox_dynamical> attribute.
372  
373 If passed an argument, that argument becomes the new value of
374 C<desired_equinox_dynamical>, and the object itself is returned so that
375 calls may be chained.
376  
377 The interpretation of the argument is up to the subclass, but it is
378 recommended for sanity's sake that the subclasses interpret this value
379 as a dynamical time (even though it is represented as a normal Perl
380 time) if they use this attribute at all. If the value is true (in the
381 Perl sense) inertial coordinates should be precessed to the dynamical
382 time represented by this attribute. If the value is false (in the Perl
383 sense) they should not be precessed.
384  
385 =head3 gmt
386  
387 print 'Time zone: ', ( $fmt->gmt() ? 'GMT' : 'local' ), "\n";
388 $fmt->gmt( 1 );
389  
390 The C<gmt> attribute is maintained on behalf of subclasses of this
391 class, which B<may> (but need not) use it to decide whether to display
392 dates in GMT or in the local time zone. This method B<may> be overridden
393 by subclasses, but the override B<must> call C<SUPER::gmt>, and return
394 values consistent with the following description.
395  
396 This method acts as both accessor and mutator for the C<gmt>
397 attribute. Without arguments it is an accessor, returning the current
398 value of the C<gmt> attribute. This value is to be interpreted as a
399 Boolean under the usual Perl rules.
400  
401 If passed an argument, that argument becomes the new value of
402 C<gmt>, and the object itself is returned so that calls may be
403 chained.
404  
405 =head3 local_coord
406  
407 print 'Local coord: ', $fmt->local_coord(), "\n";
408 $fmt->local_coord( 'azel_rng' );
409  
410 The C<local_coord> attribute is maintained on behalf of subclasses of
411 this class, which B<may> (but need not) use it to determine what
412 coordinates to display. This method B<may> be overridden by subclasses,
413 but the override B<must> call C<SUPER::local_coord>, and return values
414 consistent with the following description.
415  
416 This method acts as both accessor and mutator for the C<local_coord>
417 attribute. Without arguments it is an accessor, returning the current
418 value of the C<local_coord> attribute.
419  
420 If passed an argument, that argument becomes the new value of
421 C<local_coord>, and the object itself is returned so that calls may be
422 chained. The interpretation of the argument is up to the subclass, but
423 it is recommended for sanity's sake that the subclasses support at least
424 the following values if they use this attribute at all:
425  
426 az_rng --------- azimuth and range;
427 azel ----------- azimuth and elevation;
428 azel_rng ------- azimuth, elevation and range;
429 equatorial ----- right ascension and declination;
430 equatorial_rng - right ascension, declination and range.
431  
432 It is further recommended that C<azel_rng> be the default.
433  
434 =head3 provider
435  
436 print 'Provider: ', $fmt->provider(), "\n";
437 $fmt->provider( 'Astro::App::Satpass2 v' . Astro::App::Satpass2->VERSION() );
438  
439 The C<provider> attribute is maintained on behalf of subclasses of this
440 class, which B<may> (but need not) use it to identify the provider of
441 the data for informational purposes. This method B<may> be overridden by
442 subclasses, but the override B<must> call C<SUPER::provider>, and return
443 values consistent with the following description.
444  
445 This method acts as both accessor and mutator for the C<provider>
446 attribute. Without arguments it is an accessor, returning the current
447 value of the C<provider> attribute.
448  
449 If passed an argument, that argument becomes the new value of
450 C<provider>, and the object itself is returned so that calls may be
451 chained.
452  
453 =head3 round_time
454  
455 print 'Time rounded to: ', $fmt->round_time(), " seconds\n";
456 $fmt->round_time( 60 );
457  
458 The C<round_time> attribute is maintained on behalf of subclasses of
459 this class, which B<may> (but need not) use it to format times. This
460 method B<may> be overridden by subclasses, but the override B<must> call
461 C<SUPER::round_time>, and return values consistent with the following
462 description.
463  
464 This method acts as both accessor and mutator for the C<round_time>
465 attribute. Without arguments it is an accessor, returning the current
466 value of the C<round_time> attribute.
467  
468 If passed an argument, that argument becomes the new value of
469 C<round_time>, and the object itself is returned so that calls may be
470 chained.
471  
472 The interpretation of the argument is up to the subclass, but
473 it is recommended for sanity's sake that the subclasses interpret this
474 value in the same way as
475 L<Astro::App::Satpass2::FormatTime|Astro::App::Satpass2::FormatTime>
476 if they use this attribute at all.
477  
478 =head3 time_format
479  
480 print 'Time format: ', $fmt->time_format(), "\n";
481 $fmt->time_format( '%H:%M:%S' );
482  
483 The C<time_format> attribute is maintained on behalf of subclasses of
484 this class, which B<may> (but need not) use it to format times. This
485 method B<may> be overridden by subclasses, but the override B<must> call
486 C<SUPER::time_format>, and return values consistent with the following
487 description.
488  
489 This method acts as both accessor and mutator for the C<time_format>
490 attribute. Without arguments it is an accessor, returning the current
491 value of the C<time_format> attribute.
492  
493 If passed an argument, that argument becomes the new value of
494 C<time_format>, and the object itself is returned so that calls may be
495 chained.
496  
497 The interpretation of the argument is up to the subclass, but
498 it is recommended for sanity's sake that the subclasses interpret this
499 value as a C<POSIX::strftime> format producing a time (but not a date),
500 if they use this attribute at all.
501  
502 The default value, if used by the subclass at all, should produce a
503 numeric time of the form hour:minute:second. For formatters that use
504 C<strftime()>, this will be '%H:%M:%S'.
505  
506 B<Note> that this value will be reset to its default if the
507 L<time_formatter|/time_formatter> attribute is modified and the new
508 object has a different C<FORMATTER_TYPE()> than the old one.
509  
510 =head3 time_formatter
511  
512 This method acts as both accessor and mutator for the object used to
513 format times. It will probably be a
514 L<Astro::App::Satpass2::FormatTime|Astro::App::Satpass2::FormatTime>
515 object of some sort, and will certainly conform to that interface. When
516 setting the value, you can specify either a class name or an object. If
517 a class name, the leading C<Astro::App::Satpass2::FormatTime::> can be
518 omitted.
519  
520 B<Note> that setting this will reset the L<date_format|/date_format> and
521 L<time_format|/time_format> attributes to values appropriate to the
522 new time formatter's class, if the new formatter object has a different
523 C<FORMATTER_TYPE()> than the old one.
524  
525 =head3 tz
526  
527 print 'Time zone: ', $fmt->tz()->name(), "\n";
528 $fmt->tz( 'MST7MDT' );
529  
530 The C<tz> attribute is maintained on behalf of subclasses of this class,
531 which B<may> (but need not) use it to format times. This method B<may>
532 be overridden by subclasses, but the override B<must> call C<SUPER::tz>,
533 and return values consistent with the following description.
534  
535 This method acts as both accessor and mutator for the C<tz> attribute.
536 Without arguments it is an accessor, returning the current value of the
537 C<tz> attribute.
538  
539 If passed an argument, that argument becomes the new value of C<tz>, and
540 the object itself is returned so that calls may be chained.
541  
542 The use of the argument is up to the subclass, but it is
543 recommended for sanity's sake that the subclasses interpret this value
544 as a time zone to be used to derive the local time if they use this
545 attribute at all.
546  
547 A complication is that subclasses may need to validate zone values. It
548 is to be hoped that their digestions will be rugged enough to handle the
549 usual conventions, since convention rather than standard seems to rule
550 here.
551  
552 =head3 value_formatter
553  
554 This method acts as both accessor and mutator for the object used to
555 format values. It will probably be a
556 L<Astro::App::Satpass2::FormatValue|Astro::App::Satpass2::FormatValue>
557 object of some sort, and will certainly conform to that interface. When
558 setting the value, you can specify either a class name or an object. If
559 a class name, the leading C<Astro::App::Satpass2::> can be omitted.
560  
561 Author's note:
562  
563 This method is B<experimental and unsupported>. Documentation is for the
564 benefit of the author and the curious. I wanted to screw around with
565 extra formatters, and the best way to do that seemed to be to subclass
566 C<Astro::App::Satpass2::FormatValue>, but then I needed a way to put the
567 subclass into use. But I am not really ready to document the necessary
568 interface (and therefore commit to not changing it, or at least not
569 doing so without going through a deprecation cycle). If you have a need
570 for this kind of thing, please contact me.
571  
572 =head2 Formatters
573  
574 There is actually only one formatter method. The subclass B<must>
575 provide it, because this class does not.
576  
577 =head3 format
578  
579 print $fmt->format( template => $name, data => $data );
580  
581 This method takes named arguments.
582  
583 The only required argument is C<template>, which specifies what kind of
584 data are expected, and how it is to be formatted. These are described
585 below. The name of the C<template> argument assumes an implementation in
586 terms of some sort of templating system, but a subclass can implement
587 formatting in any way it pleases.
588  
589 The C<data> argument is normally required, and must be the data expected
590 by the specified C<template>. However, B<if> the formatter supports it,
591 the C<sp> argument can be specified in lieu of C<data>. The C<sp>
592 argument should be an L<Astro::App::Satpass2|Astro::App::Satpass2>
593 object, and it only does anything if the specific formatter is capable
594 of handling it.
595  
596 The supported template names, and the data required by each, are as
597 follows:
598  
599 =over
600  
601 =item almanac
602  
603 The C<$data> argument is expected to be a reference to an array of hash
604 references, which are presumed to be output from the C<almanac_hash()>
605 method of such L<Astro::Coord::ECI|Astro::Coord::ECI> subclasses that
606 have such a method.
607  
608 =item flare
609  
610 The C<$data> argument is expected to be a reference to an array of hash
611 references, which are presumed to be output from the
612 L<Astro::Coord::ECI::TLE::Iridium|Astro::Coord::ECI::TLE::Iridium>
613 C<flare()> method.
614  
615 =item list
616  
617 The C<$data> argument is expected to be a reference to an array of
618 L<Astro::Coord::ECI|Astro::Coord::ECI> or
619 L<Astro::Coord::ECI::TLE::Set|Astro::Coord::ECI::TLE::Set> objects. The
620 description generated by this method should be appropriate for a
621 satellite.
622  
623 =item location
624  
625 The C<$data> argument is expected to be an
626 L<Astro::Coord::ECI|Astro::Coord::ECI> object. This description should
627 be appropriate for a ground station.
628  
629 =item pass
630  
631 The C<$data> argument is expected to be a reference to an array of hash
632 references, which are presumed to be output from the
633 L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> C<pass()> method.
634  
635 =item pass_events
636  
637 The C<$data> argument is expected to be a reference to an array of hash
638 references, which are presumed to be output from the
639 L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> C<pass()> method.
640  
641 This template is expected to format a description of individual events
642 of satellite passes for the L<pass|Astro::App::Satpass2/pass> command
643 with the C<-events> option.
644  
645 =item phase
646  
647 The C<$data> argument is expected to be a reference to an array of
648 C<Astro::Coord::ECI|Astro::Coord::ECI> objects which support the
649 C<phase()> method and which have already had their time set to the
650 desired time.
651  
652 =item position
653  
654 This template is intended to format the position (and possibly other
655 data) of a set of bodies for the
656 L<position|Astro::App::Satpass2/position> command.
657  
658 The C<$data> argument is expected to be a hash containing relevant data.
659 The following hash keys are required:
660  
661 {bodies} - a reference to an array of bodies to report;
662 {station} - the observing station;
663 {time} - the time to be reported;
664  
665 Both C<{bodies}> and C<{station}> must contain
666 L<Astro::Coord::ECI|Astro::Coord::ECI> or
667 C<Astro::Coord::ECI::TLE::Set|Astro::Coord::ECI::TLE::Set> objects. The
668 bodies must already have had their times set to the desired time.
669  
670 In addition, the following keys are recommended:
671  
672 {questionable} - true to do flare calculations for questionable
673 sources;
674 {twilight} - twilight, in radians (negative).
675  
676 If the C<{twilight}> key is omitted, it will be set to civil twilight
677 (i.e. the radian equivalent of -6 degrees).
678  
679 Yes, this is more complex than the others, but the function is more
680 ad-hoc.
681  
682 =item tle
683  
684 The C<$data> argument is expected to be a reference to an array of
685 L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> objects. The output
686 should be compatible with the normal TLE format as documented at
687 L<http://celestrak.org>.
688  
689 =item tle_verbose
690  
691 The C<$data> argument is expected to be a reference to an array of
692 L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> objects. The output
693 should be an expanded output of the data in a TLE (say, one line per
694 datum, labeled and with units).
695  
696 =back
697  
698 =head2 Other Methods
699  
700 The following other methods are provided.
701  
702 =head3 config
703  
704 use YAML;
705 print Dump ( $pt->config( changes => 1 ) );
706  
707 This method retrieves the configuration of the formatter as an array of
708 array references. The first element of each array reference is a method
709 name, and the subsequent elements are arguments to that method. Calling
710 the given methods with the given arguments should reproduce the
711 configuration of the formatter. If called in scalar context, it returns
712 a reference to the array.
713  
714 There are two named arguments:
715  
716 =over
717  
718 =item changes
719  
720 If this boolean argument is true (in the Perl sense), only changes from
721 the default configuration are reported.
722  
723 =item decode
724  
725 If this boolean argument is true (in the Perl sense), the
726 L<decode()|/decode> method is used to obtain the configuration values.
727  
728 =back
729  
730 Subclasses that add other ways to configure the object B<must> override
731 this method. The override B<must> call C<SUPER::config()>, and include
732 the result in the returned data.
733  
734 =head2 decode
735  
736 $fmt->decode( 'desired_equinox_dynamical' );
737  
738 This method wraps other methods, converting their returned values to
739 human-readable. The arguments are the name of the method, and its
740 arguments if any. The return values of methods not explicitly documented
741 below are not modified.
742  
743 The following methods return something different when invoked via this
744 method:
745  
746 =over
747  
748 =item desired_equinox_dynamical
749  
750 If called as an accessor, the returned time is converted to an ISO-8601
751 time in the GMT zone. If called as a mutator, you still get back the
752 object reference.
753  
754 =item time_formatter
755  
756 If called as an accessor, the class name of the object being used to
757 format the time is returned. If called as a mutator, you still get back
758 the object reference.
759  
760 =back
761  
762 If a subclass overrides this method, the override should either perform
763 the decoding itself, or delegate to C<SUPER::decode>.
764  
765 =head1 SEE ALSO
766  
767 L<Astro::App::Satpass2|Astro::App::Satpass2>, which is the intended user of this
768 functionality.
769  
770 L<Astro::Coord::ECI|Astro::Coord::ECI> and associated modules, which are
771 the intended providers of data for this functionality.
772  
773 L<Astro::App::Satpass2::Format::Dump|Astro::App::Satpass2::Format::Dump>, which is a
774 subclass of this module. It is intended for debugging, and simply dumps
775 its arguments in Data::Dumper, JSON, or YAML format depending on how it
776 is configured and what modules are installed
777  
778 =head1 SUPPORT
779  
780 Support is by the author. Please file bug reports at
781 L<https://github.com/trwyant/perl-Astro-App-Satpass2/issues> or in
782 electronic mail to the author.
783  
784 =head1 AUTHOR
785  
786 Thomas R. Wyant, III F<harryfmudd at comcast dot net>
787  
788 =head1 COPYRIGHT AND LICENSE
789  
790 Copyright (C) 2010-2026 by Thomas R. Wyant, III
791  
792 This program is free software; you can redistribute it and/or modify it
793 under the same terms as Perl 5.10.0. For more details, see the full text
794 of the licenses in the files F<LICENSE-Artistic> and F<LICENSE-GPL>.
795  
796 This program is distributed in the hope that it will be useful, but
797 without any warranty; without even the implied warranty of
798 merchantability or fitness for a particular purpose.
799  
800 =cut
801  
802 __END__
« blib/lib/Astro/App/Satpass2/Copier.pm ↑ Summary blib/lib/Astro/App/Satpass2/ParseTime/Date/Manip.pm »