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

       perlancar <perlancar@cpan.org>

       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.

perl v5.40.0                                       2024-11-15              Perinci::CmdLi...umentValidation(3pm)

       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.

       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.

       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']],
            ...
        }

Howtofindoutifanargumentissetexplicitlybytheuserorisgettingadefaultvaluefromtheschema/argumentspecification?
       Use the special argument "-set_ARGNAME".

   Howtogettheoriginalvalueonanargumentsentbyuserbeforetheargumentisbeingcoerced/filtered/givendefaultvaluebytheschema?
       Use the special argument "-orig_ARGNAME".

   Howtogetthedefaultvalueofanargumentfromtheschema/argumentspecifcation?
       Use the special argument "-default_ARGNAME".

   What'sthedifferencebetweensettingadefaultintheargumentspecificationvsintheschema?
       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.

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

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

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

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