This file is indexed.

/usr/lib/perl5/Params/Validate.pm is in libparams-validate-perl 0.97-1build2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
package Params::Validate;
BEGIN {
  $Params::Validate::VERSION = '0.97';
}

use 5.008001;

use strict;
use warnings;

BEGIN {
    use Exporter;

    use vars qw( $NO_VALIDATION %OPTIONS $options );

    our @ISA = 'Exporter';

    my %tags = (
        types => [
            qw( SCALAR ARRAYREF HASHREF CODEREF GLOB GLOBREF
                SCALARREF HANDLE BOOLEAN UNDEF OBJECT )
        ],
    );

    our %EXPORT_TAGS = (
        'all' => [
            qw( validate validate_pos validation_options validate_with ),
            map { @{ $tags{$_} } } keys %tags
        ],
        %tags,
    );

    our @EXPORT_OK = ( @{ $EXPORT_TAGS{all} }, 'set_options' );
    our @EXPORT = qw( validate validate_pos );

    $NO_VALIDATION = $ENV{PERL_NO_VALIDATION};

    my $e = do {
        local $@;
        eval { require Params::ValidateXS; } unless $ENV{PV_TEST_PERL};
        $@;
    };

    if ( $e || $ENV{PV_TEST_PERL} ) {
        require Params::ValidatePP;
    }
}

1;

# ABSTRACT: Validate method/function parameters



=pod

=head1 NAME

Params::Validate - Validate method/function parameters

=head1 VERSION

version 0.97

