1Role::Commons::Tap(3) User Contributed Perl DocumentationRole::Commons::Tap(3)
2
3
4

NAME

6       Role::Commons::Tap - an object method which helps with chaining,
7       inspired by Ruby
8

SYNOPSIS

10          # This fails because the "post" method doesn't return
11          # $self; it returns an HTTP::Request object.
12          #
13          LWP::UserAgent
14             -> new
15             -> post('http://www.example.com/submit', \%data)
16             -> get('http://www.example.com/status');
17
18          # The 'tap' method runs some code and always returns $self.
19          #
20          LWP::UserAgent
21             -> new
22             -> tap(post => [ 'http://www.example.com/submit', \%data ])
23             -> get('http://www.example.com/status');
24
25          # Or use a coderef...
26          #
27          LWP::UserAgent
28             -> new
29             -> tap(sub { $_->post('http://www.example.com/submit', \%data) })
30             -> get('http://www.example.com/status');
31

DESCRIPTION

33       DO NOT USE THIS MODULE! Use Object::Tap or Object::Util instead. They
34       are not drop-in replacements, but a far more sensible way to have a
35       "tap" method.
36
37       This module has nothing to do with the Test Anything Protocol (TAP, see
38       Test::Harness).
39
40       This module is a role for your class, providing it with a "tap" method.
41       The "tap" method is an aid to chaining. You can do for example:
42
43          $object
44             ->tap( sub{ $_->foo(1) } )
45             ->tap( sub{ $_->bar(2) } )
46             ->tap( sub{ $_->baz(3) } );
47
48       ... without worrying about what the "foo", "bar" and "baz" methods
49       return, because "tap" always returns its invocant.
50
51       The "tap" method also provides a few shortcuts, so that the above can
52       actually be written:
53
54          $object->tap(foo => [1], bar => [2], baz => [3]);
55
56       ... but more about that later. Anyway, this module provides one method
57       for your class - "tap" - which is described below.
58
59   tap(@arguments)
60       This can be called as an object or class method, but is usually used as
61       an object method.
62
63       Each argument is processed in the order given. It is processed
64       differently, depending on the kind of argument it is.
65
66       Coderef arguments
67
68       An argument that is a coderef (or a blessed argument that overloads
69       "&{}" - see overload) will be executed in a context where $_ has been
70       set to the invocant of the tap method "tap". The return value of the
71       coderef is ignored. For example:
72
73          {
74             package My::Class;
75             use Role::Commons qw(Tap);
76          }
77          print My::Class->tap(
78             sub { warn uc $_; return 'X' },
79          );
80
81       ... will warn "MY::CLASS" and then print "My::Class".
82
83       Because each argument to "tap" is processed in order, you can provide
84       multiple coderefs:
85
86          print My::Class->tap(
87             sub { warn uc $_; return 'X' },
88             sub { warn lc $_; return 'Y' },
89          );
90
91       String arguments
92
93       A non-reference argument (i.e. a string) is treated as a shortcut for a
94       method call on the invocant. That is, the following two taps are
95       equivalent:
96
97          $object->tap( sub{$_->foo(@_)} );
98          $object->tap( 'foo' );
99
100       Arrayref arguments
101
102       An arrayref is dereferenced yielding a list. This list is passed as an
103       argument list when executing the previous coderef argument (or string
104       argument). The following three taps are equivalent:
105
106          $object->tap(
107             sub { $_->foo('bar', 'baz') },
108          );
109          $object->tap(
110             sub { $_->foo(@_) },
111             ['bar', 'baz'],
112          );
113          $object->tap(
114             foo => ['bar', 'baz'],
115          );
116
117       Scalar ref arguments
118
119       There are a handful of special scalar ref arguments that are supported:
120
121       "\"EVAL""
122           This indicates that you wish for all subsequent coderefs to be
123           wrapped in an "eval", making any errors that occur within it non-
124           fatal.
125
126              $object->tap(\"EVAL", sub {...});
127
128       "\"NO_EVAL""
129           Switches back to the default behaviour of not wrapping coderefs in
130           "eval".
131
132              $object->tap(
133                 \"EVAL",
134                 sub {...},   # any fatal errors will be caught and ignored
135                 \"NO_EVAL",
136                 sub {...},   # fatal errors are properly fatal again.
137              );
138

BUGS

140       Please report any bugs to
141       <http://rt.cpan.org/Dist/Display.html?Queue=Role-Commons>.
142

SEE ALSO

144       Object::Tap, Object::Util.
145
146       Role::Commons.
147
148       <http://tea.moertel.com/articles/2007/02/07/ruby-1-9-gets-handy-new-method-object-tap>,
149       <http://prepan.org/module/3Yz7PYrBLN>.
150

AUTHOR

152       Toby Inkster <tobyink@cpan.org>.
153

155       This software is copyright (c) 2012, 2014 by Toby Inkster.
156
157       This is free software; you can redistribute it and/or modify it under
158       the same terms as the Perl 5 programming language system itself.
159

DISCLAIMER OF WARRANTIES

161       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
162       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
163       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
164
165
166
167perl v5.38.0                      2023-07-21             Role::Commons::Tap(3)
Impressum