Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 400 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Params::Check.3perl b/upstream/debian-unstable/man3/Params::Check.3perl
new file mode 100644
index 00000000..4f4819df
--- /dev/null
+++ b/upstream/debian-unstable/man3/Params::Check.3perl
@@ -0,0 +1,400 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 "Params::Check 3perl"
+.TH Params::Check 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+Params::Check \- A generic input parsing/checking mechanism.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use Params::Check qw[check allow last_error];
+\&
+\&    sub fill_personal_info {
+\&        my %hash = @_;
+\&        my $x;
+\&
+\&        my $tmpl = {
+\&            firstname   => { required   => 1, defined => 1 },
+\&            lastname    => { required   => 1, store => \e$x },
+\&            gender      => { required   => 1,
+\&                             allow      => [qr/M/i, qr/F/i],
+\&                           },
+\&            married     => { allow      => [0,1] },
+\&            age         => { default    => 21,
+\&                             allow      => qr/^\ed+$/,
+\&                           },
+\&
+\&            phone       => { allow => [ sub { return 1 if /$valid_re/ },
+\&                                        \*(Aq1\-800\-PERL\*(Aq ]
+\&                           },
+\&            id_list     => { default        => [],
+\&                             strict_type    => 1
+\&                           },
+\&            employer    => { default => \*(AqNSA\*(Aq, no_override => 1 },
+\&        };
+\&
+\&        ### check() returns a hashref of parsed args on success ###
+\&        my $parsed_args = check( $tmpl, \e%hash, $VERBOSE )
+\&                            or die qw[Could not parse arguments!];
+\&
+\&        ... other code here ...
+\&    }
+\&
+\&    my $ok = allow( $colour, [qw|blue green yellow|] );
+\&
+\&    my $error = Params::Check::last_error();
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Params::Check is a generic input parsing/checking mechanism.
+.PP
+It allows you to validate input via a template. The only requirement
+is that the arguments must be named.
+.PP
+Params::Check can do the following things for you:
+.IP \(bu 4
+Convert all keys to lowercase
+.IP \(bu 4
+Check if all required arguments have been provided
+.IP \(bu 4
+Set arguments that have not been provided to the default
+.IP \(bu 4
+Weed out arguments that are not supported and warn about them to the
+user
+.IP \(bu 4
+Validate the arguments given by the user based on strings, regexes,
+lists or even subroutines
+.IP \(bu 4
+Enforce type integrity if required
+.PP
+Most of Params::Check's power comes from its template, which we'll
+discuss below:
+.SH Template
+.IX Header "Template"
+As you can see in the synopsis, based on your template, the arguments
+provided will be validated.
+.PP
+The template can take a different set of rules per key that is used.
+.PP
+The following rules are available:
+.IP default 4
+.IX Item "default"
+This is the default value if none was provided by the user.
+This is also the type \f(CW\*(C`strict_type\*(C'\fR will look at when checking type
+integrity (see below).
+.IP required 4
+.IX Item "required"
+A boolean flag that indicates if this argument was a required
+argument. If marked as required and not provided, \fBcheck()\fR will fail.
+.IP strict_type 4
+.IX Item "strict_type"
+This does a \f(CWref()\fR check on the argument provided. The \f(CW\*(C`ref\*(C'\fR of the
+argument must be the same as the \f(CW\*(C`ref\*(C'\fR of the default value for this
+check to pass.
+.Sp
+This is very useful if you insist on taking an array reference as
+argument for example.
+.IP defined 4
+.IX Item "defined"
+If this template key is true, enforces that if this key is provided by
+user input, its value is \f(CW\*(C`defined\*(C'\fR. This just means that the user is
+not allowed to pass \f(CW\*(C`undef\*(C'\fR as a value for this key and is equivalent
+to:
+    allow => sub { defined \f(CW$_\fR[0] && OTHER TESTS }
+.IP no_override 4
+.IX Item "no_override"
+This allows you to specify \f(CW\*(C`constants\*(C'\fR in your template. ie, they
+keys that are not allowed to be altered by the user. It pretty much
+allows you to keep all your \f(CW\*(C`configurable\*(C'\fR data in one place; the
+\&\f(CW\*(C`Params::Check\*(C'\fR template.
+.IP store 4
+.IX Item "store"
+This allows you to pass a reference to a scalar, in which the data
+will be stored:
+.Sp
+.Vb 2
+\&    my $x;
+\&    my $args = check(foo => { default => 1, store => \e$x }, $input);
+.Ve
+.Sp
+This is basically shorthand for saying:
+.Sp
+.Vb 2
+\&    my $args = check( { foo => { default => 1 }, $input );
+\&    my $x    = $args\->{foo};
+.Ve
+.Sp
+You can alter the global variable \f(CW$Params::Check::NO_DUPLICATES\fR to
+control whether the \f(CW\*(C`store\*(C'\fR'd key will still be present in your
+result set. See the "Global Variables" section below.
+.IP allow 4
+.IX Item "allow"
+A set of criteria used to validate a particular piece of data if it
+has to adhere to particular rules.
+.Sp
+See the \f(CWallow()\fR function for details.
+.SH Functions
+.IX Header "Functions"
+.SS "check( \e%tmpl, \e%args, [$verbose] );"
+.IX Subsection "check( %tmpl, %args, [$verbose] );"
+This function is not exported by default, so you'll have to ask for it
+via:
+.PP
+.Vb 1
+\&    use Params::Check qw[check];
+.Ve
+.PP
+or use its fully qualified name instead.
+.PP
+\&\f(CW\*(C`check\*(C'\fR takes a list of arguments, as follows:
+.IP Template 4
+.IX Item "Template"
+This is a hash reference which contains a template as explained in the
+\&\f(CW\*(C`SYNOPSIS\*(C'\fR and \f(CW\*(C`Template\*(C'\fR section.
+.IP Arguments 4
+.IX Item "Arguments"
+This is a reference to a hash of named arguments which need checking.
+.IP Verbose 4
+.IX Item "Verbose"
+A boolean to indicate whether \f(CW\*(C`check\*(C'\fR should be verbose and warn
+about what went wrong in a check or not.
+.Sp
+You can enable this program wide by setting the package variable
+\&\f(CW$Params::Check::VERBOSE\fR to a true value. For details, see the
+section on \f(CW\*(C`Global Variables\*(C'\fR below.
+.PP
+\&\f(CW\*(C`check\*(C'\fR will return when it fails, or a hashref with lowercase
+keys of parsed arguments when it succeeds.
+.PP
+So a typical call to check would look like this:
+.PP
+.Vb 2
+\&    my $parsed = check( \e%template, \e%arguments, $VERBOSE )
+\&                    or warn q[Arguments could not be parsed!];
+.Ve
+.PP
+A lot of the behaviour of \f(CWcheck()\fR can be altered by setting
+package variables. See the section on \f(CW\*(C`Global Variables\*(C'\fR for details
+on this.
+.ie n .SS "allow( $test_me, \e@criteria );"
+.el .SS "allow( \f(CW$test_me\fP, \e@criteria );"
+.IX Subsection "allow( $test_me, @criteria );"
+The function that handles the \f(CW\*(C`allow\*(C'\fR key in the template is also
+available for independent use.
+.PP
+The function takes as first argument a key to test against, and
+as second argument any form of criteria that are also allowed by
+the \f(CW\*(C`allow\*(C'\fR key in the template.
+.PP
+You can use the following types of values for allow:
+.IP string 4
+.IX Item "string"
+The provided argument MUST be equal to the string for the validation
+to pass.
+.IP regexp 4
+.IX Item "regexp"
+The provided argument MUST match the regular expression for the
+validation to pass.
+.IP subroutine 4
+.IX Item "subroutine"
+The provided subroutine MUST return true in order for the validation
+to pass and the argument accepted.
+.Sp
+(This is particularly useful for more complicated data).
+.IP "array ref" 4
+.IX Item "array ref"
+The provided argument MUST equal one of the elements of the array
+ref for the validation to pass. An array ref can hold all the above
+values.
+.PP
+It returns true if the key matched the criteria, or false otherwise.
+.SS \fBlast_error()\fP
+.IX Subsection "last_error()"
+Returns a string containing all warnings and errors reported during
+the last time \f(CW\*(C`check\*(C'\fR was called.
+.PP
+This is useful if you want to report then some other way than
+\&\f(CW\*(C`carp\*(C'\fR'ing when the verbose flag is on.
+.PP
+It is exported upon request.
+.SH "Global Variables"
+.IX Header "Global Variables"
+The behaviour of Params::Check can be altered by changing the
+following global variables:
+.ie n .SS $Params::Check::VERBOSE
+.el .SS \f(CW$Params::Check::VERBOSE\fP
+.IX Subsection "$Params::Check::VERBOSE"
+This controls whether Params::Check will issue warnings and
+explanations as to why certain things may have failed.
+If you set it to 0, Params::Check will not output any warnings.
+.PP
+The default is 1 when warnings are enabled, 0 otherwise;
+.ie n .SS $Params::Check::STRICT_TYPE
+.el .SS \f(CW$Params::Check::STRICT_TYPE\fP
+.IX Subsection "$Params::Check::STRICT_TYPE"
+This works like the \f(CW\*(C`strict_type\*(C'\fR option you can pass to \f(CW\*(C`check\*(C'\fR,
+which will turn on \f(CW\*(C`strict_type\*(C'\fR globally for all calls to \f(CW\*(C`check\*(C'\fR.
+.PP
+The default is 0;
+.ie n .SS $Params::Check::ALLOW_UNKNOWN
+.el .SS \f(CW$Params::Check::ALLOW_UNKNOWN\fP
+.IX Subsection "$Params::Check::ALLOW_UNKNOWN"
+If you set this flag, unknown options will still be present in the
+return value, rather than filtered out. This is useful if your
+subroutine is only interested in a few arguments, and wants to pass
+the rest on blindly to perhaps another subroutine.
+.PP
+The default is 0;
+.ie n .SS $Params::Check::STRIP_LEADING_DASHES
+.el .SS \f(CW$Params::Check::STRIP_LEADING_DASHES\fP
+.IX Subsection "$Params::Check::STRIP_LEADING_DASHES"
+If you set this flag, all keys passed in the following manner:
+.PP
+.Vb 1
+\&    function( \-key => \*(Aqval\*(Aq );
+.Ve
+.PP
+will have their leading dashes stripped.
+.ie n .SS $Params::Check::NO_DUPLICATES
+.el .SS \f(CW$Params::Check::NO_DUPLICATES\fP
+.IX Subsection "$Params::Check::NO_DUPLICATES"
+If set to true, all keys in the template that are marked as to be
+stored in a scalar, will also be removed from the result set.
+.PP
+Default is false, meaning that when you use \f(CW\*(C`store\*(C'\fR as a template
+key, \f(CW\*(C`check\*(C'\fR will put it both in the scalar you supplied, as well as
+in the hashref it returns.
+.ie n .SS $Params::Check::PRESERVE_CASE
+.el .SS \f(CW$Params::Check::PRESERVE_CASE\fP
+.IX Subsection "$Params::Check::PRESERVE_CASE"
+If set to true, Params::Check will no longer convert all keys from
+the user input to lowercase, but instead expect them to be in the
+case the template provided. This is useful when you want to use
+similar keys with different casing in your templates.
+.PP
+Understand that this removes the case-insensitivity feature of this
+module.
+.PP
+Default is 0;
+.ie n .SS $Params::Check::ONLY_ALLOW_DEFINED
+.el .SS \f(CW$Params::Check::ONLY_ALLOW_DEFINED\fP
+.IX Subsection "$Params::Check::ONLY_ALLOW_DEFINED"
+If set to true, Params::Check will require all values passed to be
+\&\f(CW\*(C`defined\*(C'\fR. If you wish to enable this on a 'per key' basis, use the
+template option \f(CW\*(C`defined\*(C'\fR instead.
+.PP
+Default is 0;
+.ie n .SS $Params::Check::SANITY_CHECK_TEMPLATE
+.el .SS \f(CW$Params::Check::SANITY_CHECK_TEMPLATE\fP
+.IX Subsection "$Params::Check::SANITY_CHECK_TEMPLATE"
+If set to true, Params::Check will sanity check templates, validating
+for errors and unknown keys. Although very useful for debugging, this
+can be somewhat slow in hot-code and large loops.
+.PP
+To disable this check, set this variable to \f(CW\*(C`false\*(C'\fR.
+.PP
+Default is 1;
+.ie n .SS $Params::Check::WARNINGS_FATAL
+.el .SS \f(CW$Params::Check::WARNINGS_FATAL\fP
+.IX Subsection "$Params::Check::WARNINGS_FATAL"
+If set to true, Params::Check will \f(CW\*(C`croak\*(C'\fR when an error during
+template validation occurs, rather than return \f(CW\*(C`false\*(C'\fR.
+.PP
+Default is 0;
+.ie n .SS $Params::Check::CALLER_DEPTH
+.el .SS \f(CW$Params::Check::CALLER_DEPTH\fP
+.IX Subsection "$Params::Check::CALLER_DEPTH"
+This global modifies the argument given to \f(CWcaller()\fR by
+\&\f(CWParams::Check::check()\fR and is useful if you have a custom wrapper
+function around \f(CWParams::Check::check()\fR. The value must be an
+integer, indicating the number of wrapper functions inserted between
+the real function call and \f(CWParams::Check::check()\fR.
+.PP
+Example wrapper function, using a custom stacktrace:
+.PP
+.Vb 2
+\&    sub check {
+\&        my ($template, $args_in) = @_;
+\&
+\&        local $Params::Check::WARNINGS_FATAL = 1;
+\&        local $Params::Check::CALLER_DEPTH = $Params::Check::CALLER_DEPTH + 1;
+\&        my $args_out = Params::Check::check($template, $args_in);
+\&
+\&        my_stacktrace(Params::Check::last_error) unless $args_out;
+\&
+\&        return $args_out;
+\&    }
+.Ve
+.PP
+Default is 0;
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Thanks to Richard Soderberg for his performance improvements.
+.SH "BUG REPORTS"
+.IX Header "BUG REPORTS"
+Please report bugs or other issues to <bug\-params\-check@rt.cpan.org>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This module by Jos Boumans <kane@cpan.org>.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+This library is free software; you may redistribute and/or modify it
+under the same terms as Perl itself.