NAME

       Dispatch::Class - dispatch on the type (class) of an argument

SYNOPSIS

         use Dispatch::Class qw(
           class_case
           dispatch
         );

         # analyze the class of an object
         my $analyze = class_case(
           'Some::Class'  => 1,
           'Other::Class' => 2,
           'UNIVERSAL'    => "???",
         );
         my $foo = $analyze->(Other::Class->new);  # 2
         my $bar = $analyze->(IO::Handle->new);    # "???"
         my $baz = $analyze->(["not an object"]);  # undef

         # build a dispatcher
         my $dispatch = dispatch(
           'Dog::Tiny' => sub { ... },  # handle objects of the class Dog::Tiny
           'Dog'       => sub { ... },
           'Mammal'    => sub { ... },
           'Tree'      => sub { ... },

           'ARRAY'     => sub { ... },  # handle array refs

           ':str'      => sub { ... },  # handle non-reference strings

           '*'         => sub { ... },  # handle any value
         );

         # call the appropriate handler, passing $obj as an argument
         my $result = $dispatch->($obj);

DESCRIPTION

       This module offers a (mostly) simple way to check the class of an object and handle specific cases
       specially.

   Functions
       The following functions are available and can be imported on request:

       "class_case"
           "class_case"  takes a list of "KEY, VALUE" pairs and returns a code reference that (when called on an
           object) will analyze the object's class according  to  the  rules  described  below  and  return  the
           corresponding VALUE of the first matching KEY.

           Example:

             my $subref = class_case(
               KEY1 => VALUE1,
               KEY2 => VALUE2,
               ...
             );
             my $value = $subref->($some_object);

           This  will  check  the  class  of  $some_object  against  "KEY1", "KEY2", ... in order and return the
           corresponding "VALUEn" of the first match. If no key matches, an  empty  list/undef  is  returned  in
           list/scalar context, respectively.

           The following things can be used as keys:

           "*" This will match any value. No actual check is performed.

           ":str"
               This special key will match any non-reference.

           "SCALAR", "ARRAY", "HASH", ...
               These  values  match  references  of  the  specified  type  even if they aren't objects (i.e. not
               "bless"ed). That is, for unblessed references the string returned by "ref" is compared with "eq".

           CLASS
               Any other string is interpreted as a class name and matches if the input value is an  object  for
               which  "$obj->isa($CLASS)"  is  true.  To  match  any kind of object (blessed value), use the key
               'UNIVERSAL'.

               Starting with Perl 5.10.0 Perl supports checking for  roles  with  "DOES",  so  "Dispatch::Class"
               actually  uses  "$obj->DOES($CLASS)"  instead  of "isa".  This still returns true for normal base
               classes but it also accepts roles that have been composed into the object's class.

       "dispatch"
           This works like "class_case"  above,  but  the  VALUEs  must  be  code  references  and  get  invoked
           automatically:

             sub dispatch {
               my $analyze = class_case @_;
               sub {
                 my ($obj) = @_;
                 my $handler = $analyze->($obj) or return;
                 $handler->($obj)
               }
             }

           That is, the matching object is passed on to the matched VALUEs and the return value of the inner sub
           is whatever the handler returns (or the empty list/undef if no KEY matches).

       This module uses "Exporter::Tiny", so you can rename the imported functions at "use" time.

SEE ALSO

       Exporter::Tiny

AUTHOR

       Lukas Mai, "<l.mai at web.de>"

COPYRIGHT & LICENSE

       Copyright 2013, 2014 Lukas Mai.

       This  program  is  free software; you can redistribute it and/or modify it under the terms of either: the
       GNU General Public License as published by the Free Software Foundation; or the Artistic License.

       See http://dev.perl.org/licenses/ for more information.

perl v5.20.2                                       2014-11-29                               Dispatch::Class(3pm)