/ 
Capture-Attribute-0.003
River stage one • 1 direct dependent • 1 total dependent
/ Capture::Attribute

NAME

Capture::Attribute - s/return/print/g

SYNOPSIS

use Capture::Attribute;

sub foobar :Capture {
  print "Hello World\n";
}

my $result = foobar();
$result =~ s/World/Planet/;
print "$result";   # says "Hello Planet"

DESCRIPTION

Sometimes you write a function that needs to build a long string via a convoluted series of conditional statements, loops and so on. I tend to end up defining a variable $return at the top of the code, concatenating bits to it as required, and then return it at the end. For example:

sub count_to_10 {
  my $return = "Listen to me count!\n";
  foreach (1..10) {
    $return .= "$_\n";
    $return .= "Half-way there!\n" if $_==5;
  }
  $return .= "All done!\n";
  return $return;
}

Mail::Message->new(
  To      => 'teacher@example.com',
  From    => 'student@example.com',
  Subject => 'I can count!',
  data    => count_to_ten(),
  )->send;

Capture::Attribute simplifies this pattern by capturing all output to STDOUT, so you can use STDOUT as a place to capture each part of the string.

sub count_to_10 :Capture {
  say "Listen to me count!";
  foreach (1..10) {
    say $_;
    say "Half-way there!" if $_==5;
  }
  say "All done!";
}

Mail::Message->new(
  To      => 'teacher@example.com',
  From    => 'student@example.com',
  Subject => 'I can count!',
  data    => count_to_ten(),
  )->send;

Doesn't that look nicer?

Within a sub marked with the ":Capture" attribute, all data that would be printed is captured instead. When the sub is finished, the return value is ignored and the captured text is returned instead.

The return keyword still works just fine for its control flow purpose inside a captured sub. The return value just doesn't get returned.

How does it work?

When you use Capture::Attribute, then at BEGIN time (see perlmod) your package will be automatically made into an subclass of Capture::Attribute.

At CHECK time (again perlmod), Capture::Attribute will then use Attribute::Handlers to wrap each sub marked with the ":Capture" attribute with a sub that captures its output via Capture::Tiny, and returns the output.

At INIT time (again perlmod), Capture::Attribute then removes itself from your package's @ISA, thus your package is no longer a subclass of Capture::Attribute. (It would be nice if the subclassing could be avoided altogether, but alas this seems to be the way Attribute::Handlers works.)

The ":Capture" Attribute

There are actually various options you can use on the ":Capture" attribute. They are mostly useless.

:Capture(STDOUT)

This is the default. Captures STDOUT.

:Capture(STDERR)

Captures STDERR instead of STDOUT.

:Capture(MERGED)

Captures both STDOUT and STDERR, merged into one. Because of buffering, lines from different handles may interleave differently than expected.

:Capture(STDOUT,STDERR)

Capture both STDOUT and STDERR. In scalar context, returns STDOUT. In List context returns both.

sub foo :Capture(STDOUT,STDERR) {
  print "World\n";
  warn "Hello\n";
}
my ($hello, $world) = map { chomp;$_ } foo();

:Capture(STDERR,STDOUT)

Capture both STDOUT and STDERR. In scalar context, returns STDERR. In List context returns both.

CAVEATS

Subclassing

As mentioned above, Capture::Attribute temporarily installs itself as a superclass of your class. If your class has subs named any of the following, they may override the Capture::Attribute versions, and bad stuff may happen.

  • ATTR

  • Capture

  • MODIFY_CODE_ATTRIBUTES

  • any sub matching the expresssion /^_ATTR_CODE_/

Accessing the real return value

sub quux :Capture
{
  print "foo";
  return "bar";
}

say quux();                             # says "foo"
say Capture::Attribute->return->value;  # says "bar"

The Capture::Attribute->return class method gives you the real return value from the most recently captured sub. This is a Capture::Attribute::Return object.

However, this section is listed under CAVEATS for a good reason. The fact that a sub happens to use the ":Capture" attribute should be considered private to it. The caller shouldn't consider there to be any difference between:

sub foo :Capture { print "foo" }

and

sub foo { return "foo" }

If the caller of the captured sub goes on to inspect Capture::Attribute->return, then this assumes an implementation detail of the captured sub, which breaks encapsulation.

Adding a ":Capture" attribute to somebody else's function

So you want to do something like:

add_attribute(\&Some::Module::function, ':Capture(STDOUT)');

Here's how:

# Declare a generic wrapper
sub CAP :Capture { (shift)->(@_) }

# Wrap Some::Module::function in our wrapper.
my $orig = \&Some::Module::function;
local *Some::Module::function = sub { CAP($orig, @_) };

Though you are probably better off investigating Capture::Tiny.

Call stack

Capture::Attribute adds two extra frames to the call stack, and Capture::Tiny adds (it seems) two more again. So any code that you capture will see them quite clearly in the call stack if they decide to look. They'll show up in stack traces, etc.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Capture-Attribute.

SEE ALSO

Capture::Tiny, "Subroutine Attributes" in perlsub.

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.