Framework/Feature/Pod.pm

filter: Statementstmt 96.9% 161 / 166 Branchbran 86.3% 57 / 66 Conditioncond 66.6% 6 / 9 MC/DCmcdc 50.0% 3 / 6 Subroutinesub 100% 14 / 14 Podpod 100% 9 / 9 totaltotal 92.5% 250 / 270 CC 41 SCAR 20.8
CC
41
Cov
93%
pod_options
13.0
get_synopsis
10.1
pod_args
8.0
CRAP 8.0
« Framework/Feature/Data.pm ↑ Summary Framework/Core.pm »
1 package App::Framework::Feature::Pod ;
2  
3 =head1 NAME
4  
5 App::Framework::Feature::Pod - Application documentation
6  
7 =head1 SYNOPSIS
8  
9 # Data feature is loaded by default as if the script contained:
10 use App::Framework '+Pod' ;
11  
12  
13 =head1 DESCRIPTION
14  
15 Used by the application framework to create pod-based man pages and help.
16  
17 =cut
18  
19 31 ▶use strict ;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 31 ▶use Carp ;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 31 our $VERSION = "1.002" ;
23  
24  
25 #============================================================================================
26 # USES
27 #============================================================================================
28 31 ▶use Pod::Usage ;
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 31 ▶use App::Framework::Feature ;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 31 ▶use App::Framework::Base ;
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 #============================================================================================
34 # OBJECT HIERARCHY
35 #============================================================================================
36 31 our @ISA = qw(App::Framework::Feature) ;
37  
38 #============================================================================================
39 # GLOBALS
40 #============================================================================================
41  
42 31 my $POD_HEAD = "=head" ;
43 31 my $POD_OVER = "=over" ;
44  
45  
46 31 my %FIELDS = (
47 ) ;
48  
49  
50 =head2 ADDITIONAL COMMAND LINE OPTIONS
51  
52 This feature adds the following additional command line options to any application:
53  
54 =over 4
55  
56 =item B<-help> - show help
57  
58 Displays brief help message then exits
59  
60 =item B<-man> - show full man pages
61  
62 Displays the application's full man pages then exits
63  
64 =item B<-man-dev> - show full developer man pages
65  
66 Displays the application's full developer man pages then exits. Developer man pages contain extra
67 information and is intended for the application developer (rather than the end user).
68  
69 =item B<-pod> - show man pages as pod [I<developer use>]
70  
71 Outputs the full pod text.
72  
73 =back
74  
75 =cut
76  
77  
78 31 my @OPTIONS = (
79 ['h|"help"', 'Print help', 'Show brief help message then exit'],
80 ['man', 'Full documentation', 'Show full man page then exit' ],
81 ['man-dev', 'Full developer\'s documentation', 'Show full man page for the application developer then exit' ],
82 ['dev:pod', 'Output full pod', 'Show full man page as pod then exit' ],
83 ) ;
84  
85  
86 #============================================================================================
87  
88 =head2 CONSTRUCTOR
89  
90 =over 4
91  
92 =cut
93  
94 #============================================================================================
95  
96  
97 =item B< new([%args]) >
98  
99 Create a new Pod.
100  
101 The %args are specified as they would be in the B<set> method (see L</Fields>).
102  
103 =cut
104  
105 sub new
106 31 ▶{
Subroutine new: called CC=2 SCAR=7.4
Pod documented
107 31 my ($obj, %args) = @_ ;
108  
109 31 ▶ my $class = ref($obj) || $obj ;
Condition33%1/3
ref $obj || $obj
l!l&&r!l&&!r
0310
MC/DC0%0/2
ref $obj || $obj
ref $obj $obj
Truth table33%1/3
A || B
A= ref $objB= $obj
ABresult
1X1
011
000
110  
111 # Create object
112 31 my $this = $class->SUPER::new(%args,
113 'feature_options' => \@OPTIONS,
114 'registered' => [qw/application_entry/],
115 ) ;
116  
117 #$this->debug(2);
118  
119
120 31 return($this) ;
121 }
122  
123  
124  
125 #============================================================================================
126  
127 =back
128  
129 =head2 CLASS METHODS
130  
131 =over 4
132  
133 =cut
134  
135 #============================================================================================
136  
137  
138 #-----------------------------------------------------------------------------
139  
140 =item B< init_class([%args]) >
141  
142 Initialises the Pod object class variables.
143  
144 =cut
145  
146 sub init_class
147 31 ▶{
Subroutine init_class: called CC=1 SCAR=0.0
Pod documented
148 31 my $class = shift ;
149 31 my (%args) = @_ ;
150  
151 # Add extra fields
152 31 $class->add_fields(\%FIELDS, \%args) ;
153  
154 # init class
155 31 $class->SUPER::init_class(%args) ;
156  
157 }
158  
159 #============================================================================================
160  
161 =back
162  
163 =head2 OBJECT METHODS
164  
165 =over 4
166  
167 =cut
168  
169 #============================================================================================
170  
171 #----------------------------------------------------------------------------
172  
173 =item B<application_entry()>
174  
175 Called by the application framework at the start of the application.
176
177 This method checks for the user specifying any of the options described above (see L</ADDITIONAL COMMAND LINE OPTIONS>) and handles
178 them if so.
179  
180 =cut
181  
182  
183 sub application_entry
184 41 ▶{
Subroutine application_entry: called CC=6 SCAR=18.3
Pod documented
185 41 my $this = shift ;
186  
187 41 $this->_dbg_prt(["application_entry()\n"]) ;
188  
189 ## Handle special options
190 41 my $app = $this->app ;
191 41 my %opts = $app->options() ;
192 41 $this->_dbg_prt(["pod options=",\%opts]) ;
193 41 ▶ if ($opts{'man'} || $opts{'help'})
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"man"} or $opts{"help"}) 1 40 41
Condition66%2/3
$opts{"man"} or $opts{"help"}
l!l&&r!l&&!r
0140
MC/DC50%1/2
$opts{"man"} or $opts{"help"}
$opts{"man"} $opts{"help"}
Truth table66%2/3
A or B
A= $opts{"man"}B= $opts{"help"}
ABresult
1X1
011
000
194 {
195 1 $this->_dbg_prt(["pod man page=$opts{'man'} \n"]) ;
196 1 ▶ my $type = $opts{'man'} ? 'man' : 'help' ;
Branch: 1 branch
BranchTrueFalseTotal
$opts{'man'} ? : 0 1 1
197 1 $app->usage($type) ;
198 1 $app->exit(0) ;
199 }
200 40 ▶ if ($opts{'man-dev'})
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"man-dev"}) 1 39 40
201 {
202 1 $app->usage('man-dev') ;
203 1 $app->exit(0) ;
204 }
205 39 ▶ if ($opts{'pod'})
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"pod"}) 0 39 39
206 {
207 0 print $this->pod() ;
208 0 $app->exit(0) ;
209 }
210
211 }
212  
213  
214 #----------------------------------------------------------------------------
215  
216 =item B<pod([$developer])>
217  
218 Return full pod of application
219  
220 If the optional $developer flag is set, returns application developer biased information
221  
222 =cut
223  
224 sub pod
225 8 ▶{
Subroutine pod: called CC=1 SCAR=0.0
Pod documented
226 8 my $this = shift ;
227 8 my ($developer) = @_ ;
228  
229 8 my $pod =
230 $this->pod_head($developer) .
231 $this->pod_args($developer) .
232 $this->pod_options($developer) .
233 $this->pod_description($developer) .
234 "\n=cut\n" ;
235 8 return $pod ;
236 }
237
238 #----------------------------------------------------------------------------
239  
240 =item B< Pod([%args]) >
241  
242 Alias to L</pod>
243  
244 =cut
245  
246 31 *Pod = \&pod ;
247  
248 #----------------------------------------------------------------------------
249  
250 =item B<pod_head([$developer])>
251  
252 Return pod heading of application
253  
254 If the optional $developer flag is set, returns application developer biased information
255  
256 =cut
257  
258 sub pod_head
259 8 ▶{
Subroutine pod_head: called CC=7 SCAR=19.5
Pod documented
260 8 my $this = shift ;
261 8 my ($developer) = @_ ;
262  
263 8 my $name = $this->app->name() ;
264 8 my $summary = $this->app->summary() ;
265 8 my $synopsis = $this->get_synopsis() ;
266 8 my $version = $this->app->version() ;
267  
268 8 my $pod =<<"POD_HEAD" ;
269  
270 ${POD_HEAD}1 NAME
271  
272 $name (v$version) - $summary
273  
274 ${POD_HEAD}1 SYNOPSIS
275  
276 $synopsis
277  
278 Options:
279  
280 POD_HEAD
281  
282 # Cycle through
283 8 my $names_aref = $this->app->feature('Options')->option_names() ;
284 8 foreach my $option_name (@$names_aref)
285 {
286 90 my $option_entry_href = $this->app->feature('Options')->option_entry($option_name) ;
287 90 my $default = "" ;
288 90 ▶ if ($option_entry_href->{'default'})
Branch: 1 branch
BranchTrueFalseTotal
if ($option_entry_href->{"default"}) 4 86 90
289 {
290 4 $default = "[Default: $option_entry_href->{'default'}]" ;
291 }
292  
293 90 my $multi = "" ;
294 90 ▶ if ($option_entry_href->{dest_type})
Branch: 1 branch
BranchTrueFalseTotal
if ($option_entry_href->{"dest_type"}) 4 86 90
295 {
296 4 $multi = "(option may be specified multiple times)" ;
297 }
298
299 90 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) { } 15 75 90
300 {
301 15 $pod .= sprintf " -%-20s $option_entry_href->{summary}\t$default\n", $option_entry_href->{'spec'} ;
302 }
303 else
304 {
305 # show option if it's not a devevloper option
306 $pod .= sprintf " -%-20s $option_entry_href->{summary}\t$default\t$multi\n", $option_entry_href->{'pod_spec'}
307 75 ▶ unless $option_entry_href->{'developer'} ;
Branch: 1 branch
BranchTrueFalseTotal
unless $option_entry_href->{"developer"} 54 21 75
308 }
309 }
310
311 8 ▶ unless (@$names_aref)
Branch: 1 branch
BranchTrueFalseTotal
unless (@$names_aref) 0 8 8
312 {
313 0 $pod .= " NONE\n" ;
314 }
315  
316 8 return $pod ;
317 }
318  
319 #----------------------------------------------------------------------------
320  
321 =item B<pod_options([$developer])>
322  
323 Return pod of options of application
324  
325 If the optional $developer flag is set, returns application developer biased information
326  
327 =cut
328  
329 sub pod_options
330 8 ▶{
Subroutine pod_options: called CC=13 SCAR=25.7
Pod documented
331 8 my $this = shift ;
332 8 my ($developer) = @_ ;
333  
334 8 my $pod ="\n${POD_HEAD}1 OPTIONS\n\n" ;
335  
336 8 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) 1 7 8
337 {
338 1 $pod .= "Get options from application object as:\n my \%opts = \$app->options();\n\n" ;
339 }
340  
341 8 $pod .= "${POD_OVER} 8\n\n" ;
342  
343  
344 # Cycle through
345 8 my $names_aref = $this->app->feature('Options')->option_names() ;
346 8 foreach my $option_name (@$names_aref)
347 {
348 90 my $option_entry_href = $this->app->feature('Options')->option_entry($option_name) ;
349 90 $this->_dbg_prt(["entry for $option_name=",$option_entry_href]) ;
350 90 my $default = "" ;
351 90 ▶ if ($option_entry_href->{'default'})
Branch: 1 branch
BranchTrueFalseTotal
if ($option_entry_href->{"default"}) 4 86 90
352 {
353 4 $default = "[Default: $option_entry_href->{'default'}]" ;
354 }
355  
356 90 my $show = 1 ;
357 90 ▶ $show = 0 if ($option_entry_href->{'developer'} && !$developer) ;
Branch: 1 branch
BranchTrueFalseTotal
if $option_entry_href->{"developer"} and not $developer 21 69 90
Condition100%3/3
$option_entry_href->{"developer"} and not $developer
!ll&&!rl&&r
66321
MC/DC100%2/2
$option_entry_href->{"developer"} and not $developer
$option_entry_href->{"developer"} not $developer
Truth table100%3/3
A and not(B)
A= $option_entry_href->{"developer"}B= not $developer
ABresult
0X0
100
111
358 90 ▶ if ($show)
Branch: 1 branch
BranchTrueFalseTotal
if ($show) 69 21 90
359 {
360 69 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) { } 15 54 69
361 {
362 15 $pod .= "=item -$option_entry_href->{spec} $default # Access as \$opts{$option_entry_href->{field}} \n" ;
363 }
364 else
365 {
366 54 $pod .= "=item B<-$option_entry_href->{pod_spec}> $default\n" ;
367 }
368 69 $pod .= "\n$option_entry_href->{description}\n" ;
369
370 69 ▶ if ($option_entry_href->{dest_type})
Branch: 1 branch
BranchTrueFalseTotal
if ($option_entry_href->{"dest_type"}) 4 65 69
371 {
372 4 $pod .= "This option may be specified multiple times.\n" ;
373
374 4 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) 2 2 4
375 {
376 2 my $dtype = "" ;
377 2 ▶ if ($option_entry_href->{dest_type} eq '@')
Branch: 2 branches
BranchTrueFalseTotal
if ($option_entry_href->{'dest_type'} eq '@') { } 1 1 2
elsif ($option_entry_href->{'dest_type'} eq '%') { } 1 0 1
378 {
379 1 $dtype = 'ARRAY' ;
380 }
381 elsif ($option_entry_href->{dest_type} eq '%')
382 {
383 1 $dtype = 'HASH' ;
384 }
385 2 $pod .= "(The option values will be available internally via the $dtype ref \$opts{$option_entry_href->{field}})\n" ;
386 }
387 }
388 69 $pod .= "\n" ;
389 }
390 }
391  
392 8 ▶ unless (@$names_aref)
Branch: 1 branch
BranchTrueFalseTotal
unless (@$names_aref) 0 8 8
393 {
394 0 $pod .= " NONE\n" ;
395 }
396  
397 8 $pod .= "\n=back\n\n" ;
398  
399 8 return $pod ;
400 }
401  
402 #----------------------------------------------------------------------------
403  
404 =item B<pod_args([$developer])>
405  
406 Return pod of args of application
407  
408 If the optional $developer flag is set, returns application developer biased information
409  
410 =cut
411  
412 sub pod_args
413 8 ▶{
Subroutine pod_args: called CC=8 SCAR=20.8
Pod documented
414 8 my $this = shift ;
415 8 my ($developer) = @_ ;
416  
417 8 my $pod ="\n${POD_HEAD}1 ARGS\n\n" ;
418  
419 8 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) 1 7 8
420 {
421 1 $pod .= "Get args from application object as:\n my \@args = \$app->args();\n# or\n my \%args = \$app->feature('Args')->arghash();\n\n" ;
422 }
423  
424 8 $pod .= "${POD_OVER} 8\n\n" ;
425  
426 # Cycle through
427 8 my $names_aref = $this->app->feature('Args')->arg_names() ;
428 8 foreach my $arg_name (@$names_aref)
429 {
430 31 my $arg_entry_href = $this->app->feature('Args')->arg_entry($arg_name) ;
431  
432 31 my $default = "" ;
433 31 ▶ if ($arg_entry_href->{'default'})
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"default"}) 29 2 31
434 {
435 29 $default = "[Default: $arg_entry_href->{'default'}]" ;
436 }
437  
438 31 my $show = 1 ;
439 31 ▶ if ($show)
Branch: 1 branch
BranchTrueFalseTotal
if ($show) 31 0 31
440 {
441 31 ▶ if ($developer)
Branch: 1 branch
BranchTrueFalseTotal
if ($developer) { } 1 30 31
442 {
443 1 $pod .= "=item * $arg_entry_href->{spec} $default # Access as \$args{$arg_entry_href->{name}} \n" ;
444 }
445 else
446 {
447 30 $pod .= "=item B<* $arg_entry_href->{pod_spec}> $default\n" ;
448 }
449 31 $pod .= "\n$arg_entry_href->{description}\n" ;
450
451 31 ▶ if ($arg_entry_href->{dest_type})
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"dest_type"}) 5 26 31
452 {
453 5 $pod .= "This arg may be specified multiple times.\n" ;
454 }
455 31 $pod .= "\n" ;
456 }
457 }
458  
459 8 ▶ unless (@$names_aref)
Branch: 1 branch
BranchTrueFalseTotal
unless (@$names_aref) 1 7 8
460 {
461 1 $pod .= " NONE\n" ;
462 }
463  
464 8 $pod .= "\n=back\n\n" ;
465  
466 8 return $pod ;
467 }
468  
469 #----------------------------------------------------------------------------
470  
471 =item B<pod_description([$developer])>
472  
473 Return pod of description of application
474  
475 If the optional $developer flag is set, returns application developer biased information
476  
477 =cut
478  
479 sub pod_description
480 8 ▶{
Subroutine pod_description: called CC=1 SCAR=0.0
Pod documented
481 8 my $this = shift ;
482 8 my ($developer) = @_ ;
483  
484 8 my $description = $this->app->description() ;
485  
486 8 my $pod =<<"POD_DESC" ;
487  
488 ${POD_HEAD}1 DESCRIPTION
489  
490 $description
491
492 POD_DESC
493
494 8 return $pod ;
495 }
496  
497  
498 #----------------------------------------------------------------------------
499  
500 =item B<get_synopsis()>
501  
502 Check to ensure synopsis is set. If not, set based on application name and any Args
503 settings
504  
505 =cut
506  
507 sub get_synopsis
508 8 ▶{
Subroutine get_synopsis: called CC=10 SCAR=23.1
Pod documented
509 8 my $this = shift ;
510  
511 8 my $synopsis = $this->app->synopsis() ;
512 8 ▶ if (!$synopsis)
Branch: 1 branch
BranchTrueFalseTotal
unless ($synopsis) 5 3 8
513 {
514 5 my %opts = $this->app->options() ;
515
516 # start with basics
517 5 my $app = $this->app->name() ;
518 5 $synopsis = "$app [options] " ;
519
520 ## Get args
521 5 my $names_aref = $this->app->feature('Args')->arg_names() ;
522 5 foreach my $arg_name (@$names_aref)
523 {
524 10 my $arg_entry_href = $this->app->feature('Args')->arg_entry($arg_name) ;
525  
526 10 my $type = "" ;
527 10 ▶ if ($arg_entry_href->{'type'} eq 'f')
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"type"} eq "f") 8 2 10
528 {
529 8 $type = "file" ;
530 }
531 10 ▶ if ($arg_entry_href->{'type'} eq 'd')
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"type"} eq "d") 2 8 10
532 {
533 2 $type = "directory" ;
534 }
535  
536 10 ▶ if ($type)
Branch: 1 branch
BranchTrueFalseTotal
if ($type) 10 0 10
537 {
538 10 my $direction = "input " ;
539 10 ▶ if ($arg_entry_href->{'direction'} eq 'o')
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"direction"} eq "o") 3 7 10
540 {
541 3 $direction = "output " ;
542 }
543 10 $type = " ($direction $type)" ;
544 }
545  
546 10 my $suffix = "" ;
547 10 ▶ if ($arg_entry_href->{'dest_type'})
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{"dest_type"}) 2 8 10
548 {
549 2 $suffix = "(s)" ;
550 }
551
552 10 ▶ if ($arg_entry_href->{'optional'})
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_entry_href->{'optional'}) { } 0 10 10
553 {
554 0 $synopsis .= 'I<[' ;
555 }
556 else
557 {
558 10 $synopsis .= 'B<' ;
559 }
560
561 10 $synopsis .= "{$arg_name$type$suffix}" ;
562 10 ▶ $synopsis .= ']' if $arg_entry_href->{'optional'} ;
Branch: 1 branch
BranchTrueFalseTotal
if $arg_entry_href->{"optional"} 0 10 10
563 10 $synopsis .= '> ' ;
564 }
565
566 # set our best guess
567 5 $this->app->synopsis($synopsis) ;
568 }
569  
570 8 return $synopsis ;
571 }
572  
573  
574  
575 # ============================================================================================
576 # PRIVATE METHODS
577 # ============================================================================================
578  
579  
580 # ============================================================================================
581 # END OF PACKAGE
582  
583 =back
584  
585 =head1 DIAGNOSTICS
586  
587 Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.
588  
589 =head1 AUTHOR
590  
591 Steve Price C<< <sdprice at cpan.org> >>
592  
593 =head1 BUGS
594  
595 None that I know of!
596  
597 =cut
598  
599  
600 31 1;
601  
602 __END__
« Framework/Feature/Data.pm ↑ Summary Framework/Core.pm »