NAME
    Object::Tap - a ruby-inspired tap method for your objects

SYNOPSIS
     {
       package My::Class;
       use Object::Tap;
       sub new { ... }
       sub dump { ... ; return $string }
     }
 
     my $obj    = My::Class->new;
     my $return = $obj->tap(sub { warn "here"; return "blah" });
 
     use Test::More;
     is $obj, $return, "tap method returns the invocant";

DESCRIPTION
    This module has nothing to do with the Test Anything Protocol (TAP, see
    Test::Harness).

    This module is a (non-Moose) role for your class, providing it with a
    "tap" method. The "tap" method is an aid to chaining. You can do for
    example:

     $object
       ->tap( sub{ $_->foo(1) } )
       ->tap( sub{ $_->bar(2) } )
       ->tap( sub{ $_->baz(3) } );

    ... without worrying about what the "foo", "bar" and "baz" methods
    return, because "tap" always returns its invocant.

    The "tap" method also provides a few shortcuts, so that the above can
    actually be written:

     $object->tap(foo => [1], bar => [2], baz => [3]);

    ... but more about that later. Anyway, this module provides one method
    for your class - "tap" - which is described below.

  "tap(@arguments)"
    This can be called as an object or class method, but is usually used as
    an object method.

    Each argument is processed in the order given. It is processed
    differently, depending on the kind of argument it is.

   Coderef arguments
    An argument that is a coderef (or a blessed argument that overloads
    "&{}" - see overload) will be executed in a context where $_ has been
    set to the invocant of the tap method "tap". The return value of the
    coderef is ignored. For example:

     { package My::Class; use Object::Tap; }
     print My::Class->tap( sub { warn uc $_; return 'X' } );

    ... will warn "MY::CLASS" and then print "My::Class".

    Because each argument to "tap" is processed in order, you can provide
    multiple coderefs:

     print My::Class->tap(
       sub { warn uc $_; return 'X' },
       sub { warn lc $_; return 'Y' },
       );

   String arguments
    A non-reference argument (i.e. a string) is treated as a shortcut for a
    method call on the invocant. That is, the following two taps are
    equivalent:

     $object->tap( sub{$_->foo(@_)} );
     $object->tap( 'foo' );

   Arrayref arguments
    An arrayref is dereferenced yielding a list. This list is passed as an
    argument list when executing the previous coderef argument (or string
    argument). The following three taps are equivalent:

     $object->tap(
       sub { $_->foo('bar', 'baz') },
       );
     $object->tap(
       sub { $_->foo(@_) },
       ['bar', 'baz'],
       );
     $object->tap(
       foo => ['bar', 'baz'],
       );

   Scalar ref arguments
    There are a handful of special scalar ref arguments that are supported:

    "\"EVAL"", "Object::Tap::EVAL"
        This indicates that you wish for all subsequent coderefs to be
        wrapped in an "eval", making any errors that occur within it
        non-fatal.

         $object->tap(\"EVAL", sub {...});

        In case you dislike weird scalar references in your code, this
        should also work:

         $object->tap(Object::Tap::EVAL, sub {...});

    "\"NO_EVAL"", "Object::Tap::NO_EVAL"
        Switches back to the default behaviour of not wrapping coderefs in
        "eval".

         $object->tap(
           Object::Tap::EVAL,
           sub {...},   # any fatal errors will be caught and ignored
           Object::Tap::NO_EVAL,
           sub {...},   # fatal errors are properly fatal again.
           );

  Importing from Object::Tap
    Object::Tap provides a number of cool import features. Firstly, what if
    you like the idea of a "tap" method but don't like the name "tap"? Easy,
    just give the method a different name:

     use Object::Tap 'execute_and_return_self'; # silly long name

    You can even create multiple methods:

     use Object::Tap qw/execute_and_return_self exec_return/;

    You can quite easily install "tap" into somebody else's class too:

     use Object::Tap -package => 'LWP::UserAgent';

    or multiple classes:

     use Object::Tap -package => [
       qw/LWP::UserAgent HTTP::Response HTTP::Request/
       ];

    or even all classes (though this is probably not desirable):

      use Object::Tap -package => 'UNIVERSAL';

    And these options can be combined:

     use Object::Tap 'exec_return', -package => 'UNIVERSAL';

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

SEE ALSO
    <http://tea.moertel.com/articles/2007/02/07/ruby-1-9-gets-handy-new-meth
    od-object-tap>, <http://prepan.org/module/3Yz7PYrBLN>.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2012 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.

