NAME

Perinci::CmdLine::Manual::Explanation::ArgumentValidation - Argument validation

VERSION

This document describes version 2.000.1 of Perinci::CmdLine::Manual::Explanation::ArgumentValidation (from Perl distribution Perinci-CmdLine), released on 2024-11-12.

DESCRIPTION

Argument validation is performed before passing the arguments to the function. It includes: making sure required arguments (arguments with req property set to true) are specified, the values of specified arguments conforms to the argument schema (schema property, described in Sah format), and argument relation rules (in args_rels property in the args function metadata property) are followed.

Arguments will be checked against their schemas for all arguments that are specified by the user or have a default value/rules in their schema, e.g.:

# argument specification

# this argument has a default clause in its schema
foo => {
    schema => ['str*', default=>'on'],
    ...
}

# this argument has a default-value rule clause in its schema
mod => {
    schema => ['perl::modname*', 'x.perl.default_value_rules'=>['Perl::this_mod']],
    ...
}

FAQ

How to find out if an argument is set explicitly by the user or is getting a default value from the schema/argument specification?

Use the special argument -set_ARGNAME.

How to get the original value on an argument sent by user before the argument is being coerced/filtered/given default value by the schema?

Use the special argument -orig_ARGNAME.

How to get the default value of an argument from the schema/argument specifcation?

Use the special argument -default_ARGNAME.

What's the difference between setting a default in the argument specification vs in the schema?

There are two ways to set a default value. The first one is via the default property in argument specification:

# in the function metadata property...
args => {
    foo => {
        schema => 'str*',
        default => 'on',
    },
    ...
}

This means, if user does not specify the argument:

# via CLI
% progname

# via wrapped function call
funcname()

then the function will get a foo key in its %args automatically. As well as -set_foo set to false, -default_foo set to on. We know (from -set_foo) that foo gets its value from the default and not from the user explicitly setting it.

Another way is by setting default value in the schema's default clause or x.perl.default_value_rules property (the latter allows dynamic default values):

# in the function metadata property...
args => {
    bar => {
        schema => ['str*', default=>'on'],
        ...
    },
    baz => {
        schema => ['perl::modname*', 'x.perl.default_value_rules'=>['Perl::this_mod']],
        ...
    },
    ...
}

This means that if the argument value is set to undefined value (undef), it will get set the default from schema during argument validation:

# via CLI
% progname --baz-json 'null'

# via wrapped function call
funcname(baz=>undef)

Function will receive bar key in its %args set to on, baz set to e.g. "Some::Module" instead of undef. %args will also contain -set_bar (false), -set_baz (true), -orig_baz (undef) as well as -default_bar (on) and -default_baz (Some::Module).

You can know from -set_bar that the argument is set by default value and not explicitly by user.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-CmdLine.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-CmdLine.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

cpanm Perinci::CmdLine

perl -MCPAN -e shell
install Perinci::CmdLine