Spec.pm

filter: Statementstmt 94.4% 205 / 217 Branchbran 87.1% 61 / 70 Conditioncond 63.1% 12 / 19 MC/DCmcdc 30.0% 3 / 10 Subroutinesub 94.1% 16 / 17 Podpod 100% 4 / 4 totaltotal 89.3% 301 / 337 CC 57 SCAR 29.2
CC
57
Cov
91%
usage
34.5
make_getopt
8.2
generate_completion
6.0
CRAP 18.5
« Spec/Plugin/Meta.pm ↑ Summary Spec/Argument.pm »
1 # ABSTRACT: Specification for commandline app
2 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 package App::Spec;
5 7 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 7 our $VERSION = 'v0.15.1'; # TRIAL VERSION
8  
9 7 ▶use App::Spec::Subcommand;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 7 ▶use App::Spec::Option;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 7 ▶use App::Spec::Parameter;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 7 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 7 with('App::Spec::Role::Command');
16  
17 7 has title => ( is => 'rw' );
18 7 has abstract => ( is => 'rw' );
19  
20  
21  
22  
23 34 ▶sub runner {
Subroutine runner: called CC=1 SCAR=0.0
Pod documented
24 34 my ($self, %args) = @_;
25 34 my $class = $self->class;
26 34 my $cmd = $class->new;
27 34 my $run = App::Spec::Run->new({
28 spec => $self,
29 cmd => $cmd,
30 %args,
31 });
32 34 return $run;
33 }
34  
35 19 ▶sub usage {
Subroutine usage: called CC=34 SCAR=35.4
Pod documented
36 19 my ($self, %args) = @_;
37 19 my $cmds = $args{commands};
38 19 ▶ my %highlights = %{ $args{highlights} || {} };
Condition100%2/2
$args{'highlights'} || {}
l!l
127
MC/DC100%1/1
$args{'highlights'} || {}
$args{'highlights'}
Truth table100%2/2
A
A= $args{'highlights'}
Aresult
11
00
39 19 ▶ my $colored = $args{colored} || sub { $_[1] };
Subroutine __ANON__: not called CC=1 SCAR=2.0
Condition33%1/3
$args{'colored'} || sub { $_[1]; }
l!l&&r!l&&!r
1900
MC/DC0%0/2
$args{'colored'} || sub { $_[1]; }
$args{'colored'} sub { $_[1]; }
Truth table33%1/3
A || B
A= $args{'colored'}B= sub { $_[1]; }
ABresult
1X1
011
000
40 19 my $appname = $self->name;
41  
42 19 ▶ my $abstract = $self->abstract // '';
Condition100%2/2
$self->abstract // ""
l!l
163
MC/DC100%1/1
$self->abstract // ""
$self->abstract
Truth table100%2/2
A
A= $self->abstract
Aresult
11
00
43 19 my $title = $self->title;
44 19 my ($options, $parameters, $subcmds) = $self->_gather_options_parameters($cmds);
45 19 my $header = $colored->(['bold'], "$appname - $title");
46 19 my $usage = <<"EOM";
47 $header
48 $abstract
49  
50 EOM
51  
52 19 my $body = '';
53 19 my $usage_header = $colored->([qw/ bold /], "Usage:");
54 19 $usage .= "$usage_header $appname";
55 19 ▶ $usage .= " @$cmds" if @$cmds;
Branch: 1 branch
BranchTrueFalseTotal
if @$cmds 12 7 19
56 19 ▶ if (keys %$subcmds) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %$subcmds) 6 13 19
57 6 my $maxlength = 0;
58 6 my @table;
59 6 my $usage_string = "<subcommands>";
60 6 my $header = "Subcommands:";
61 6 ▶ if ($highlights{subcommands}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($highlights{'subcommands'}) { } 3 3 6
62 3 $colored->([qw/ bold red /], $usage_string);
63 3 $colored->([qw/ bold red /], $header);
64 }
65 else {
66 3 $colored->([qw/ bold /], $header);
67 }
68 6 $usage .= " $usage_string";
69 6 $body .= "$header\n";
70  
71 6 my %keys;
72 6 @keys{ keys %$subcmds } = ();
73 6 my @keys;
74 6 ▶ if (@$cmds) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$cmds) { } 0 6 6
75 0 @keys = sort keys %keys;
76 }
77 else {
78 6 for my $key (qw/ help _meta /) {
79 12 ▶ if (exists $keys{ $key }) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $keys{$key}) 10 2 12
80 10 push @keys, $key;
81 10 delete $keys{ $key };
82 }
83 }
84 6 unshift @keys, sort keys %keys;
85 }
86 6 for my $name (@keys) {
87 38 my $cmd_spec = $subcmds->{ $name };
88 38 my $summary = $cmd_spec->summary;
89 38 my @lines = split m/\n/, $summary;
90 38 ▶ push @table, [$name, $lines[0] // ''];
Condition50%1/2
$lines[0] // ""
l!l
380
MC/DC0%0/1
$lines[0] // ""
$lines[0]
Truth table50%1/2
A
A= $lines[0]
Aresult
11
00
91 38 push @table, ['', $_] for map { s/^ +//; $_ } @lines[1 .. $#lines];
92 38 ▶ if (length $name > $maxlength) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $name > $maxlength) 16 22 38
93 16 $maxlength = length $name;
94 }
95 }
96 6 $body .= $self->_output_table(\@table, [$maxlength]);
97 }
98  
99 19 ▶ if (@$parameters) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$parameters) 9 10 19
100 9 my $maxlength = 0;
101 9 my @table;
102 my @highlights;
103 9 for my $param (@$parameters) {
104 25 my $name = $param->name;
105 25 my $highlight = $highlights{parameters}->{ $name };
106 25 ▶ push @highlights, $highlight ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$highlight ? : 8 17 25
107 25 my $summary = $param->summary;
108 25 my $param_usage_header = $param->to_usage_header;
109 25 ▶ if ($highlight) {
Branch: 1 branch
BranchTrueFalseTotal
if ($highlight) 8 17 25
110 8 $colored->([qw/ bold red /], $param_usage_header);
111 }
112 25 $usage .= " " . $param_usage_header;
113 25 my ($req, $multi) = (' ', ' ');
114 25 ▶ if ($param->required) {
Branch: 1 branch
BranchTrueFalseTotal
if ($param->required) 24 1 25
115 24 $req = "*";
116 }
117 25 ▶ if ($param->mapping) {
Branch: 2 branches
BranchTrueFalseTotal
if ($param->mapping) { } 0 25 25
elsif ($param->multiple) { } 6 19 25
118 0 $multi = '{}';
119 }
120 elsif ($param->multiple) {
121 6 $multi = '[]';
122 }
123  
124 25 my $flags = $self->_param_flags_string($param);
125  
126 25 my @lines = split m/\n/, $summary;
127 25 ▶ push @table, [$name, $req, $multi, ($lines[0] // '') . $flags];
Condition50%1/2
$lines[0] // ""
l!l
250
MC/DC0%0/1
$lines[0] // ""
$lines[0]
Truth table50%1/2
A
A= $lines[0]
Aresult
11
00
128 25 push @table, ['', ' ', ' ', $_] for map { s/^ +//; $_ } @lines[1 .. $#lines];
129 25 ▶ if (length $name > $maxlength) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $name > $maxlength) 14 11 25
130 14 $maxlength = length $name;
131 }
132 }
133 9 my $parameters_string = $colored->([qw/ bold /], "Parameters:");
134 9 $body .= "$parameters_string\n";
135 9 my @lines = $self->_output_table(\@table, [$maxlength]);
136 9 my $lines = $self->_colorize_lines(\@lines, \@highlights, $colored);
137 9 $body .= $lines;
138 }
139  
140 19 ▶ if (@$options) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$options) 19 0 19
141 19 my @highlights;
142 19 $usage .= " [options]";
143 19 my $maxlength = 0;
144 19 my @table;
145 19 for my $opt (sort { $a->name cmp $b->name } @$options) {
146 70 my $name = $opt->name;
147 70 my $highlight = $highlights{options}->{ $name };
148 70 ▶ push @highlights, $highlight ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$highlight ? : 4 66 70
149 70 my $aliases = $opt->aliases;
150 70 my $summary = $opt->summary;
151 my @names = map {
152 70 ▶ length $_ > 1 ? "--$_" : "-$_"
Branch: 1 branch
BranchTrueFalseTotal
length $_ > 1 ? : 70 40 110
153 } ($name, @$aliases);
154 70 my $string = "@names";
155 70 ▶ if (length $string > $maxlength) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $string > $maxlength) 56 14 70
156 56 $maxlength = length $string;
157 }
158 70 my ($req, $multi) = (' ', ' ');
159 70 ▶ if ($opt->required) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt->required) 0 70 70
160 0 $req = "*";
161 }
162 70 ▶ if ($opt->mapping) {
Branch: 2 branches
BranchTrueFalseTotal
if ($opt->mapping) { } 3 67 70
elsif ($opt->multiple) { } 16 51 67
163 3 $multi = '{}';
164 }
165 elsif ($opt->multiple) {
166 16 $multi = '[]';
167 }
168  
169 70 my $flags = $self->_param_flags_string($opt);
170  
171 70 my @lines = split m/\n/, $summary;
172 70 ▶ push @table, [$string, $req, $multi, ($lines[0] // '') . $flags];
Condition50%1/2
$lines[0] // ""
l!l
700
MC/DC0%0/1
$lines[0] // ""
$lines[0]
Truth table50%1/2
A
A= $lines[0]
Aresult
11
00
173 70 push @table, ['', ' ', ' ', $_ ] for map { s/^ +//; $_ } @lines[1 .. $#lines];
174 }
175 19 my $options_string = $colored->([qw/ bold /], "Options:");
176 19 $body .= "\n$options_string\n";
177 19 my @lines = $self->_output_table(\@table, [$maxlength]);
178 19 my $lines = $self->_colorize_lines(\@lines, \@highlights, $colored);
179 19 $body .= $lines;
180 }
181  
182 19 return "$usage\n\n$body";
183 }
184  
185 153 ▶sub _param_flags_string {
Subroutine _param_flags_string: called CC=5 SCAR=16.1
186 153 my ($self, $param) = @_;
187 153 my @flags;
188 153 ▶ if ($param->type eq 'flag') {
Branch: 1 branch
BranchTrueFalseTotal
if ($param->type eq "flag") 72 81 153
189 72 push @flags, "flag";
190 }
191 153 ▶ if ($param->multiple) {
Branch: 1 branch
BranchTrueFalseTotal
if ($param->multiple) 31 122 153
192 31 push @flags, "multiple";
193 }
194 153 ▶ if ($param->mapping) {
Branch: 1 branch
BranchTrueFalseTotal
if ($param->mapping) 4 149 153
195 4 push @flags, "mapping";
196 }
197 153 ▶ my $flags = @flags ? " (" . join("; ", @flags) . ")" : '';
Branch: 1 branch
BranchTrueFalseTotal
@flags ? : 85 68 153
198 153 return $flags;
199 }
200  
201 28 ▶sub _colorize_lines {
Subroutine _colorize_lines: called CC=3 SCAR=11.0
202 28 my ($self, $lines, $highlights, $colored) = @_;
203 28 my $output = '';
204 28 for my $i (0 .. $#$lines) {
205 101 my $line = $lines->[ $i ];
206 101 ▶ if ($highlights->[ $i ]) {
Branch: 1 branch
BranchTrueFalseTotal
if ($highlights->[$i]) 12 89 101
207 12 $colored->([qw/ bold red /], $line);
208 }
209 101 $output .= $line;
210 }
211 28 return $output;
212 }
213  
214 34 ▶sub _output_table {
Subroutine _output_table: called CC=4 SCAR=13.9
215 34 my ($self, $table, $lengths) = @_;
216 34 my @lines;
217 my @lengths = map {
218 124 ▶ defined $lengths->[$_] ? "%-$lengths->[$_]s" : "%s"
Branch: 1 branch
BranchTrueFalseTotal
defined $lengths->[$_] ? : 34 90 124
219 34 } 0 .. @{ $table->[0] } - 1;
220 34 for my $row (@$table) {
221 7 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
222 143 push @lines, sprintf join(' ', @lengths) . "\n", @$row;
223 }
224 34 ▶ return wantarray ? @lines : join '', @lines;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 28 6 34
225 }
226  
227  
228 19 ▶sub _gather_options_parameters {
Subroutine _gather_options_parameters: called CC=5 SCAR=16.2
229 19 my ($self, $cmds) = @_;
230 19 my @options;
231 my @parameters;
232 19 my $global_options = $self->options;
233 19 my $commands = $self->subcommands;
234 19 push @options, @$global_options;
235  
236 19 for my $cmd (@$cmds) {
237 13 my $cmd_spec = $commands->{ $cmd };
238 13 ▶ my $options = $cmd_spec->options || [];
Condition50%1/2
$cmd_spec->options || []
l!l
130
MC/DC0%0/1
$cmd_spec->options || []
$cmd_spec->options
Truth table50%1/2
A
A= $cmd_spec->options
Aresult
11
00
239 13 ▶ my $parameters = $cmd_spec->parameters || [];
Condition50%1/2
$cmd_spec->parameters || []
l!l
130
MC/DC0%0/1
$cmd_spec->parameters || []
$cmd_spec->parameters
Truth table50%1/2
A
A= $cmd_spec->parameters
Aresult
11
00
240 13 push @options, @$options;
241 13 push @parameters, @$parameters;
242  
243 13 ▶ $commands = $cmd_spec->subcommands || {};
Condition100%2/2
$cmd_spec->subcommands || {}
l!l
112
MC/DC100%1/1
$cmd_spec->subcommands || {}
$cmd_spec->subcommands
Truth table100%2/2
A
A= $cmd_spec->subcommands
Aresult
11
00
244  
245 }
246 19 return \@options, \@parameters, $commands;
247 }
248  
249 5 ▶sub generate_completion {
Subroutine generate_completion: called CC=4 SCAR=17.9
Pod documented
250 5 my ($self, %args) = @_;
251 5 my $shell = delete $args{shell};
252  
253 5 ▶ if ($shell eq "zsh") {
Branch: 3 branches
BranchTrueFalseTotal
if ($shell eq 'zsh') { } 0 5 5
elsif ($shell eq 'bash') { } 0 5 5
elsif ($shell eq 'fish') { } 5 0 5
254 0 require App::Spec::Completion::Zsh;
255 0 my $completer = App::Spec::Completion::Zsh->new(
256 spec => $self,
257 );
258 0 return $completer->generate_completion(%args);
259 }
260 elsif ($shell eq "bash") {
261 0 require App::Spec::Completion::Bash;
262 0 my $completer = App::Spec::Completion::Bash->new(
263 spec => $self,
264 );
265 0 return $completer->generate_completion(%args);
266 }
267 elsif ($shell eq "fish") {
268 5 require App::Spec::Completion::Fish;
269 5 my $completer = App::Spec::Completion::Fish->new(
270 spec => $self,
271 );
272 5 return $completer->generate_completion(%args);
273 }
274 }
275  
276  
277 70 ▶sub make_getopt {
Subroutine make_getopt: called CC=8 SCAR=21.0
Pod documented
278 70 my ($self, $options, $result, $specs) = @_;
279 70 my @getopt;
280 70 for my $opt (@$options) {
281 144 my $name = $opt->name;
282 144 my $spec = $name;
283 144 ▶ if (my $aliases = $opt->aliases) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $aliases = $opt->aliases) 144 0 144
284 144 $spec .= "|$_" for @$aliases;
285 }
286 144 ▶ unless ($opt->type eq 'flag') {
Branch: 1 branch
BranchTrueFalseTotal
unless ($opt->type eq "flag") 52 92 144
287 52 $spec .= "=s";
288 }
289 144 $specs->{ $name } = $opt;
290 144 ▶ if ($opt->multiple) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt->multiple) 35 109 144
291 35 ▶ if ($opt->type eq 'flag') {
Branch: 2 branches
BranchTrueFalseTotal
if ($opt->type eq 'flag') { } 30 5 35
elsif ($opt->mapping) { } 5 0 5
292 30 $spec .= '+';
293 }
294 elsif ($opt->mapping) {
295 5 $result->{ $name } = {};
296 5 $spec .= '%';
297 }
298 else {
299 0 $result->{ $name } = [];
300 0 $spec .= '@';
301 }
302 }
303 144 push @getopt, $spec, \$result->{ $name },
304 }
305 70 return @getopt;
306 }
307  
308 =pod
309  
310 =head1 NAME
311  
312 App::Spec - Specification for commandline apps
313  
314 =head1 SYNOPSIS
315  
316 WARNING: This is still experimental. The spec is subject to change.
317  
318 This module represents a specification of a command line tool.
319 Currently it can read the spec from a YAML file or directly from a data
320 structure in perl.
321  
322 It uses the role L<App::Spec::Role::Command>.
323  
324 The L<App::Spec::Run> module is the framework which will run the actual
325 app.
326  
327 Have a look at the L<App::Spec::Tutorial> for how to write an app.
328  
329 In the examples directory you will find the app C<myapp> which is supposed
330 to demonstrate everything that App::Spec supports right now.
331  
332 Your script:
333  
334 use App::Spec;
335 my $spec = App::Spec->read("/path/to/myapp-spec.yaml");
336  
337 my $run = $spec->runner;
338 $run->run;
339  
340 # this is equivalent to
341 #my $run = App::Spec::Run->new(
342 # spec => $spec,
343 # cmd => Your::App->new,
344 #);
345 #$run->run;
346  
347 Your App class:
348  
349 package Your::App;
350 use base 'App::Spec::Run::Cmd';
351  
352 sub command1 {
353 my ($self, $run) = @_;
354 my $options = $run->options;
355 my $param = $run->parameters;
356 # Do something
357 $run->out("Hello world!");
358 $run->err("oops");
359 # you can also use print directly
360 }
361  
362  
363 =head1 METHODS
364  
365 =over 4
366  
367 =item read
368  
369 my $spec = App::Spec->read("/path/to/myapp-spec.yaml");
370  
371 =item load_data
372  
373 Takes a file, hashref or glob and returns generated appspec hashref
374  
375 my $hash = $class->load_data($file);
376  
377 =item build
378  
379 Builds objects out of the hashref
380  
381 my $appspec = App::Spec->build(%hash);
382  
383 =item runner
384  
385 Returns an instance of the your app class
386  
387 my $run = $spec->runner;
388 $run->run;
389  
390 # this is equivalent to
391 my $run = App::Spec::Example::MyApp->new({
392 spec => $spec,
393 });
394 $run->run;
395  
396 =item usage
397  
398 Returns usage output for the specified subcommands:
399  
400 my $usage = $spec->usage(
401 commands => ["subcommand1","subcommand2"],
402 );
403  
404 =item generate_completion
405  
406 Generates shell completion script for the spec. Supported shells: C<zsh>, C<bash>, C<fish> (fish >= 4.0).
407  
408 my $completion = $spec->generate_completion(
409 shell => "zsh",
410 );
411  
412 =item make_getopt
413  
414 Returns options for Getopt::Long
415  
416 my @getopt = $spec->make_getopt($global_options, \%options, $option_specs);
417  
418 =item abstract, appspec, class, description, has_subcommands, markup, name, options, parameters, subcommands, title
419  
420 Accessors for the things defined in the spec (file)
421  
422 =back
423  
424 =head1 SEE ALSO
425  
426 L<App::AppSpec> - Utilities for App::Spec authors
427  
428 =head1 LICENSE
429  
430 This library is free software and may be distributed under the same terms
431 as perl itself.
432  
433 =cut
434  
435 7 1;
436  
« Spec/Plugin/Meta.pm ↑ Summary Spec/Argument.pm »