/ 
Sub-Multi-Tiny-0.000013
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 0 GitHub stars
/ README.md

Build Status

NAME

Sub::Multi::Tiny - Multisubs/multimethods (multiple dispatch) yet another way!

SYNOPSIS

{
    package main::my_multi;     # We're making main::my_multi()
    use Sub::Multi::Tiny qw($foo $bar);     # All possible params

    sub first :M($foo, $bar) {  # sub's name will be ignored,
        return $foo ** $bar;    # but can't match the one we're making
    }

    sub second :M($foo) {
        return $foo + 42;
    }

}

# Back in package main, my_multi() is created just before the run phase.
say my_multi(2, 5);     # -> 32
say my_multi(1295);     # -> 1337

The default dispatcher dispatches solely by arity, and only one candidate can have each arity. For more flexible dispatching, see Sub::Multi::Tiny::Dispatcher::TypeParams.

DESCRIPTION

Sub::Multi::Tiny is a library for making multisubs, aka multimethods, aka multiple-dispatch subroutines. Each multisub is defined in a single package. Within that package, the individual implementations ("impls") are subs tagged with the :M attribute. The names of the impls are preserved but not used specifically by Sub::Multi::Tiny.

Within a multisub package, the name of the sub being defined is available for recursion. For example (using where, supported by Sub::Multi::Tiny::Dispatcher::TypeParams):

{
    package main::fib;
    use Sub::Multi::Tiny qw(D:TypeParams $n);
    sub base  :M($n where { $_ <= 1 })  { 1 }
    sub other :M($n)                    { $n * fib($n-1) }
}

This code creates function fib() in package main. Within package main::fib, function fib() is an alias for main::fib(). It's easier to use than to explain!

FUNCTIONS

import

Sets up the package that uses it to define a multisub. The parameters are all the parameter variables that the multisubs will use. import creates these as package variables so that they can be used unqualified in the multisub implementations.

A parameter D:Dispatcher can also be given to specify the dispatcher to use --- see "CUSTOM DISPATCH".

Also sets "$VERBOSE" in Sub::Multi::Tiny::Util if the environment variable SUB_MULTI_TINY_VERBOSE has a truthy value. If the SUB_MULTI_TINY_VERBOSE value is numeric, $VERBOSE is set to that value; otherwise, $VERBOSE is set to 1.

CUSTOM DISPATCH

This module includes a default dispatcher (implemented in Sub::Multi::Tiny::Dispatcher::Default. To use a different dispatcher, define or import a sub MakeDispatcher() into the package before compilation ends. That sub will be called to create the dispatcher. For example:

{
    package main::foo;
    use Sub::Multi::Tiny;
    sub MakeDispatcher { return sub { ... } }
}

or

{
    package main::foo;
    use Sub::Multi::Tiny;
    use APackageThatImportsMakeDispatcherIntoMainFoo;
}

As a shortcut, you can specify a dispatcher on the use line. For example:

use Sub::Multi::Tiny qw(D:Foo $var);

will use dispatcher Sub::Multi::Tiny::Dispatcher::Foo. Any name with a double-colon will be used as a full package name. E.g., D:Bar::Quux will use dispatcher Bar::Quux. If Foo does not include a double-colon, Sub::Multi::Tiny::Dispatcher:: will be prepended.

DEBUGGING

For extra debug output, set "$VERBOSE" in Sub::Multi::Tiny::Util to a positive integer. This has to be set at compile time to have any effect. For example, before creating any multisubs, do:

use Sub::Multi::Tiny::Util '*VERBOSE';
BEGIN { $VERBOSE = 2; }

RATIONALE

SEE ALSO

I looked at these but decided not to use them for the following reasons:

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Sub::Multi::Tiny

You can also look for information at:

BUGS

AUTHOR

Chris White cxw@cpan.org

LICENSE

Copyright (C) 2019 Chris White cxw@cpan.org

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