---
name: "Perinci::CmdLine::Manual::Explanation::ArgumentValidation"
section: "3pm"
platform: "linux"
package: "libperinci-cmdline-perl"
version: "2.000.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Perinci::CmdLine::Manual::Explanation::ArgumentValidation"
---

# Perinci::CmdLine::Manual::Explanation::ArgumentValidation(3pm)

Argument validation

## 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.