Debian Codegraph @

lib/Perinci/CmdLine/Manual/Explanation/ArgumentValidation.pod

raw
1 # no code
2 ## no critic: TestingAndDebugging::RequireUseStrict
3 package Perinci::CmdLine::Manual::Explanation::ArgumentValidation; # just to make podweaver happy
4
5 # AUTHORITY
6 # DATE
7 our $DIST = 'Perinci-CmdLine'; # DIST
8 # VERSION
9
10 1;
11 # ABSTRACT: Argument validation
12
13 __END__
14
15 =pod
16
17 =encoding UTF-8
18
19 =head1 NAME
20
21 Perinci::CmdLine::Manual::Explanation::ArgumentValidation - Argument validation
22
23 =head1 VERSION
24
25 This document describes version 2.000.2 of Perinci::CmdLine::Manual::Explanation::ArgumentValidation (from Perl distribution Perinci-CmdLine), released on 2026-03-30.
26
27 =head1 DESCRIPTION
28
29 Argument validation is performed before passing the arguments to the function.
30 It includes: making sure required arguments (arguments with C<req> property set
31 to true) are specified, the values of specified arguments conforms to the
32 argument schema (C<schema> property, described in L<Sah> format), and argument
33 relation rules (in C<args_rels> property in the C<args> function metadata
34 property) are followed.
35
36 Arguments will be checked against their schemas for all arguments that are
37 specified by the user I<or> have a default value/rules in their schema, e.g.:
38
39 # argument specification
40
41 # this argument has a default clause in its schema
42 foo => {
43 schema => ['str*', default=>'on'],
44 ...
45 }
46
47 # this argument has a default-value rule clause in its schema
48 mod => {
49 schema => ['perl::modname*', 'x.perl.default_value_rules'=>['Perl::this_mod']],
50 ...
51 }
52
53 =head1 FAQ
54
55 =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?
56
57 Use the special argument C<-set_ARGNAME>.
58
59 =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?
60
61 Use the special argument C<-orig_ARGNAME>.
62
63 =head2 How to get the default value of an argument from the schema/argument specifcation?
64
65 Use the special argument C<-default_ARGNAME>.
66
67 =head2 What's the difference between setting a default in the argument specification vs in the schema?
68
69 There are two ways to set a default value. The first one is via the C<default>
70 property in argument specification:
71
72 # in the function metadata property...
73 args => {
74 foo => {
75 schema => 'str*',
76 default => 'on',
77 },
78 ...
79 }
80
81 This means, if user does not specify the argument:
82
83 # via CLI
84 % progname
85
86 # via wrapped function call
87 funcname()
88
89 then the function will get a C<foo> key in its C<%args> automatically. As well
90 as C<-set_foo> set to false, C<-default_foo> set to C<on>. We know (from
91 C<-set_foo>) that C<foo> gets its value from the default and not from the user
92 explicitly setting it.
93
94 Another way is by setting default value in the schema's C<default> clause or
95 C<x.perl.default_value_rules> property (the latter allows dynamic default
96 values):
97
98 # in the function metadata property...
99 args => {
100 bar => {
101 schema => ['str*', default=>'on'],
102 ...
103 },
104 baz => {
105 schema => ['perl::modname*', 'x.perl.default_value_rules'=>['Perl::this_mod']],
106 ...
107 },
108 ...
109 }
110
111 This means that if the argument value is set to undefined value (C<undef>), it
112 will get set the default from schema during argument validation:
113
114 # via CLI
115 % progname --baz-json 'null'
116
117 # via wrapped function call
118 funcname(baz=>undef)
119
120 Function will receive C<bar> key in its C<%args> set to C<on>, C<baz> set to
121 e.g. C<"Some::Module"> instead of C<undef>. C<%args> will also contain
122 C<-set_bar> (false), C<-set_baz> (true), C<-orig_baz> (C<undef>) as well as
123 C<-default_bar> (C<on>) and C<-default_baz> (C<Some::Module>).
124
125 You can know from C<-set_bar> that the argument is set by default value and not
126 explicitly by user.
127
128 =head1 HOMEPAGE
129
130 Please visit the project's homepage at L<https://metacpan.org/release/Perinci-CmdLine>.
131
132 =head1 SOURCE
133
134 Source repository is at L<https://github.com/perlancar/perl-Perinci-CmdLine>.
135
136 =head1 AUTHOR
137
138 perlancar <[email protected]>
139
140 =head1 CONTRIBUTING
141
142
143 To contribute, you can send patches by email/via RT, or send pull requests on
144 GitHub.
145
146 Most of the time, you don't need to build the distribution yourself. You can
147 simply modify the code, then test via:
148
149 % prove -l
150
151 If you want to build the distribution (e.g. to try to install it locally on your
152 system), you can install L<Dist::Zilla>,
153 L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
154 L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other
155 Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond
156 that are considered a bug and can be reported to me.
157
158 =head1 COPYRIGHT AND LICENSE
159
160 This software is copyright (c) 2026 by perlancar <[email protected]>.
161
162 This is free software; you can redistribute it and/or modify it under
163 the same terms as the Perl 5 programming language system itself.
164
165 =head1 BUGS
166
167 Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine>
168
169 When submitting a bug or request, please include a test-file or a
170 patch to an existing test-file that illustrates the bug or desired
171 feature.
172
173 =cut