=head1 SYNOPSIS

    use Params::Validate qw(:all);

    # takes named params (hash or hashref)
    sub foo {
        validate(
            @_, {
                foo => 1,    # mandatory
                bar => 0,    # optional
            }
        );
    }

    # takes positional params
    sub bar {
        # first two are mandatory, third is optional
        validate_pos( @_, 1, 1, 0 );
    }

    sub foo2 {
        validate(
            @_, {
                foo =>
                    # specify a type
                    { type => ARRAYREF },
                bar =>
                    # specify an interface
                    { can => [ 'print', 'flush', 'frobnicate' ] },
                baz => {
                    type      => SCALAR,     # a scalar ...
                                             # ... that is a plain integer ...
                    regex     => qr/^\d+$/,
                    callbacks => {           # ... and smaller than 90
                        'less than 90' => sub { shift() < 90 },
                    },
                }
            }
        );
    }

    sub with_defaults {
        my %p = validate(
            @_, {
                # required
                foo => 1,
                # $p{bar} will be 99 if bar is not given.  bar is now
                # optional.
                bar => { default => 99 }
            }
        );
    }

    sub pos_with_defaults {
        my @p = validate_pos( @_, 1, { default => 99 } );
    }

    sub sets_options_on_call {
        my %p = validate_with(
            params => \@_,
            spec   => { foo => { type => SCALAR, default => 2 } },
            normalize_keys => sub { $_[0] =~ s/^-//; lc $_[0] },
        );
    }

=head1 DESCRIPTION

The Params::Validate module allows you to validate method or function
call parameters to an arbitrary level of specificity.  At the simplest
level, it is capable of validating the required parameters were given
and that no unspecified additional parameters were passed in.

It is also capable of determining that a parameter is of a specific
type, that it is an object of a certain class hierarchy, that it
possesses certain methods, or applying validation callbacks to
arguments.

=head2 EXPORT

The module always exports the C<validate()> and C<validate_pos()>
functions.

It also has an additional function available for export,
C<validate_with>, which can be used to validate any type of
parameters, and set various options on a per-invocation basis.

In addition, it can export the following constants, which are used as
part of the type checking.  These are C<SCALAR>, C<ARRAYREF>,
C<HASHREF>, C<CODEREF>, C<GLOB>, C<GLOBREF>, and C<SCALARREF>,
C<UNDEF>, C<OBJECT>, C<BOOLEAN>, and C<HANDLE>.  These are explained
in the section on L<Type Validation|Params::Validate/Type Validation>.

The constants are available via the export tag C<:types>.  There is
also an C<:all> tag which includes all of the constants as well as the
C<validation_options()> function.

=head1 PARAMETER VALIDATION

The validation mechanisms provided by this module can handle both
named or positional parameters.  For the most part, the same features
are available for each.  The biggest difference is the way that the
validation specification is given to the relevant subroutine.  The
other difference is in the error messages produced when validation
checks fail.

When handling named parameters, the module will accept either a hash
or a hash reference.

Subroutines expecting named parameters should call the C<validate()>
subroutine like this:

    validate(
        @_, {
            parameter1 => validation spec,
            parameter2 => validation spec,
            ...
        }
    );

Subroutines expecting positional parameters should call the
C<validate_pos()> subroutine like this:

    validate_pos( @_, { validation spec }, { validation spec } );

=head2 Mandatory/Optional Parameters

If you just want to specify that some parameters are mandatory and
others are optional, this can be done very simply.

For a subroutine expecting named parameters, you would do this:

    validate( @_, { foo => 1, bar => 1, baz => 0 } );

This says that the "foo" and "bar" parameters are mandatory and that
the "baz" parameter is optional.  The presence of any other
parameters will cause an error.

For a subroutine expecting positional parameters, you would do this:

    validate_pos( @_, 1, 1, 0, 0 );

This says that you expect at least 2 and no more than 4 parameters.
If you have a subroutine that has a minimum number of parameters but
can take any maximum number, you can do this:

    validate_pos( @_, 1, 1, (0) x (@_ - 2) );

This will always be valid as long as at least two parameters are
given.  A similar construct could be used for the more complex
validation parameters described further on.

Please note that this:

    validate_pos( @_, 1, 1, 0, 1, 1 );

makes absolutely no sense, so don't do it.  Any zeros must come at the
end of the validation specification.

In addition, if you specify that a parameter can have a default, then
it is considered optional.

=head2 Type Validation

This module supports the following simple types, which can be
L<exported as constants|/EXPORT>:

=over 4

=item * SCALAR

A scalar which is not a reference, such as C<10> or C<'hello'>.  A
parameter that is undefined is B<not> treated as a scalar.  If you
want to allow undefined values, you will have to specify C<SCALAR |
UNDEF>.

=item * ARRAYREF

An array reference such as C<[1, 2, 3]> or C<\@foo>.

=item * HASHREF

A hash reference such as C<< { a => 1, b => 2 } >> or C<\%bar>.

=item * CODEREF

A subroutine reference such as C<\&foo_sub> or C<sub { print "hello" }>.

=item * GLOB

This one is a bit tricky.  A glob would be something like C<*FOO>, but
not C<\*FOO>, which is a glob reference.  It should be noted that this
trick:

    my $fh = do { local *FH; };

makes C<$fh> a glob, not a glob reference.  On the other hand, the
return value from C<Symbol::gensym> is a glob reference.  Either can
be used as a file or directory handle.

=item * GLOBREF

A glob reference such as C<\*FOO>.  See the L<GLOB|GLOB> entry above
for more details.

=item * SCALARREF

A reference to a scalar such as C<\$x>.

=item * UNDEF

An undefined value

=item * OBJECT

A blessed reference.

=item * BOOLEAN

This is a special option, and is just a shortcut for C<UNDEF | SCALAR>.

=item * HANDLE

This option is also special, and is just a shortcut for C<GLOB |
GLOBREF>.  However, it seems likely that most people interested in
either globs or glob references are likely to really be interested in
whether the parameter in question could be a valid file or directory
handle.

=back

To specify that a parameter must be of a given type when using named
parameters, do this:

    validate(
        @_, {
            foo => { type => SCALAR },
            bar => { type => HASHREF }
        }
    );

If a parameter can be of more than one type, just use the bitwise or
(C<|>) operator to combine them.

    validate( @_, { foo => { type => GLOB | GLOBREF } );

For positional parameters, this can be specified as follows:

    validate_pos( @_, { type => SCALAR | ARRAYREF }, { type => CODEREF } );

=head2 Interface Validation

To specify that a parameter is expected to have a certain set of
methods, we can do the following:

    validate(
        @_, {
            foo =>
                # just has to be able to ->bar
                { can => 'bar' }
        }
    );

 ... or ...

    validate(
        @_, {
            foo =>
                # must be able to ->bar and ->print
                { can => [qw( bar print )] }
        }
    );

=head2 Class Validation

A word of warning.  When constructing your external interfaces, it is
probably better to specify what methods you expect an object to
have rather than what class it should be of (or a child of).  This
will make your API much more flexible.

With that said, if you want to validate that an incoming parameter
belongs to a class (or child class) or classes, do:

    validate(
        @_,
        { foo => { isa => 'My::Frobnicator' } }
    );

 ... or ...

    validate(
        @_,
        # must be both, not either!
        { foo => { isa => [qw( My::Frobnicator IO::Handle )] } }
    );

=head2 Regex Validation

If you want to specify that a given parameter must match a specific
regular expression, this can be done with "regex" spec key.  For
example:

    validate(
        @_,
        { foo => { regex => qr/^\d+$/ } }
    );

The value of the "regex" key may be either a string or a pre-compiled
regex created via C<qr>.

If the value being checked against a regex is undefined, the regex is
explicitly checked against the empty string ('') instead, in order to
avoid "Use of uninitialized value" warnings.

The C<Regexp::Common> module on CPAN is an excellent source of regular
expressions suitable for validating input.

=head2 Callback Validation

If none of the above are enough, it is possible to pass in one or more
callbacks to validate the parameter.  The callback will be given the
B<value> of the parameter as its first argument.  Its second argument
will be all the parameters, as a reference to either a hash or array.
Callbacks are specified as hash reference.  The key is an id for the
callback (used in error messages) and the value is a subroutine
reference, such as:

    validate(
        @_, {
            foo => {
                callbacks => {
                    'smaller than a breadbox' => sub { shift() < $breadbox },
                    'green or blue' =>
                        sub { $_[0] eq 'green' || $_[0] eq 'blue' }
                }
            }
        );

    validate(
        @_, {
            foo => {
                callbacks => {
                    'bigger than baz' => sub { $_[0] > $_[1]->{baz} }
                }
            }
        }
    );

=head2 Untainting

If you want values untainted, set the "untaint" key in a spec hashref
to a true value, like this:

    my %p = validate(
        @_, {
            foo => { type => SCALAR, untaint => 1 },
            bar => { type => ARRAYREF }
        }
    );

This will untaint the "foo" parameter if the parameters are valid.

Note that untainting is only done if I<all parameters> are valid.
Also, only the return values are untainted, not the original values
passed into the validation function.

Asking for untainting of a reference value will not do anything, as
C<Params::Validate> will only attempt to untaint the reference itself.

=head2 Mandatory/Optional Revisited

If you want to specify something such as type or interface, plus the
fact that a parameter can be optional, do this:

    validate(
        @_, {
            foo => { type => SCALAR },
            bar => { type => ARRAYREF, optional => 1 }
        }
    );

or this for positional parameters:

    validate_pos(
        @_,
        { type => SCALAR },
        { type => ARRAYREF, optional => 1 }
    );

By default, parameters are assumed to be mandatory unless specified as
optional.

=head2 Dependencies

It also possible to specify that a given optional parameter depends on
the presence of one or more other optional parameters.

    validate(
        @_, {
            cc_number => {
                type     => SCALAR,
                optional => 1,
                depends  => [ 'cc_expiration', 'cc_holder_name' ],
            },
            cc_expiration  { type => SCALAR, optional => 1 },
            cc_holder_name { type => SCALAR, optional => 1 },
        }
    );

In this case, "cc_number", "cc_expiration", and "cc_holder_name" are
all optional.  However, if "cc_number" is provided, then
"cc_expiration" and "cc_holder_name" must be provided as well.

This allows you to group together sets of parameters that all must be
provided together.

The C<validate_pos()> version of dependencies is slightly different,
in that you can only depend on one other parameter.  Also, if for
example, the second parameter 2 depends on the fourth parameter, then
it implies a dependency on the third parameter as well.  This is
because if the fourth parameter is required, then the user must also
provide a third parameter so that there can be four parameters in
total.

C<Params::Validate> will die if you try to depend on a parameter not
declared as part of your parameter specification.

=head2 Specifying defaults

If the C<validate()> or C<validate_pos()> functions are called in a list
context, they will return a hash or containing the original parameters plus
defaults as indicated by the validation spec.

If the function is not called in a list context, providing a default
in the validation spec still indicates that the parameter is optional.

The hash or array returned from the function will always be a copy of
the original parameters, in order to leave C<@_> untouched for the
calling function.

Simple examples of defaults would be:

    my %p = validate( @_, { foo => 1, bar => { default => 99 } } );

    my @p = validate_pos( @_, 1, { default => 99 } );

In scalar context, a hash reference or array reference will be
returned, as appropriate.

=head1 USAGE NOTES

=head2 Validation failure

By default, when validation fails C<Params::Validate> calls
C<Carp::confess()>.  This can be overridden by setting the C<on_fail>
option, which is described in the L<"GLOBAL" OPTIONS|"GLOBAL" OPTIONS>
section.

=head2 Method calls

When using this module to validate the parameters passed to a method
call, you will probably want to remove the class/object from the
parameter list B<before> calling C<validate()> or C<validate_pos()>.
If your method expects named parameters, then this is necessary for
the C<validate()> function to actually work, otherwise C<@_> will not
be usable as a hash, because it will first have your object (or
class) B<followed> by a set of keys and values.

Thus the idiomatic usage of C<validate()> in a method call will look
something like this:

    sub method {
        my $self = shift;

        my %params = validate(
            @_, {
                foo => 1,
                bar => { type => ARRAYREF },
            }
        );
    }

=head2 Speeding Up Validation

In most cases, the validation spec will remain the same for each call to a
subroutine. In that case, you can speed up validation by defining the
validation spec just once, rather than on each call to the subroutine:

    my %spec = ( ... );
    sub foo {
        my %params = validate( @_, \%spec );
    }

You can also use the C<state> feature to do this:

    use feature 'state';

    sub foo {
        state %spec = ( ... );
        my %params = validate( @_, \%spec );
    }

=head1 "GLOBAL" OPTIONS

Because the API for the C<validate()> and C<validate_pos()> functions does not
make it possible to specify any options other than the validation spec, it is
possible to set some options as pseudo-'globals'.  These allow you to specify
such things as whether or not the validation of named parameters should be
case sensitive, for one example.

These options are called pseudo-'globals' because these settings are
B<only applied to calls originating from the package that set the
options>.

In other words, if I am in package C<Foo> and I call
C<validation_options()>, those options are only in effect when I call
C<validate()> from package C<Foo>.

While this is quite different from how most other modules operate, I
feel that this is necessary in able to make it possible for one
module/application to use Params::Validate while still using other
modules that also use Params::Validate, perhaps with different
options set.

The downside to this is that if you are writing an app with a standard
calling style for all functions, and your app has ten modules, B<each
module must include a call to C<validation_options()>>. You could of
course write a module that all your modules use which uses various
trickery to do this when imported.

=head2 Options

=over 4

=item * normalize_keys => $callback

This option is only relevant when dealing with named parameters.

This callback will be used to transform the hash keys of both the
parameters and the parameter spec when C<validate()> or
C<validate_with()> are called.

Any alterations made by this callback will be reflected in the
parameter hash that is returned by the validation function.  For
example:

    sub foo {
        return validate_with(
            params => \@_,
            spec   => { foo => { type => SCALAR } },
            normalize_keys =>
                sub { my $k = shift; $k =~ s/^-//; return uc $k },
        );

    }

    %p = foo( foo => 20 );

    # $p{FOO} is now 20

    %p = foo( -fOo => 50 );

    # $p{FOO} is now 50

The callback must return a defined value.

If a callback is given then the deprecated "ignore_case" and
"strip_leading" options are ignored.

=item * allow_extra => $boolean

If true, then the validation routine will allow extra parameters not
named in the validation specification.  In the case of positional
parameters, this allows an unlimited number of maximum parameters
(though a minimum may still be set).  Defaults to false.

=item * on_fail => $callback

If given, this callback will be called whenever a validation check
fails.  It will be called with a single parameter, which will be a
string describing the failure.  This is useful if you wish to have
this module throw exceptions as objects rather than as strings, for
example.

This callback is expected to C<die()> internally.  If it does not, the
validation will proceed onwards, with unpredictable results.

The default is to simply use the Carp module's C<confess()> function.

=item * stack_skip => $number

This tells Params::Validate how many stack frames to skip when finding
a subroutine name to use in error messages.  By default, it looks one
frame back, at the immediate caller to C<validate()> or
C<validate_pos()>.  If this option is set, then the given number of
frames are skipped instead.

=item * ignore_case => $boolean

DEPRECATED

This is only relevant when dealing with named parameters.  If it is
true, then the validation code will ignore the case of parameter
names.  Defaults to false.

=item * strip_leading => $characters

DEPRECATED

This too is only relevant when dealing with named parameters.  If this
is given then any parameters starting with these characters will be
considered equivalent to parameters without them entirely.  For
example, if this is specified as '-', then C<-foo> and C<foo> would be
considered identical.

=back

=head1 PER-INVOCATION OPTIONS

The C<validate_with()> function can be used to set the options listed
above on a per-invocation basis.  For example:

    my %p = validate_with(
        params => \@_,
        spec   => {
            foo => { type    => SCALAR },
            bar => { default => 10 }
        },
        allow_extra => 1,
    );

In addition to the options listed above, it is also possible to set
the option "called", which should be a string.  This string will be
used in any error messages caused by a failure to meet the validation
spec.

This subroutine will validate named parameters as a hash if the "spec"
parameter is a hash reference.  If it is an array reference, the
parameters are assumed to be positional.

    my %p = validate_with(
        params => \@_,
        spec   => {
            foo => { type    => SCALAR },
            bar => { default => 10 }
        },
        allow_extra => 1,
        called      => 'The Quux::Baz class constructor',
    );

    my @p = validate_with(
        params => \@_,
        spec   => [
            { type    => SCALAR },
            { default => 10 }
        ],
        allow_extra => 1,
        called      => 'The Quux::Baz class constructor',
    );

=head1 DISABLING VALIDATION

If the environment variable C<PERL_NO_VALIDATION> is set to something
true, then validation is turned off.  This may be useful if you only
want to use this module during development but don't want the speed
hit during production.

The only error that will be caught will be when an odd number of
parameters are passed into a function/method that expects a hash.

If you want to selectively turn validation on and off at runtime, you
can directly set the C<$Params::Validate::NO_VALIDATION> global
variable.  It is B<strongly> recommended that you B<localize> any
changes to this variable, because other modules you are using may
expect validation to be on when they execute.  For example:

    {
        local $Params::Validate::NO_VALIDATION = 1;

        # no error
        foo( bar => 2 );
    }

    # error
    foo( bar => 2 );

    sub foo {
        my %p = validate( @_, { foo => 1 } );
        ...;
    }

But if you want to shoot yourself in the foot and just turn it off, go
ahead!

=head1 LIMITATIONS

Right now there is no way (short of a callback) to specify that
something must be of one of a list of classes, or that it must possess
one of a list of methods.  If this is desired, it can be added in the
future.

Ideally, there would be only one validation function.  If someone
figures out how to do this, please let me know.

=head1 SUPPORT

Please submit bugs and patches to the CPAN RT system at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params%3A%3AValidate or
via email at bug-params-validate@rt.cpan.org.

Support questions can be sent to Dave at autarch@urth.org.

The code repository is at http://hg.urth.org/hg/Params-Validate

=head1 DONATIONS

If you'd like to thank me for the work I've done on this module,
please consider making a "donation" to me via PayPal. I spend a lot of
free time creating free software, and would appreciate any support
you'd care to offer.

Please note that B<I am not suggesting that you must do this> in order
for me to continue working on this particular software. I will
continue to do so, inasmuch as I have in the past, for as long as it
interests me.

Similarly, a donation made in this way will probably not make me work
on this software much more, unless I get so many donations that I can
consider working on free software full time, which seems unlikely at
best.

To donate, log into PayPal and send money to autarch@urth.org or use
the button on this page:
L<http://www.urth.org/~autarch/fs-donation.html>

=head1 AUTHOR

Dave Rolsky, <autarch@urth.org> and Ilya Martynov <ilya@martynov.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Dave Rolsky and Ilya Martynov.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=cut


__END__