======================================================================== * README.md ======================================================================== # NAME Params::ValidationCompiler - Build an optimized subroutine parameter validator once, use it forever # VERSION version 0.30 # SYNOPSIS use Types::Standard qw( Int Str ); use Params::ValidationCompiler qw( validation_for ); { my $validator = validation_for( params => { foo => { type => Int }, bar => { type => Str, optional => 1, }, baz => { type => Int, default => 42, }, }, ); sub foo { my %args = $validator->(@_); } } { my $validator = validation_for( params => [ { type => Int }, { type => Str, optional => 1, }, ], ); sub bar { my ( $int, $str ) = $validator->(@_); } } { my $validator = validation_for( params => [ foo => { type => Int }, bar => { type => Str, optional => 1, }, ], named_to_list => 1, ); sub baz { my ( $foo, $bar ) = $validator->(@_); } } # DESCRIPTION This module creates a customized, highly efficient parameter checking subroutine. It can handle named or positional parameters, and can return the parameters as key/value pairs or a list of values. In addition to type checks, it also supports parameter defaults, optional parameters, and extra "slurpy" parameters. # PARAMETERS This module has two options exports, `validation_for` and `source_for`. Both of these subs accept the same options: ## params An arrayref or hashref containing a parameter specification. If you pass a hashref then the generated validator sub will expect named parameters. The `params` value should be a hashref where the parameter names are keys and the specs are the values. If you pass an arrayref and `named_to_list` is false, the validator will expect positional params. Each element of the `params` arrayref should be a parameter spec. If you pass an arrayref and `named_to_list` is true, the validator will expect named params, but will return a list of values. In this case the arrayref should contain a _list_ of key/value pairs, where parameter names are the keys and the specs are the values. Each spec can contain either a boolean or hashref. If the spec is a boolean, this indicates required (true) or optional (false). The spec hashref accepts the following keys: - type A type object. This can be a [Moose](https://metacpan.org/pod/Moose) type (from [Moose](https://metacpan.org/pod/Moose) or [MooseX::Types](https://metacpan.org/pod/MooseX::Types)), a [Type::Tiny](https://metacpan.org/pod/Type::Tiny) type, or a [Specio](https://metacpan.org/pod/Specio) type. If the type has coercions, those will always be used. - default This can either be a simple (non-reference) scalar or a subroutine reference. The sub ref will be called without any arguments (for now). - optional A boolean indicating whether or not the parameter is optional. By default, parameters are required unless you provide a default. ## slurpy If this is a simple true value, then the generated subroutine accepts additional arguments not specified in `params`. By default, extra arguments cause an exception. You can also pass a type constraint here, in which case all extra arguments must be values of the specified type. ## named\_to\_list If this is true, the generated subroutine will expect a list of key-value pairs or a hashref and it will return a list containing only values. The `params` you pass must be a arrayref of key-value pairs. The order of these pairs determines the order in which values are returned. You cannot combine `slurpy` with `named_to_list` as there is no way to know how to order the extra return values. ## return\_object If this is true, the generated subroutine will return an object instead of a hashref. You cannot set this option to true if you set either or `slurpy` or `named_to_list`. The object's methods correspond to the parameter names passed to the subroutine. While calling methods on an object is slower than accessing a hashref, the advantage is that if you typo a parameter name you'll get a helpful error. If you have [Class::XSAccessor](https://metacpan.org/pod/Class::XSAccessor) installed then this will be used to create the class's methods, which makes it fairly fast. The returned object is in a generated class. Do not rely on this class name being anything in specific, and don't check this object using `isa`, `DOES`, or anything similar. When `return_object` is true, the parameter spec hashref also accepts to the following additional keys: - getter Use this to set an explicit getter method name for the parameter. By default the method name will be the same as the parameter name. Note that if the parameter name is not a valid sub name, then you will get an error compiling the validation sub unless you specify a getter for the parameter. - predicate Use this to ask for a predicate method to be created for this parameter. The predicate method returns true if the parameter was passed and false if it wasn't. Note that this is only useful for optional parameters, but you can ask for a predicate for any parameter. # EXPORTS The exported subs are: ## validation\_for(...) This returns a subroutine that implements the specific parameter checking. This subroutine expects to be given the parameters to validate in `@_`. If all the parameters are valid, it will return the validated parameters (with defaults as appropriate), either as a list of key-value pairs or as a list of just values. If any of the parameters are invalid it will throw an exception. For validators expected named params, the generated subroutine accepts either a list of key-value pairs or a single hashref. Otherwise the validator expects a list of values. For now, you must shift off the invocant yourself. This subroutine accepts the following additional parameters: - name If this is given, then the generated subroutine will be named using [Sub::Util](https://metacpan.org/pod/Sub::Util). This is strongly recommended as it makes it possible to distinguish different check subroutines when profiling or in stack traces. This name will also be used in some exception messages, even if [Sub::Util](https://metacpan.org/pod/Sub::Util) is not available. Note that you must install [Sub::Util](https://metacpan.org/pod/Sub::Util) yourself separately, as it is not required by this distribution, in order to avoid requiring a compiler. - name\_is\_optional If this is true, then the name is ignored when `Sub::Util` is not installed. If this is false, then passing a name when [Sub::Util](https://metacpan.org/pod/Sub::Util) cannot be loaded causes an exception. This is useful for CPAN modules where you want to set a name if you can, but you do not want to add a prerequisite on [Sub::Util](https://metacpan.org/pod/Sub::Util). - debug Sets the `EVAL_CLOSURE_PRINT_SOURCE` environment variable to true before calling `Eval::Closure::eval_closure()`. This causes the source of the subroutine to be printed before it's `eval`'d. ## source\_for(...) This returns a two element list. The first is a string containing the source code for the generated sub. The second is a hashref of "environment" variables to be used when generating the subroutine. These are the arguments that are passed to [Eval::Closure](https://metacpan.org/pod/Eval::Closure). # SUPPORT Bugs may be submitted at [https://github.com/houseabsolute/Params-ValidationCompiler/issues](https://github.com/houseabsolute/Params-ValidationCompiler/issues). I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`. # SOURCE The source code repository for Params-ValidationCompiler can be found at [https://github.com/houseabsolute/Params-ValidationCompiler](https://github.com/houseabsolute/Params-ValidationCompiler). # 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 **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 (let's all have a chuckle at that together). To donate, log into PayPal and send money to autarch@urth.org, or use the button at [http://www.urth.org/~autarch/fs-donation.html](http://www.urth.org/~autarch/fs-donation.html). # AUTHOR Dave Rolsky # CONTRIBUTORS - Gregory Oschwald - Gregory Oschwald - Tomasz Konojacki # COPYRIGHT AND LICENSE This software is Copyright (c) 2016 - 2018 by Dave Rolsky. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible) The full text of the license can be found in the `LICENSE` file included with this distribution. ======================================================================== * LICENSE ======================================================================== This software is Copyright (c) 2016 - 2018 by Dave Rolsky. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible) The Artistic License 2.0 Copyright (c) 2000-2006, The Perl Foundation. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble This license establishes the terms under which a given free software Package may be copied, modified, distributed, and/or redistributed. The intent is that the Copyright Holder maintains some artistic control over the development of that Package while still keeping the Package available as open source and free software. You are always permitted to make arrangements wholly outside of this license directly with the Copyright Holder of a given Package. If the terms of this license do not permit the full use that you propose to make of the Package, you should contact the Copyright Holder and seek a different licensing arrangement. Definitions "Copyright Holder" means the individual(s) or organization(s) named in the copyright notice for the entire Package. "Contributor" means any party that has contributed code or other material to the Package, in accordance with the Copyright Holder's procedures. "You" and "your" means any person who would like to copy, distribute, or modify the Package. "Package" means the collection of files distributed by the Copyright Holder, and derivatives of that collection and/or of those files. A given Package may consist of either the Standard Version, or a Modified Version. "Distribute" means providing a copy of the Package or making it accessible to anyone else, or in the case of a company or organization, to others outside of your company or organization. "Distributor Fee" means any fee that you charge for Distributing this Package or providing support for this Package to another party. It does not mean licensing fees. "Standard Version" refers to the Package if it has not been modified, or has been modified only in ways explicitly requested by the Copyright Holder. "Modified Version" means the Package, if it has been changed, and such changes were not explicitly requested by the Copyright Holder. "Original License" means this Artistic License as Distributed with the Standard Version of the Package, in its current version or as it may be modified by The Perl Foundation in the future. "Source" form means the source code, documentation source, and configuration files for the Package. "Compiled" form means the compiled bytecode, object code, binary, or any other form resulting from mechanical transformation or translation of the Source form. Permission for Use and Modification Without Distribution (1) You are permitted to use the Standard Version and create and use Modified Versions for any purpose without restriction, provided that you do not Distribute the Modified Version. Permissions for Redistribution of the Standard Version (2) You may Distribute verbatim copies of the Source form of the Standard Version of this Package in any medium without restriction, either gratis or for a Distributor Fee, provided that you duplicate all of the original copyright notices and associated disclaimers. At your discretion, such verbatim copies may or may not include a Compiled form of the Package. (3) You may apply any bug fixes, portability changes, and other modifications made available from the Copyright Holder. The resulting Package will still be considered the Standard Version, and as such will be subject to the Original License. Distribution of Modified Versions of the Package as Source (4) You may Distribute your Modified Version as Source (either gratis or for a Distributor Fee, and with or without a Compiled form of the Modified Version) provided that you clearly document how it differs from the Standard Version, including, but not limited to, documenting any non-standard features, executables, or modules, and provided that you do at least ONE of the following: (a) make the Modified Version available to the Copyright Holder of the Standard Version, under the Original License, so that the Copyright Holder may include your modifications in the Standard Version. (b) ensure that installation of your Modified Version does not prevent the user installing or running the Standard Version. In addition, the Modified Version must bear a name that is different from the name of the Standard Version. (c) allow anyone who receives a copy of the Modified Version to make the Source form of the Modified Version available to others under (i) the Original License or (ii) a license that permits the licensee to freely copy, modify and redistribute the Modified Version using the same licensing terms that apply to the copy that the licensee received, and requires that the Source form of the Modified Version, and of any works derived from it, be made freely available in that license fees are prohibited but Distributor Fees are allowed. Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source (5) You may Distribute Compiled forms of the Standard Version without the Source, provided that you include complete instructions on how to get the Source of the Standard Version. Such instructions must be valid at the time of your distribution. If these instructions, at any time while you are carrying out such distribution, become invalid, you must provide new instructions on demand or cease further distribution. If you provide valid instructions or cease distribution within thirty days after you become aware that the instructions are invalid, then you do not forfeit any of your rights under this license. (6) You may Distribute a Modified Version in Compiled form without the Source, provided that you comply with Section 4 with respect to the Source of the Modified Version. Aggregating or Linking the Package (7) You may aggregate the Package (either the Standard Version or Modified Version) with other packages and Distribute the resulting aggregation provided that you do not charge a licensing fee for the Package. Distributor Fees are permitted, and licensing fees for other components in the aggregation are permitted. The terms of this license apply to the use and Distribution of the Standard or Modified Versions as included in the aggregation. (8) You are permitted to link Modified and Standard Versions with other works, to embed the Package in a larger work of your own, or to build stand-alone binary or bytecode versions of applications that include the Package, and Distribute the result without restriction, provided the result does not expose a direct interface to the Package. Items That are Not Considered Part of a Modified Version (9) Works (including, but not limited to, modules and scripts) that merely extend or make use of the Package, do not, by themselves, cause the Package to be a Modified Version. In addition, such works are not considered parts of the Package itself, and are not subject to the terms of this license. General Provisions (10) Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. (11) If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. (12) This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. (13) This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. (14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.