lib/Object/Tap.pm

   1 package Object::Tap;
   2
   3 use strict;
   4 use warnings;
   5 use base qw(Exporter);
   6
   7 our $VERSION = '1.000006'; # TRIAL
   8
   9 our @EXPORT = qw($_tap);
  10
  11 our $_tap = sub { my ($obj, $call, @args) = @_; $obj->$call(@args); $obj };
  12
  13 1;
  14
  15 =head1 NAME
  16
  17 Object::Tap - Tap into a series of method calls to alter an object
  18
  19 =head1 SYNOPSIS
  20
  21 Instead of writing -
  22
  23   my $thing = My::Class->new(...);
  24
  25   $thing->set_foo(1);
  26
  27 you can instead write -
  28
  29   use Object::Tap;
  30
  31   my $thing = My::Class->new(...)->$_tap(sub { $_[0]->set_foo(1) });
  32
  33 To realise why this might be useful, consider instead -
  34
  35   My::App->new(...)->$_tap(...)->run;
  36
  37 where a variable is thereby not required at all.
  38
  39 You can also pass extra args -
  40
  41   $obj->$_tap(sub { warn "Got arg: $_[1]" }, 'arg');
  42
  43 or use a method name instead of a sub ref -
  44
  45   my $thing = My::Class->new(...)->$_tap(set_foo => 1);
  46
  47 For a 'real' example of how that might be used, one could create and
  48 initialize an L<HTML::TableExtract> object in one go using -
  49
  50   my $te = HTML::TableExtract->new->$_tap(parse => $html);
  51
  52 =head1 AUTHOR
  53
  54 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
  55
  56 =head1 CONTRIBUTORS
  57
  58 None yet. Well volunteered? :)
  59
  60 =head1 COPYRIGHT
  61
  62 Copyright (c) 2014 the Object::Tap L</AUTHOR> and L</CONTRIBUTORS>
  63 as listed above.
  64
  65 =head1 LICENSE
  66
  67 This library is free software and may be distributed under the same terms
  68 as perl itself.
  69
  70 =cut