view release on metacpan or  search on metacpan

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

Acme::Sub::Parms - Provides simple, fast parsing of named subroutine parameters

=head1 SYNOPSIS

 use Acme::Sub::Parms;

 ################
 # A simple function with two required parameters

 sub simple_bind_parms_function {
     BindParms : (
         my $handle : handle;
         my $thing  : thing;
     )

     #...
 }

 ################
 # A complex method interface with multiple parameters
 # and validation requirements

 sub complex_bind_parms_function {
     my $self = shift;

     BindParms : (
         my $handle         : handle  [required, is_defined, can=param];
         my $thing          : thing   [optional, isa=CGI::Minimal];
         my $another_thing  : another [optional, type=SCALAR, callback=_legal_thing];
         my $yathing        : yathing [optional, is_defined];
         my $defaulted      : dthing  [optional, default="help me"];
     )

     #...
 }

=head1 DESCRIPTION

Acme::Sub::Parms uses a source filter to rewrite the code during the
module load with efficient inline parameter processing code that
handles some common cases for simple Perl style named parameter key/value
parameter lists. It can handle either case-sensitive or case-insensitive
parameters as desired.

In essence, it provides some syntactic sugar for parameter declaration
and validation.

Typical usage is follows:

  sub a_function {
    BindParms : (
        my $somevariable    : parameter_name         [required];
        my $anothervariable : another_parameter_name [optional];
    )

    #...
  }

B<IMPORTANT:> The whitespace before and after the ':' in the 
'BindParms : (' starting declaration B<IS NOT> optional.

Second, the entire declaration must be on one line: No line breaks in
the middle or other code on the line.

You can make the passed parameter names case insensitive by adding the
':normalize' option on the 'use' line.

Acme::Sub::Parms does not handle anonymous hashes for parameters. It
expects parameters lists to be passed as 'flat' lists. This is due to
performance issues. The additional code required to handle both 'flat'
and 'anon hash' parameters has a noticable performance hit for simple
cases. Since one of the goals of this module is to be B<fast> and a
survey of existing modules indicates most authors use 'flat' parameters
lists, that is what Acme::Sub::Parms does as well. If you prefer using
anon hashes. just dereference them before using them to call.

Good Example:

 some_function('a_parm' => 'value);

 sub some_function {
	BindParms : (
		my $variable : a_parm;
        )

    #.....
 }

Example of dereferencing anon hash parms:

 my $parms = { 'a_parm' => 'value' };
 some_function(%$parms);

Broken Examples:

 some_function({ 'a_parm' => 'value} }); # WILL NOT WORK

 my $parms = { 'a_parm' => 'value' };
 some_function($parms);  # WILL NOT WORK


 sub some_function {
	BindParms : (
		my $variable : a_parm;
        )

    #.....
 }

=head1 'use' options

There are three compile-time 'use' options available.

  use Acme::Sub::Parms qw(:no_validation :normalize :dump_to_stdout);

=over 4

=item :no_validation

This flags that bound parameters should B<NOT> be validated according