---
name: "Dispatch::Class"
section: "3pm"
platform: "linux"
package: "libdispatch-class-perl"
version: "0.02-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Dispatch::Class"
---

# Dispatch::Class(3pm)

dispatch on the type (class) of an argument

## 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 *VALUE*s 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 *VALUE*s 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.