view release on metacpan or  search on metacpan

lib/Acme/Sub/Parms.pod  view on Meta::CPAN

Examples:

  # Optional 'HASH'
  BindParms : (
      my $data = thing [optional, type=HASH];
  )

  # Required 'Mammal' or 'Bacteria' or 'Virus' object
  BindParms : (
       my $lifeform = organism [type="Mammal Bacteria Virus"];
  )

=back

=over 4

=item default=something | default="some thing with spaces"

The 'default' declaration allows the setting of default values for
optional parameters (it is implicit that if omitted the default value
is undef).

If the value contains whitespace (or if you want the empty string
value), you will need to use quotes around it.

'default' behaves differently for required and optional parameters:

For an optional parameter, it only activates if the parameter is
omitted completely. It will not kick in for a value that is passed
but has the undefined value.

For a required parameter, it only activates if the parameter is
undefined.

=back

=over 4

=item callback=function_name

The 'callback' declaration lets you specify a function name to be used
to perform validation on the parameter(s). 
The syntax is simple: callback=validation_function_name

There is no support for method style calls, only ordinary function calls.

The callback function is called with three
parameters: ($field_name, $field_value, $arguments_anon_hash)

The $field_name and $field_value arguments are obvious,
the $arguments_anon_hash is a 'live' reference to a hash containing
all of the arguments being processed by BindParms block.

Because it is a 'live' hash reference, alterations to the hash will be
reflected in subsequent binding lines and in the final values bound.
This is a powerful, but simultaneously very dangerous feature. Use
this ability with caution. 

The callback must return either a true or a false value (not the
literal words 'true' or 'false' but something that evaluates to
a true or false logical value) and a string with an error message
(if a false value was returned.)

Callback function example:

 # Checking if the field value is an integer
 sub _is_integer {
    my ($field_name, $field_value, $args_hash) = @_;
    unless (defined ($field_value))            { return (0, 'Not defined');    }
    unless (int($field_value) eq $field_value) { return (0, 'Not an integer'); }
    return 1;
 }

Callbacks are a powerful feature that allow you to do complex
validation well beyond the capabilities of the simple BindParms
specifications. If you are finding yourself wishing that the syntax for
BindParms let you do more complicated things, then use a callback.

=back

=head1 CHANGES

 1.03 2020.10.12 - Relicensed under MIT License. Maintainer updated. Build
                   configs updated. Set min version of Perl to 5.6. Added
                   'use warnings'. Misc file permissions updated. Added
                   GitHub repo to metadata.

 1.02 2008.05.17 - Permissions fixes for build tools and added more examples

 1.01 2008.05.16 - Fixed minor permissions problem

 1.00 2008.05.13 - Initial public release.

=head1 ERRORS

Syntactic errors using Acme::Sub::Parms will generally cause
compilation errors near (but probably not exactly at) the line
containing the error. When you see that kind of error, look for a
syntax error in the declaration.

=head1 BUGS

You can't used parameters names containing single or double quotes,
whitespace or the '[' character. Line numbering can sometimes get
thrown off a little in error messages and I haven't been able to figure
a fix out yet. 

=head1 TODO

Handle multiline argument declarations. Handle comments on BindParm
lines. Generate thread-safe parameter parsing code. Handle parameter
names containing single or double quotes, whitespace or the '[' character.
Make error messages always align with the source lines.

=head1 AUTHOR

Jerilyn Franz <cpan@jerilyn.info>

=head1 VERSION

Version 1.03 - 2020.10.12

=head1 COPYRIGHT

Jerilyn Franz

=head1 LICENSE

MIT License

Copyright (c) 2020 Jerilyn Franz

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

=head1 DISCLAIMER

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.

Use of this software in any way or in any form, source or binary,
is not allowed in any country or locale which prohibits disclaimers
of any implied warranties of merchantability or fitness for a particular
purpose or any disclaimers of a similar nature.

IN NO EVENT SHALL I BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL,  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT
LIMITED TO, LOST PROFITS) EVEN IF I HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE

=cut