NAME

Sub::NamedParams - Perl extension for using named arguments with any sub

SYNOPSIS

  use Sub::NamedParams qw/wrap/;
  wrap ( 
    sub   => some_sub_name,
    names => [qw/ names for your arguments /],
    default => {
      your => 1,
      arguments => undef
    }
  );

  some_sub_name( {
    names => [qw/Bill Mary Ovid/],
    for   => '??'
  } );
    

DESCRIPTION

Sometimes it can be a pain to work with a sub that takes a long list of arguments. Trying to remember their order can be annoying, but it gets worse if some of the arguments are optional. This module allows you to use named arguments with any subroutine. It has only one function, Sub::NamedParams::wrap, which has two mandatory and three optional arguments.

EXPORT

Exports wrap on demand.

wrap

Call this function to "wrap" a function in a new function which takes names parameters.

sub

Required. This argument is the name of the sub (not a reference to it. If just the sub name is provided, the calling package is assumed to be the correct one. Otherwise, a fully-qualified sub name may be used.

This will use the calling package.

  wrap(
    sub   => 'process_report',
    names => [qw/ report summary totals /]
  );

This will use Some::Package::.

  wrap(
    sub   => 'Some::Package::process_report',
    names => [qw/ report summary totals /]
  );

names

Required. This should be an array ref with the names of the arguments in the order in which they are supplied to the sub. See examples for sub.

target

Optional. If you're working on a collaborative project, Billy Joe Jim Bob is going to rightfully get medieval on your po' self when all of his subroutine calls start failing with mysterious error messages. To get around this, you can specify a target parameter. This will leave the original subroutine unchanged and create a "new" subroutine exactly like the old one, but requiring the named parameters that you specify. This is strongly recommended if you will be working with others.

hashref

Optional. If you would rather supply a list instead of a hashref, set this to false. The default is true.

default

Optional. This is a hashref with default values for any argument that you don't supply when you call the subroutine.

Example

  use Data::Dumper;
  use Sub::NamedParams qw/wrap/;
  wrap(
    sub      => foo,
    names    => [qw/ first second third /],
    hashref  => 1,
    default  => {
      second => 'deux'
    }
  );

  foo( {first => 1, third => 3} );

  sub foo {
    print Dumper \@_;
  }

Another example:

 use Sub::NamedParams qw/wrap/;
 
 sub foo { $_[0] + 1 }

 wrap(
  sub    => 'foo',
  names  => [qw/arg/],
  target => 'bar'
 );

 # the following two are identical:
 print foo( 3 );
 print bar( {arg => 3} );

EXPORT

None by default. Adding wrap to the import list will import it.

CAVEATS

Once wrapped, you may not "rewrap" a sub. Attempting to do so will throw an exception. Further, the target parameter may not specify a wrapped or pre-existing subroutine.

This module works on functions, not object methods. It should be relatively easy to add this, but I have generally found object interfaces to be cleaner, so I felt there was less of a need for this.

Hash keys passed in that were not listed in the original 'names' list will be silently discarded.

BUGS

2002-04-29 Fixed bug with global value sometimes being overwritten in calling or target namespace. Thanks to chromatic for pointing that out.

AUTHOR

Copyright 2002, Curtis "Ovid" Poe <poec@yahoo.com>. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl.