| 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
| |||||||||||
| 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
| |||||||||||
| 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__ | ||||||||||