blib/lib/App/FileSync/Args.pm

filter: Statementstmt 93.1% 54 / 58 Branchbran 75.0% 3 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 14 / 14 Podpod 100% 2 / 2 totaltotal 93.5% 73 / 78 CC 3 SCAR 2.6
CC
3
Cov
92%
_validate
2.4
named
2.0
BEGIN
1.0
CRAP 1.3
« blib/lib/App/FileSync/Lock.pm ↑ Summary bin/filesync »
1 package App::FileSync::Args;
2  
3 # One place that turns a routine's @_ into a validated hashref, so every public
4 # entry point reads its arguments the same way and reports a bad one with a
5 # catalogued message instead of the validator's own text.
6  
7 337 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 337 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 337 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 337 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 337 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 337 ▶use Params::Get qw(get_params);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 337 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 337 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 337 ▶use App::FileSync::I18N qw(throw strip_location);
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 337 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 337 our @EXPORT_OK = qw(named positional);
23  
24 # Errors should point at the caller of the routine whose arguments were bad.
25 337 $Carp::Internal{ (__PACKAGE__) }++;
26  
27 =encoding utf8
28  
29 =head1 NAME
30  
31 App::FileSync::Args - validated arguments for App::FileSync's public routines
32  
33 =head1 SYNOPSIS
34  
35 use App::FileSync::Args qw(named positional);
36  
37 sub repo_create {
38 my $self = shift;
39 my $args = named(\@_, {
40 name => { type => 'string', min => 1 },
41 trash_days => { type => 'integer', min => 0, optional => 1 },
42 }, 'repo_create');
43 ...
44 }
45  
46 sub load_repo {
47 my $args = positional(\@_, [qw(root repo)], {
48 root => { type => 'string', min => 1 },
49 repo => { type => 'string', min => 1 },
50 }, 'load_repo');
51 }
52  
53 =head1 FUNCTIONS
54  
55 =head2 named
56  
57 Purpose: validate C<key =E<gt> value> arguments (or a single hashref).
58  
59 Args: C<\@args>, C<\%schema> (L<Params::Validate::Strict> format), C<$routine>
60 (the name used in an error).
61  
62 Returns: a hashref of validated (and coerced) arguments. An empty argument
63 list is an empty hash.
64  
65 Side Effects: raises C<args.invalid> naming the routine and the problem.
66  
67 Usage:
68  
69 my $args = named(\@_, $SCHEMA, 'verify');
70  
71 =head3 EXAMPLE
72  
73 my $args = named([ deep => 1 ], { deep => { type => 'boolean', optional => 1 } }, 'verify');
74  
75 =head3 API SPECIFICATION
76  
77 =head4 INPUT
78  
79 [
80 { name => 'args', type => 'arrayref' },
81 { name => 'schema', type => 'hashref' },
82 { name => 'routine', type => 'string', min => 1 },
83 ]
84  
85 =head4 OUTPUT
86  
87 { type => 'hashref' }
88  
89 =head3 MESSAGES
90  
91 Key Meaning Resolution
92 args.invalid an argument is missing, unknown or invalid fix the call
93  
94 =head3 FORMAL SPECIFICATION
95  
96 named : seq VALUE × SCHEMA × NAME ↛ (KEY ⇸ VALUE)
97 pre pairs(args) satisfies schema
98 post result = coerce(pairs(args))
99  
100 =cut
101  
102 6323 ▶sub named {
Subroutine named: called CC=2 SCAR=6.9
Pod documented
103 6323 my ($args, $schema, $routine) = @_;
104  
105 6323 ▶ my $input = @{$args} ? get_params(undef, $args) : {};
Branch: 1 branch
BranchTrueFalseTotal
@{$args;} ? : 5338 985 6323
106 6323 return _validate($input, $schema, $routine);
107 }
108  
109 =head2 positional
110  
111 Purpose: validate positional arguments by naming them.
112  
113 Args: C<\@args>, C<\@names> (one per position), C<\%schema>, C<$routine>.
114  
115 Returns: a hashref keyed by C<@names>; missing trailing arguments are
116 C<undef> and must be C<optional> in the schema.
117  
118 Side Effects: raises C<args.invalid>.
119  
120 Usage:
121  
122 my $args = positional(\@_, [qw(root repo)], $SCHEMA, 'load_repo');
123  
124 =head3 EXAMPLE
125  
126 my $args = positional([ '/srv', 'docs' ], [qw(root repo)],
127 { root => { type => 'string' }, repo => { type => 'string' } }, 'load_repo');
128  
129 =head3 API SPECIFICATION
130  
131 =head4 INPUT
132  
133 [
134 { name => 'args', type => 'arrayref' },
135 { name => 'names', type => 'arrayref', min => 1 },
136 { name => 'schema', type => 'hashref' },
137 { name => 'routine', type => 'string', min => 1 },
138 ]
139  
140 =head4 OUTPUT
141  
142 { type => 'hashref' }
143  
144 =head3 MESSAGES
145  
146 Key Meaning Resolution
147 args.invalid an argument is missing or invalid fix the call
148  
149 =head3 FORMAL SPECIFICATION
150  
151 positional(a, n, s, r) = named(zip(n, a), s, r)
152 pre #a ≤ #n
153  
154 =cut
155  
156 1034 ▶sub positional {
Subroutine positional: called CC=1 SCAR=0.0
Pod documented
157 1034 my ($args, $names, $schema, $routine) = @_;
158  
159 # Map by position directly: get_params treats a lone hashref argument as
160 # named pairs, which is wrong for a positional routine that takes one.
161 1034 my %input;
162 1034 @input{ @{$names} } = @{$args};
163 1034 delete @input{ grep { !defined $input{$_} } keys %input };
164  
165 1034 return _validate(\%input, $schema, $routine);
166 }
167  
168 # _validate
169 # Purpose: run Params::Validate::Strict and translate its failure.
170 # Entry: $input is a hashref; $schema a Params::Validate::Strict schema.
171 # Exit: returns the validated hashref, or raises args.invalid.
172 # Side effects: none beyond the raise.
173 7357 ▶sub _validate :Private {
Subroutine _validate: called CC=2 SCAR=8.7
174 7357 my ($input, $schema, $routine) = @_;
175  
176 7357 my $valid = eval { validate_strict(schema => $schema, input => $input) };
177 7357 ▶ unless ($valid) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($valid) 0 7357 7357
178 # Drop the validator's own prefix and location; the routine name says
179 # where, and the rest says what.
180 0 my $reason = strip_location($@);
181 0 $reason =~ s/\AParams::Validate::Strict line \d+: (?:validate_strict: )?//;
182 0 $reason =~ s/ at \S+ line \d+\.?\z//;
183 0 throw('args.invalid', { routine => $routine, reason => $reason });
184 }
185  
186 7357 return $valid;
187 337 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
188  
189 337 1;
190  
191 __END__
« blib/lib/App/FileSync/Lock.pm ↑ Summary bin/filesync »