.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Perinci::CmdLine::Manual::Explanation::ArgumentValidation 3pm" .TH Perinci::CmdLine::Manual::Explanation::ArgumentValidation 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Perinci::CmdLine::Manual::Explanation::ArgumentValidation \- Argument validation .SH "VERSION" .IX Header "VERSION" This document describes version 2.000.0 of Perinci::CmdLine::Manual::Explanation::ArgumentValidation (from Perl distribution Perinci-CmdLine), released on 2021\-12\-19. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Argument validation is performed before passing the arguments to the function. It includes: making sure required arguments (arguments with \f(CW\*(C`req\*(C'\fR property set to true) are specified, the values of specified arguments conforms to the argument schema (\f(CW\*(C`schema\*(C'\fR property, described in Sah format), and argument relation rules (in \f(CW\*(C`args_rels\*(C'\fR property in the \f(CW\*(C`args\*(C'\fR function metadata property) are followed. .PP Arguments will be checked against their schemas for all arguments that are specified by the user \fIor\fR have a default value/rules in their schema, e.g.: .PP .Vb 1 \& # argument specification \& \& # this argument has a default clause in its schema \& foo => { \& schema => [\*(Aqstr*\*(Aq, default=>\*(Aqon\*(Aq], \& ... \& } \& \& # this argument has a default\-value rule clause in its schema \& mod => { \& schema => [\*(Aqperl::modname*\*(Aq, \*(Aqx.perl.default_value_rules\*(Aq=>[\*(AqPerl::this_mod\*(Aq]], \& ... \& } .Ve .SH "FAQ" .IX Header "FAQ" .SS "How to find out if an argument is set explicitly by the user or is getting a default value from the schema/argument specification?" .IX Subsection "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 \f(CW\*(C`\-set_ARGNAME\*(C'\fR. .SS "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?" .IX Subsection "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 \f(CW\*(C`\-orig_ARGNAME\*(C'\fR. .SS "How to get the default value of an argument from the schema/argument specifcation?" .IX Subsection "How to get the default value of an argument from the schema/argument specifcation?" Use the special argument \f(CW\*(C`\-default_ARGNAME\*(C'\fR. .SS "What's the difference between setting a default in the argument specification vs in the schema?" .IX Subsection "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 \f(CW\*(C`default\*(C'\fR property in argument specification: .PP .Vb 8 \& # in the function metadata property... \& args => { \& foo => { \& schema => \*(Aqstr*\*(Aq, \& default => \*(Aqon\*(Aq, \& }, \& ... \& } .Ve .PP This means, if user does not specify the argument: .PP .Vb 2 \& # via CLI \& % progname \& \& # via wrapped function call \& funcname() .Ve .PP then the function will get a \f(CW\*(C`foo\*(C'\fR key in its \f(CW%args\fR automatically. As well as \f(CW\*(C`\-set_foo\*(C'\fR set to false, \f(CW\*(C`\-default_foo\*(C'\fR set to \f(CW\*(C`on\*(C'\fR. We know (from \&\f(CW\*(C`\-set_foo\*(C'\fR) that \f(CW\*(C`foo\*(C'\fR gets its value from the default and not from the user explicitly setting it. .PP Another way is by setting default value in the schema's \f(CW\*(C`default\*(C'\fR clause or \&\f(CW\*(C`x.perl.default_value_rules\*(C'\fR property (the latter allows dynamic default values): .PP .Vb 12 \& # in the function metadata property... \& args => { \& bar => { \& schema => [\*(Aqstr*\*(Aq, default=>\*(Aqon\*(Aq], \& ... \& }, \& baz => { \& schema => [\*(Aqperl::modname*\*(Aq, \*(Aqx.perl.default_value_rules\*(Aq=>[\*(AqPerl::this_mod\*(Aq]], \& ... \& }, \& ... \& } .Ve .PP This means that if the argument value is set to undefined value (\f(CW\*(C`undef\*(C'\fR), it will get set the default from schema during argument validation: .PP .Vb 2 \& # via CLI \& % progname \-\-baz\-json \*(Aqnull\*(Aq \& \& # via wrapped function call \& funcname(baz=>undef) .Ve .PP Function will receive \f(CW\*(C`bar\*(C'\fR key in its \f(CW%args\fR set to \f(CW\*(C`on\*(C'\fR, \f(CW\*(C`baz\*(C'\fR set to e.g. \f(CW"Some::Module"\fR instead of \f(CW\*(C`undef\*(C'\fR. \f(CW%args\fR will also contain \&\f(CW\*(C`\-set_bar\*(C'\fR (false), \f(CW\*(C`\-set_baz\*(C'\fR (true), \f(CW\*(C`\-orig_baz\*(C'\fR (\f(CW\*(C`undef\*(C'\fR) as well as \&\f(CW\*(C`\-default_bar\*(C'\fR (\f(CW\*(C`on\*(C'\fR) and \f(CW\*(C`\-default_baz\*(C'\fR (\f(CW\*(C`Some::Module\*(C'\fR). .PP You can know from \f(CW\*(C`\-set_bar\*(C'\fR that the argument is set by default value and not explicitly by user. .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "CONTRIBUTING" .IX Header "CONTRIBUTING" To contribute, you can send patches by email/via \s-1RT,\s0 or send pull requests on GitHub. .PP Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via: .PP .Vb 1 \& % prove \-l .Ve .PP 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, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2021, 2018, 2017, 2016, 2015 by perlancar . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP 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.