view release on metacpan or  search on metacpan

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

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

=over 4

=item can=method | can="method1 method2 method3 ..."