# no code ## no critic: TestingAndDebugging::RequireUseStrict package Perinci::CmdLine::Manual::Explanation::ArgumentValidation; # just to make podweaver happy # AUTHORITY # DATE our $DIST = 'Perinci-CmdLine'; # DIST # VERSION 1; # ABSTRACT: Argument validation __END__ =pod =encoding UTF-8 =head1 NAME Perinci::CmdLine::Manual::Explanation::ArgumentValidation - Argument validation =head1 VERSION This document describes version 2.000.2 of Perinci::CmdLine::Manual::Explanation::ArgumentValidation (from Perl distribution Perinci-CmdLine), released on 2026-03-30. =head1 DESCRIPTION Argument validation is performed before passing the arguments to the function. It includes: making sure required arguments (arguments with C property set to true) are specified, the values of specified arguments conforms to the argument schema (C property, described in L format), and argument relation rules (in C property in the C function metadata property) are followed. Arguments will be checked against their schemas for all arguments that are specified by the user I 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']], ... } =head1 FAQ =head2 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 C<-set_ARGNAME>. =head2 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 C<-orig_ARGNAME>. =head2 How to get the default value of an argument from the schema/argument specifcation? Use the special argument C<-default_ARGNAME>. =head2 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 C 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 C key in its C<%args> automatically. As well as C<-set_foo> set to false, C<-default_foo> set to C. We know (from C<-set_foo>) that C 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 C clause or C 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 (C), 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 C key in its C<%args> set to C, C set to e.g. C<"Some::Module"> instead of C. C<%args> will also contain C<-set_bar> (false), C<-set_baz> (true), C<-orig_baz> (C) as well as C<-default_bar> (C) and C<-default_baz> (C). You can know from C<-set_bar> that the argument is set by default value and not explicitly by user. =head1 HOMEPAGE Please visit the project's homepage at L. =head1 SOURCE Source repository is at L. =head1 AUTHOR perlancar =head1 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 L, L, L, 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. =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2026 by perlancar . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =head1 BUGS Please report any bugs or feature requests on the bugtracker website L 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. =cut