NAME

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

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');
}

FUNCTIONS

named

Purpose: validate key => value arguments (or a single hashref).

Args: \@args, \%schema (Params::Validate::Strict format), $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 args.invalid naming the routine and the problem.

Usage:

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

EXAMPLE

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

API SPECIFICATION

INPUT

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

OUTPUT

{ type => 'hashref' }

MESSAGES

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

FORMAL SPECIFICATION

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

positional

Purpose: validate positional arguments by naming them.

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

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

Side Effects: raises args.invalid.

Usage:

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

EXAMPLE

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

API SPECIFICATION

INPUT

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

OUTPUT

{ type => 'hashref' }

MESSAGES

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

FORMAL SPECIFICATION

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

LIMITATIONS

Validation costs about 11 microseconds per call, so it is used at entry points that run a few times per command, not per file or per protocol frame. The validator's reason text is English whatever the catalogue language.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.

cpanm App::FileSync

perl -MCPAN -e shell
install App::FileSync