File Coverage

=head1 NAME

App::FileSync::Args - validated arguments for App::FileSync's public routines

=head1 SYNOPSIS

        use App::FileSync::Args qw(named positional);

        sub repo_create {
                my $self = shift;
                my $args = named(\@_, {
                        name       => { type => 'string', min => 1 },
                        trash_days => { type => 'integer', min => 0, optional => 1 },
                }, 'repo_create');
                ...
        }

        sub load_repo {
                my $args = positional(\@_, [qw(root repo)], {
                        root => { type => 'string', min => 1 },
                        repo => { type => 'string', min => 1 },
                }, 'load_repo');
        }

=head1 FUNCTIONS

=head2 named

Purpose: validate C<key =E<gt> value> arguments (or a single hashref).

Args: C<\@args>, C<\%schema> (L<Params::Validate::Strict> format), C<$routine>
(the name used in an error).

Returns: a hashref of validated (and coerced) arguments.  An empty argument
list is an empty hash.

Side Effects: raises C<args.invalid> naming the routine and the problem.

Usage:

        my $args = named(\@_, $SCHEMA, 'verify');

=head3 EXAMPLE

        my $args = named([ deep => 1 ], { deep => { type => 'boolean', optional => 1 } }, 'verify');

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'args',    type => 'arrayref' },
                { name => 'schema',  type => 'hashref' },
                { name => 'routine', type => 'string', min => 1 },
        ]

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key            Meaning                                     Resolution
        args.invalid   an argument is missing, unknown or invalid  fix the call

=head3 FORMAL SPECIFICATION

        named : seq VALUE × SCHEMA × NAME ↛ (KEY ⇸ VALUE)
        pre  pairs(args) satisfies schema
        post result = coerce(pairs(args))

=cut

=head2 positional

Purpose: validate positional arguments by naming them.

Args: C<\@args>, C<\@names> (one per position), C<\%schema>, C<$routine>.

Returns: a hashref keyed by C<@names>; missing trailing arguments are
C<undef> and must be C<optional> in the schema.

Side Effects: raises C<args.invalid>.

Usage:

        my $args = positional(\@_, [qw(root repo)], $SCHEMA, 'load_repo');

=head3 EXAMPLE

        my $args = positional([ '/srv', 'docs' ], [qw(root repo)],
                { root => { type => 'string' }, repo => { type => 'string' } }, 'load_repo');

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'args',    type => 'arrayref' },
                { name => 'names',   type => 'arrayref', min => 1 },
                { name => 'schema',  type => 'hashref' },
                { name => 'routine', type => 'string', min => 1 },
        ]

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key            Meaning                                     Resolution
        args.invalid   an argument is missing or invalid           fix the call

=head3 FORMAL SPECIFICATION

        positional(a, n, s, r) = named(zip(n, a), s, r)
        pre #a ≤ #n

=cut