lib/Devel/REPL/Plugin/OutputCache.pm

   1 use strict;
   2 use warnings;
   3 package Devel::REPL::Plugin::OutputCache;
   4
   5 use Devel::REPL::Plugin;
   6 use namespace::autoclean;
   7
   8 has output_cache => (
   9     is      => 'rw',
  10     isa     => 'ArrayRef',
  11     default => sub { [] },
  12     lazy    => 1,
  13 );
  14
  15 has warned_about_underscore => (
  16     is      => 'rw',
  17     isa     => 'Bool',
  18     default => 0,
  19     lazy    => 1,
  20 );
  21
  22 around 'eval' => sub {
  23     my $orig = shift;
  24     my ($self, $line) = @_;
  25
  26     my $has_underscore = *_{CODE};
  27     if ($has_underscore && !$self->warned_about_underscore) {
  28         warn "OutputCache: Sub _ already defined.";
  29         $self->warned_about_underscore(1);
  30     }
  31     else {
  32         # if _ is removed, then we should warn about it again if it comes back
  33         $self->warned_about_underscore(0);
  34     }
  35
  36     # this needs to be a postfix conditional for 'local' to work
  37     local *_ = sub () { $self->output_cache->[-1] } unless $has_underscore;
  38
  39     my @ret;
  40     if (wantarray) {
  41         @ret = $self->$orig($line);
  42     }
  43     else {
  44         $ret[0] = $self->$orig($line);
  45     }
  46
  47     push @{ $self->output_cache }, @ret > 1 ? \@ret : $ret[0];
  48     return wantarray ? @ret : $ret[0];
  49 };
  50
  51 1;
  52
  53 __END__
  54
  55 =head1 NAME
  56
  57 Devel::REPL::Plugin::OutputCache - remember past results, _ is most recent
  58
  59 =head1 SYNOPSIS
  60
  61     > 21 / 7
  62     3
  63     > _ * _
  64     9
  65     > sub { die "later" }
  66     sub { die "later" }
  67     > _->()
  68     Runtime error: later
  69
  70 =head1 DESCRIPTION
  71
  72 Re-using results is very useful when working in a REPL. With C<OutputCache> you
  73 get C<_>, which holds the past result. The benefit is that you can build up
  74 your result instead of having to type it in all at once, or store it in
  75 intermediate variables. C<OutputCache> also provides
  76 C<< $_REPL->output_cache >>, an array reference of all results in this session.
  77
  78 Devel::REPL already has a similar plugin, L<Devel::REPL::Plugin::History>.
  79 There are some key differences though:
  80
  81 =over 4
  82
  83 =item Input vs Output
  84
  85 C<History> remembers input. C<OutputCache> remembers output.
  86
  87 =item Munging vs Pure Perl
  88
  89 C<History> performs regular expressions on your input. C<OutputCache> provides
  90 the C<_> sub as a hook to get the most recent result, and
  91 C<< $_REPL->output_cache >> for any other results.
  92
  93 =item Principle of Least Surprise
  94
  95 C<History> will replace exclamation points in any part of the input. This is
  96 problematic if you accidentally include one in a string, or in a C<not>
  97 expression. C<OutputCache> uses a regular (if oddly named) subroutine so Perl
  98 does the parsing -- no surprises.
  99
 100 =back
 101
 102 =head1 CAVEATS
 103
 104 The C<_> sub is shared across all packages. This means that if a module is
 105 using the C<_> sub, then there is a conflict and you should not use this
 106 plugin. For example, L<Jifty> uses the C<_> sub for localization. Jifty is the
 107 only known user.
 108
 109 =head1 SEE ALSO
 110
 111 C<Devel::REPL>, C<Devel::REPL::Plugin::History>
 112
 113 =head1 AUTHOR
 114
 115 Shawn M Moore, C<< <sartak at gmail dot com> >>
 116
 117 =head1 COPYRIGHT AND LICENSE
 118
 119 Copyright (C) 2007 by Shawn M Moore
 120
 121 This library is free software; you can redistribute it and/or modify
 122 it under the same terms as Perl itself.
 123
 124 =cut