File Coverage

blib/lib/Params/CheckCompiler.pm
Criterion Covered Total %
statement 13 14 92.8
branch n/a
condition n/a
subroutine 5 6 83.3
pod 2 2 100.0
total 20 22 90.9


line stmt bran cond sub pod time code
1             package Params::CheckCompiler;
2              
3 8     8   676553 use strict;
  8         11  
  8         163  
4 8     8   24 use warnings;
  8         8  
  8         232  
5              
6             our $VERSION = '0.07';
7              
8 8     8   2746 use Params::CheckCompiler::Compiler;
  8         11  
  8         183  
9              
10 8     8   33 use Exporter qw( import );
  8         6  
  8         602  
11              
12             our @EXPORT_OK = qw( compile source_for validation_for );
13              
14             sub validation_for {
15 17     17 1 40482 return Params::CheckCompiler::Compiler->new(@_)->subref;
16             }
17              
18             *compile = \&validation_for;
19              
20             sub source_for {
21 0     0 1   return Params::CheckCompiler::Compiler->new(@_)->source_for;
22             }
23              
24             1;
25              
26             # ABSTRACT: Build an optimized subroutine parameter validator once, use it forever
27              
28             __END__
29              
30             =pod
31              
32             =encoding UTF-8
33              
34             =head1 NAME
35              
36             Params::CheckCompiler - Build an optimized subroutine parameter validator once, use it forever
37              
38             =head1 VERSION
39              
40             version 0.07
41              
42             =head1 SYNOPSIS
43              
44             use Types::Standard qw( Int Str );
45             use Params::CheckCompiler qw( validation_for );
46              
47             {
48             my $check = validation_for(
49             params => {
50             foo => { type => Int },
51             bar => {
52             type => Str,
53             optional => 1,
54             },
55             baz => {
56             type => Int,
57             default => 42,
58             },
59             },
60             );
61              
62             sub do_something {
63             my %args = $check->(@_);
64             }
65             }
66              
67             =head1 DESCRIPTION
68              
69             B<This is very alpha. The module name could change. Everything could
70             change. You have been warned.>
71              
72             Create a customized, optimized, non-lobotomized, uncompromised, and thoroughly
73             specialized parameter checking subroutine.
74              
75             =for Pod::Coverage compile
76              
77             =head1 EXPORTS
78              
79             This module has two options exports, C<validation_for> and C<source_for>. Both
80             of these subs accept the same options:
81              
82             =over 4
83              
84             =item * params
85              
86             An arrayref or hashref containing a parameter specification.
87              
88             If you pass an arrayref, the check will expect positional params. Each member
89             of the arrayref represents a single parameter to validate.
90              
91             If you pass a hashref then it will expect named params. For hashrefs, the
92             parameters names are the keys and the specs are the values.
93              
94             The spec can contain either a boolean or hashref. If the spec is a boolean,
95             this indicates required (true) or optional (false).
96              
97             The hashref accepts the following keys:
98              
99             =over 8
100              
101             =item * type
102              
103             A type object. This can be a L<Moose> type (from L<Moose> or
104             L<MooseX::Types>), a L<Type::Tiny> type, or a L<Specio> type.
105              
106             If the type has coercions, those will always be used.
107              
108             =item * default
109              
110             This can either be a simple (non-reference) scalar or a subroutine
111             reference. The sub ref will be called without any arguments (for now).
112              
113             =item * optional
114              
115             A boolean indicating whether or not the parameter is optional. By default,
116             parameters are required unless you provide a default.
117              
118             =back
119              
120             =item * slurpy
121              
122             If this is a simple true value, then the generated subroutine accepts
123             additional arguments not specified in C<params>. By default, extra arguments
124             cause an exception.
125              
126             You can also pass a type constraint here, in which case all extra arguments
127             must be values of the specified type.
128              
129             =back
130              
131             =head2 validation_for(...)
132              
133             This returns a subroutine that implements the specific parameter
134             checking. Pass this the arguments in C<@_> and it will return a hash of
135             parameters or throw an exception. The generated subroutine accepts either a
136             hash or a single hashref.
137              
138             For now, you must shift off the invocant yourself.
139              
140             This subroutine accepts an additional parameter:
141              
142             =over 4
143              
144             =item * name
145              
146             If this is given, then the generated subroutine will be named using
147             L<Sub::Name>. This is strongly recommended as it makes it possible to
148             distinguish different check subroutines when profiling or in stack traces.
149              
150             =back
151              
152             =head2 source_for(...)
153              
154             This returns a two element list. The first is a string containing the source
155             code for the generated sub. The second is a hashref of "environment" variables
156             to be used when generating the subroutine. These are the arguments that are
157             passed to L<Eval::Closure>.
158              
159             =head1 SUPPORT
160              
161             Bugs may be submitted through L<the RT bug tracker|http://rt.cpan.org/Public/Dist/Display.html?Name=Params-CheckCompiler>
162             (or L<bug-params-checkcompiler@rt.cpan.org|mailto:bug-params-checkcompiler@rt.cpan.org>).
163              
164             I am also usually active on IRC as 'drolsky' on C<irc://irc.perl.org>.
165              
166             =head1 DONATIONS
167              
168             If you'd like to thank me for the work I've done on this module, please
169             consider making a "donation" to me via PayPal. I spend a lot of free time
170             creating free software, and would appreciate any support you'd care to offer.
171              
172             Please note that B<I am not suggesting that you must do this> in order for me
173             to continue working on this particular software. I will continue to do so,
174             inasmuch as I have in the past, for as long as it interests me.
175              
176             Similarly, a donation made in this way will probably not make me work on this
177             software much more, unless I get so many donations that I can consider working
178             on free software full time (let's all have a chuckle at that together).
179              
180             To donate, log into PayPal and send money to autarch@urth.org, or use the
181             button at L<http://www.urth.org/~autarch/fs-donation.html>.
182              
183             =head1 AUTHOR
184              
185             Dave Rolsky <autarch@urth.org>
186              
187             =head1 COPYRIGHT AND LICENCE
188              
189             This software is Copyright (c) 2016 by Dave Rolsky.
190              
191             This is free software, licensed under:
192              
193             The Artistic License 2.0 (GPL Compatible)
194              
195             =cut