NAME

Conjury::Core::Prototype - function prototype checking in Conjury

SYNOPSIS

  require Conjury::Core::Prototype;
  use Carp qw/&croak/;

  $prototype = Conjury::Core::Prototype->new;

  $prototype->required_arg
    (foo_arg1 => sub {
         my ($x, $y) = (shift, undef);
         $y = 'not a HASH reference' unless (ref $x eq 'HASH');
         return $y;
     });

  $prototype->optional_arg
     foo_arg2 => sub {
         my ($x, $y) = (shift, undef);
         $y = 'not a CODE reference' unless (ref $x eq 'CODE');
         return $y;
     });

  sub foo($%) {
      my ($this, %arg) = @_;
      my $error = $prototype->validate(\%arg);
      croak __PACKAGE__, "::foo-- $error" if $error;

      # use $arg{foo_arg1} with confidence that it exists and its value
      # is a HASH reference, and that $arg{foo_arg2} either does not exist,
      # or it exists and its value is a CODE reference.
  }

DESCRIPTION

The Conjury::Core::Prototype module is a general purpose function prototype verifier, included in the Conjury distribution as a convenience.

Use the Conjury::Core::Prototype-new> method to construct an instance of the prototype verifier for a particular function.

Use the required_arg method to add a required argument to the function prototype. Use the optional_arg method to add an optional argument to the function prototype. Both methods require two parameters, the name of the argument, and a reference to a subroutine that validates the argument and returns a descriptive message if the argument violates the prototype.

When the validate method is called on the prototype (with a reference to a hash containing the function arguments), each argument is passed to the parameter verifier function that was associated with the parameter name when the prototype was constructed. If none of the verifiers return a value then the argument list fits the prototype and the validate method returns undefined. Otherwise, the validate method returns an error code suitable for use in a call to croak.

AUTHOR

James Woodyatt <jhw@wetware.com>