NAME

Sub::Context - Perl extension to dispatch subroutines based on their calling context

SYNOPSIS

        use Sub::Context sensitive =>
        {
                void    => \&whine,
                scalar  => \&cry,
                list    => \&weep,
        };

DESCRIPTION

Sub::Context dispatches subroutine calls based on their calling context. This can be handy for converting return values or for throwing warnings or even fatal errors. For example, you can prohibit a function from being called in void context. Instead of playing around with wantarray() on your own, this modules does it for you.

EXPORT

None by default. use the module and its custom import() function will handle things nicely for you.

IMPORTING

By convention, Sub::Context takes a list of arguments in pairs. The first item is the name of a subroutine. The second item in the list is a reference to a hash of options for that subroutine. For example, to create a new sub named penguinize() in the calling package, with three existing subroutines for each of the three types of context (void, list, and scalar), write:

        use Sub::Context
                penguinize =>
                {
                        void    => \&void_penguinize,
                        list    => \&list_penguinize,
                        scalar  => \&scalar_penguinize,
                };

You can provide your own subroutine references, of course:

        use Sub::Context
                daemonize =>
                {
                        list => sub { paint_red( penguinize() ) },
                };

If you are creating a new subroutine and do not provide a subroutine reference for a context type, Sub::Context will helpfully croak() when you call the sub with the unsupported context. You can also provide a scalar instead of a subref, which will then be part of the error message:

        use Sub::Context 
                daemonize => {
                        list => sub { paint_red( penguinize(@_) ) },
                        void => 'daemons get snippy in void context',
                };

You don't have to create new subs. You can wrap existing subs, as well. that in this case, if you do not provide a new behavior for a context type, the old behavior will persist. For example, if you have an existing sub that returns a string of words, you can say:

        use Sub::Context
                get_sentence =>
                {
                        list => sub { split(' ', get_sentence(@_) },
                        void => 'results too good to throw away',
                };

Called in scalar context, get_sentence() will behave like it always has. In list context, it will return a list of words (for whatever definition of 'words' the regex provides). In void context, it will croak with the provided error message.

TODO

Allow unwrapping of wrapped subs (localized?)

World domination?

AUTHOR

chromatic, chromatic at wgz dot org

COPYRIGHT

Copyright (c) 2001, 2005 by chromatic.

This program is free software. You can use, modify, and distribute it under the same terms as Perl 5.8.x itself.

SEE ALSO

perl, wantarray, Want.