NAME

Sub::PatMat - call a version of subroutine depending on its arguments

VERSION

This document describes Sub::PatMat version 0.01

SYNOPSIS

  use Sub::PatMat;

  # basics:
  sub fact : when($_[0] <= 1) { 1 }
  sub fact                    { my ($n) = @_; $n*fact($n-1) }
  print fact(6);

  # referring to things other than @_:
  sub mysort : when($a < $b)  { -1 }
  sub mysort : when($a == $b) {  0 }
  sub mysort : when($a > $b)  {  1 }
  print join ", ", sort mysort (3,1,2);

  # intuiting parameter names:
  sub dispatch : when($ev eq "help") { my ($ev) = @_; print "help\n" }
  sub dispatch : when($ev eq "blah") { my ($ev) = @_; print "blah\n" }
  dispatch("help");
  dispatch("blah");
  # no fallback, this will die:
  dispatch("hest");  # dies with "Bad match"

  # silly
  sub do_something : when(full_moon()) { do_one_thing() }
  sub do_something                     { do_something_else() }

DESCRIPTION

The Sub::PatMat module provides the programmer with the ability to define a subroutine multiple times and to specify what version of the subroutine should be called, depending on the parameters passed to it (or any other condition).

This is somewhat similar to argument pattern matching facility provided by many programming languages.

To use argument pattern matching on a sub, the programmer has to specify the when attribute. The parameter to the attribute must be a single Perl expression.

When the sub is called, those expressions are evaluated consequitively until one of them evaluates to a true value. When this happens, the corresponding version of a sub is called.

If none of the expressions evaluates to a true value, a Bad Match exception is thrown.

It is possible to specify a fall-back version of the function by doing one of the following:

specifying when without an expression

specifying when with an empty expression

not specifying the when attribute at all

Please note that it does not make sense to specify any non-fall-back version of the sub after the fall-back version, since such will never be called.

There is an additional limitation for the last form of the fall-back version (the one without the when attribute at all), namely, it must be the last version of the sub defined.

It is possible to specify named sub parameters in the when-expression. This facility is highly experimental and is currently limited to scalar parameters only. The named sub parameters are extracted from expressions of the form

  my (parameter list) = @_;

anywhere in the body of the sub.

BUGS AND LIMITATIONS

The ability to intuit parameter names is very limited and without doubts buggy.

The when attribute condition is limited to a single Perl expression.

SEE ALSO

Sub::PatternMatching, which does a more comprehensive job, but its syntax makes it difficult to use.

TODO

support non-scalar named parameters

add positional parameter matching a la Erlang

AUTHOR

Anton Berezin <tobez@tobez.org>

ACKNOWLEDGEMENTS

Thanks to Dmitry Karasik for discussion.

LICENSE AND COPYRIGHT

Copyright (c) 2007, Anton Berezin <tobez@tobez.org>. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm Sub::PatMat

perl -MCPAN -e shell
install Sub::PatMat