NAME
    Object::DOES - override UNIVERSAL::DOES easily

SYNOPSIS
     {
       package Test::Mock::LWP::Simple;
       use Object::DOES;
       our @DOES = qw(LWP::Simple);
       sub get { ... }
       sub head { ... }
     }
 
     foreach my $package (qw/LWP::Simple Test::Mock::LWP::Simple CGI/)
     {
       if ($package->DOES('LWP::Simple'))
       {
         say "$package does LWP::Simple";
       }
    }

DESCRIPTION
    UNIVERSAL says: *"DOES" and "isa" are similar, in that if either is
    true, you know that the object or class on which you call the method can
    perform specific behavior. However, "DOES" is different from "isa" in
    that it does not care how the invocant performs the operations, merely
    that it does. ("isa" of course mandates an inheritance relationship.
    Other relationships include aggregation, delegation, and mocking.)*

    In Perl 5.10, "UNIVERSAL::DOES" was introduced, which recognises that
    you sometimes need to indicate (and test) whether a class performs a
    particular role, but without caring if it uses inheritance to achieve
    it. (In fact, it is almost always more useful to check "DOES" than
    "isa"!)

    However, the built-in "UNIVERSAL::DOES" is essentially just a clone of
    "UNIVERSAL::isa". The intention is that if you want to indicate your
    module does a role, you must provide a custom "DOES" method for your
    package. Fair enough, but this leads to boiler-plate code along the
    lines of:

      sub DOES
      {
        my ($invocant, $role) = @_;
        return 1 if $role eq 'Foo::Version1';
        return 1 if $role eq 'Foo::Version2';
        return $invocant->SUPER::DOES($role);
      }

    But you have to be careful to get things right. At first glance the code
    above looks fine. But imagine our package also inherits from two other
    packages Bar and Baz. And imagine that Bar and Baz both provide custom
    "DOES" methods of their own. "SUPER::DOES" will only call one of those
    custom "DOES" methods.

    This module should help you avoid the headaches of considering all the
    edge cases. All you need to do is:

      use Object::DOES;
      our @DOES = qw(Role1 Role2 Role3); # etc

    There is also an alternative syntax which may be more attractive to some
    people:

      use Object::DOES -role => [qw/Role1 Role2 Role3/];

USING WITH OTHER MODULES
  Object::Role
    Any roles that use the framework provided by Object::Role will
    automatically play nice with Object::DOES. For example:

      {
        package Example::MyRole;
        use base qw/Object::Role/;
        sub import {
          ...
          __PACKAGE__->install_method(foobar => $coderef, $caller);
        }
      }
  
      {
        package Example::MyClass;
        use Example::MyRole;
        use Object::DOES -role => 'Example::MyOtherRole';
        sub new { ... }
      }
  
      my $obj = Example::MyClass->new;
  
      use Test::More tests => 5;
      ok $new->isa('Example::MyClass');
      ok $new->does('Example::MyClass');
      ok $new->does('Example::MyRole');
      ok $new->does('Example::MyOtherRole');
      ok $new->can('foobar');

CAVEATS
    This module is designed to help classes override UNIVERSAL::DOES, but it
    makes no assumption that UNIVERSAL::DOES actually exists.
    UNIVERSAL::DOES was introduced in Perl 5.10, but there is a CPAN module
    UNIVERSAL::DOES that provides an implementation for earlier versions of
    Perl. The simple shim

      *UNIVERSAL::DOES = sub { shift->isa(@_) }
          unless defined &UNIVERSAL::DOES;

    ... is often sufficient if you don't wish to introduce a depedency on
    UNIVERSAL::DOES or Perl 5.10. However, Object::DOES will *not* do this
    for you.

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=Object-DOES>.

SEE ALSO
    UNIVERSAL, UNIVERSAL::DOES.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2011 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

