Params::Sah - Validate method/function parameters using Sah schemas
This document describes version 0.073 of Params::Sah (from Perl distribution Params-Sah), released on 2021-08-04.
use Params::Sah qw(gen_validator); # for subroutines that accept positional parameters. all parameters required, # but you can pass undef to the third param. sub mysub1 { state $validator = gen_validator('str*', ['array*', min_len=>1], 'int'); $validator->(\@_); ... } mysub1("john", ['a']); # dies, the third argument is not passed mysub1("john", ['a'], 2); # ok mysub1("john", ['a'], 2, 3); # dies, extra parameter mysub1("john", ['a'], undef); # ok, even though the third argument is undef mysub1([], ['a'], undef); # dies, first argument does not validate mysub1("john", [], undef); # dies, second argument does not validate # for subroutines that accept positional parameters (this time arrayref instead # of array), some parameters optional. also this time we use 'allow_extra' # option to allow additional positional parameters. sub mysub1b { my $args = shift; state $validator = gen_validator({optional_params=>[2], allow_extra=>1}, 'str*', 'array*', 'int'); $validator->($args); ... } mysub1b(["john", ['a']]); # ok, the third argument is optional mysub1b(["john", ['a'], 2]); # ok mysub1b(["john", ['a'], undef]); # ok mysub1b(["john", ['a'], 2, 3]); # ok, extra params allowed # for subroutines that accept named parameters (as hash). all parameters # required, but you can pass undef to the 'age' parameter. sub mysub2 { my %args = @_; state $validator = gen_validator({named=>1}, name=>'str*', tags=>['array*', min_len=>1], age=>'int'); $validator->(\%args); ... } mysub2(name=>"john", tags=>['a']); # dies, the 'age' argument is not passed mysub2(name=>"john", tags=>['a'], age=>32); # ok mysub2(name=>"john", tags=>['a'], age=>undef); # ok, even though the 'age' argument is undef mysub2(name=>[], tags=>['a'], age=>undef); # dies, the 'name' argument does not validate mysub2(name=>"john", tags=>[], age=>undef); # dies, the 'tags' argument does not validate # for subroutines that accept named parameters (this time as hashref). some # parameters optional. also this time we want to allow extra named parameters. sub mysub2b { my $args = shift; state $validator = gen_validator( {named=>1, optional_params=>['age'], allow_extra=>1}, name=>'str*', tags=>['array*', min_len=>1], age=>'int*', ); $validator->($args); ... } mysub2b({name=>"john", tags=>['a']}); # ok mysub2b({name=>"john", tags=>['a'], age=>32}); # ok mysub2b({name=>"john", tags=>['a'], age=>32, foo=>1}); # ok, extra param 'foo' allowed mysub2b({name=>"john", tags=>['a'], age=>undef}); # dies, this time, 'age' cannot be undef
Example with more complex schemas, with default value and coercion rules:
sub mysub2c { my %args = @_; state $validator = gen_validator( {named => 1, optional_params => ['age']}, name => ['str*', min_len=>4, match=>qr/\S/, default=>'noname'], age => ['int', min=>17, max=>120], tags => ['array*', min_len=>1, of=>['str*', match=>qr/\A\w+\z/], 'x.perl.coerce_rules'=>['From_str::comma_sep']], ); $validator->(\%args); ... } mysub2c(tags=>['a']); # after validation, %args will be: (name=>'noname', tags=>['a']) mysub2c(name=>"mark", tags=>['b,c,d']); # after validation, %args will be: (name=>'mark', tags=>['b','c','d'])
Validator generation options:
# default is to 'croak', valid values include: carp, die, warn, bool, str gen_validator({on_invalid=>'croak'}, ...);
This module provides a way for functions to validate their parameters using Sah schemas.
Bool. If set to true will print validator code when generated.
Str. Used to set default for backend option.
backend
Bool. Used to set default for allow_extra option.
allow_extra
String. Used to set default for on_invalid option.
on_invalid
Bool. Used to set default for err_detail option.
err_detail
Bool. Used to set default for disable option.
disable
Bool. Used to set default for named option.
named
See benchmarks in Bencher::Scenarios::ParamsSah.
None exported by default, but exportable.
Generate code for subroutine validation. It accepts an optional hashref as the first argument for options. The rest of the arguments are Sah schemas that correspond to the function parameters in the same position, i.e. the first schema will validate the function's first argument, and so on. Example:
gen_validator('schema1', 'schema2', ...); gen_validator({option=>'val', ...}, 'schema1', 'schema2', ...);
Will return a coderef which is the validator code. The validator code accepts an arrayref (usually \@_). The validator code will by default croak on invalid parameters, but this behavior can be customized using the on_invalid option.
\@_
Known options:
backend => str (default: Data::Sah)
Can be set to the experimental Data::Sah::Tiny to speed up validator generation for simpler schemas.
named => bool (default: 0)
If set to true, it means we are generating validator for subroutine that accepts named parameters (e.g. f(name=>'val', other=>'val2')) instead of positional (e.g. f('val', 'val2')). The validator will accept the parameters as a hashref. And the arguments of gen_validator are assumed to be a hash of parameter names and schemas instead of a list of schemas, for example:
f(name=>'val', other=>'val2')
f('val', 'val2')
gen_validator
gen_validator({named=>1}, arg1=>'schema1', arg2=>'schema2', ...);
optional_params => array
By default all parameters are required. This option specifies which parameters should be made optional. For positional parameters, specify the index (0-based).
allow_extra => bool (default: 0)
If set to one then additional positional or named parameters are allowed (and not validated). By default, no extra parameters are allowed.
on_invalid => str (default: 'croak')
What should the validator code do when function parameters are invalid? The default is to croak (see Carp) to report error to STDERR from the caller perspective. Other valid choices include: warn, carp, die, bool (return false on invalid, or true on valid), str (return an error message on invalid, or empty string on valid).
warn
carp
die
bool
str
invalid_detail => bool (default: 0)
If set to true, will generate a more detailed error message. For example, with this schema:
[str => {min_len=>4}]
then the string 'foo' will fail to validate with this error message "Length must be at least 4". Otherwise, the error message will just be something like: "Fail schema ['str', {min_len=>1}]". By default this option is set to false for slightly faster validation.
'foo'
disable => bool (default: 0)
If set to 1, will return an empty coderef validator. Used to disable parameter checking. Usually via setting "$OPT_DISABLE" to disable globally.
See the specification: Sah. The Sah::Examples distribution also contains more examples. Also, for other examples, lots of my distributions contain Rinci metadata which includes schemas for each function arguments.
To be able to modify the original array/hash, e.g. set default value.
You can put all your parameters in a hash first, then feed it to the validator. For example:
sub mysub { my %args; %args = %{shift} if req $_[0] eq 'HASH'; # accept optional hashref ($args{x}, $args{y}) = @_; # positional params state $validator = gen_validator( {named=>1, optional_params=>['opt1','opt2']}, x=>"posint*", y=>"negint*", opt1=>"str*", opt2=>"str", ); $validator->(\%args); ... } mysub(1, -2); # ok, after validation %args will become (x=>1, y=>-2) mysub({}, 1, -2); # ok, after validation %args will become (x=>1, y=>-2) mysub({opt1=>"foo"}, 1, -2); # ok, after validation %args will become (x=>1, y=>-2, opt1=>"foo") mysub({opt3=>"foo"}, 1, -2); # dies, unknown option 'opt3' mysub({opt1=>"foo"}, 1); # dies, missing required arg 'x' mysub({opt1=>[]}, 1, -2); # dies, 'opt1' argument doesn't validate
By using the Sah default clause in your schema:
default
gen_validator(['str*', default=>'green']);
By using the optional_params option, which is an array of parameter names to make optional. To set a positional parameter optional, specify its index (0-based) as name.
optional_params
You need to specify that you want to use state variables, either by:
state
# at least use 5.010;
or:
use feature 'state';
Set $Params::Sah::DEBUG=1 before gen_validator(), for example:
$Params::Sah::DEBUG=1
gen_validator()
use Params::Sah qw(gen_validator); $Params::Sah::DEBUG = 1; gen_validator('int*', 'str');
Sample output:
1|sub(\@) { 2| my $_ps_args = shift; 3| my $_ps_res; | | 6| ### validating 0: 7| no warnings 'void'; 8| my $_sahv_dpath = []; 9| Carp::croak("arg0: $_ps_res") if !( # req #0 10| ((defined($_ps_args->[0])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Required but not specified"),0)) | 12| && | 14| # check type 'int' 15| ((Scalar::Util::Numeric::isint($_ps_args->[0])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Not of type integer"),0))); | | 18| ### validating 1: 19| Carp::croak("arg1: $_ps_res") if !( # skip if undef 20| (!defined($_ps_args->[1]) ? 1 : | 22| (# check type 'str' 23| ((!ref($_ps_args->[1])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Not of type text"),0))))); 24| return; | 26|};
Please visit the project's homepage at https://metacpan.org/release/Params-Sah.
Source repository is at https://github.com/perlancar/perl-Params-Sah.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Params-Sah
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.
Sah, Data::Sah
Alternative non-Sah modules: Params::ValidationCompiler (a compiled version of Params::Validate), Type::Params (from Type::Tiny).
Alternative Sah modules: you can add Rinci metadata to your function, then use Perinci::Sub::Wrapper or Perinci::CmdLine to enforce validation. These can do more then schema checking e.g. interargument relationship checking, external dependency checking, etc.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2021, 2020, 2016, 2015 by 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.
To install Params::Sah, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Params::Sah
CPAN shell
perl -MCPAN -e shell install Params::Sah
For more information on module installation, please visit the detailed CPAN module installation guide.