view release on metacpan or  search on metacpan

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

'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
to any validation specifications.

If this flag is used, then parameters will be bound, callbacks and
defaults applied, but validation checking will be disabled. This
provides a significant performance boost to parameter processing
in mature code that doesn't need runtime parameter assertion checking.

=item :normalize

This flags that bound parameters should ignore the difference between
upper and lowercase names for parameters. This permits the caller to
use MixedCase, UPPERCASE, or lowercase parameters names interchangeably
(with a noticable performance penalty).

=item :dump_to_stdout

This signals that the code should be printed to STDOUT as the source
filter runs. This is useful primarily to see what the source filter
actually does, for debugging, or if you want to capture the transformed
code so it can be used B<without> needing Acme::Sub::Parms to be
installed at all.

This would typically be used by setting the flag on the
'use Acme::Sub::Parms', and then running 
  perl -c sourcefile > outputfile
(with 'sourcefile' and 'outputfile' replaced with the appropriate
filenames).

=back

=head1 Parameter Binding and Validation

A syntax is available to perform argument validation. This is both fast
and powerful, but has some caveats.

The basic format is as follows

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

The format of each line of the binding declaration is formatted as:

   <stuff being assigned to> : parameter_name [binding options];

The simplest possible binding is like the following:

 BindParms : (
    my $somevariable : parameter_name;
 )

That declares that the required named parameter 'parameter_name' will
be bound to the lexical variable $somevariable.

parameter_name may B<NOT> contain whitespace, single or double quotes,
or a left bracket ('[') character. It must be a bare (unquoted) string.

Pretty much any expression that is legal to assign to may be used for
the left side. With the caveat that it B<CANNOT> contain the literal
string ' : ' (whitespace colon whitespace) as that will confuse the
line parser. This excludes the use of the trinary ( statement ? value : value)
conditional operator on the left side, but you shouldn't need it in this
context since there is sufficient power in the binding options to cover
the cases where you might want it.

If you need to use the " : " string in an embedded quoted literal
string, use backslash escaping on it:

Bad:
  my $thing{" : "}   : something [optional];

Good:
  my $thing{" \: "} : something [optional];

Pretty much anything else you want to do on the left of the ':' binding
is fine as long as it is legal to be assigned to.

Ex.
  BindParms : (
    my Dog $rover  : dog_record [required];
  }

The options available for parameter binding are as follows:

=head1 Parameter Validation

=over 4

=item Optional/Required Parameters

Optional vs Required is flagged by either (surprise) B<optional> or
B<required> in the parameter options declaration.

The parameter options declaration is the section between the '[' and ']'
characters after the name of field being bound.

 # Optional parameter
 BindParms : (
       my $handle : handle [optional];
 )

 # Required parameter
 BindParms : (
       my $handle : handle [required];
 )

'required' specifies validation code to the bind that verifies that the
'handle' parameter was in fact passed and causes a C<confess> at that
line if it was not passed.  This does not ensure that the parameter has
a defined value - only that it was passed.

If neither 'required' or 'optional' is specified, then 'required' is defaulted.

Example of default required parameters:

 sub a_subroutine {
    BindParms : (
        my $handle : handle;
        my $thing  : thing;
    )
    #....
 )

=back

=over 4

=item is_defined

The 'is_defined' declaration generates a validation requirement that the
parameter B<IF PRESENT> must not have an undefined value - passing an
undefined value results in a runtime 'croak'.

If the parameter is B<optional> it may still be omitted - but must not have an undefined value if passed.

If the the parameter is B<required> then it B<must> be present, B<AND> must not have an undefined value.

Example:

  # Optional but may not be undefined if passed
  BindParms : (
      my $handle : handle [optional, is_defined];
  )

  # Required and may not be undefined
  BindParms : (
      my $handle : handle [required, is_defined];
  )

=back