IO::Ca...:Stdout(3pm)

✨ NAME ✨

IO::Capture::Stdout — catch literally everything that gets printed to `STDOUT, bestie 💅

This one lives in the User Contributed Perl Documentation, and it's giving very much "I intercept your prints" energy. 🎀

---

🌸 SYNOPSIS 🌸

Okay so here's the whole vibe in one go:

# Generic example (Just to give the overall view)
use IO::Capture::Stdout;

$capture = IO::Capture::Stdout->new();

$capture->start();          # STDOUT Output captured
print STDOUT "Test Line One\n";
print STDOUT "Test Line Two\n";
print STDOUT "Test Line Three\n";
$capture->stop();           # STDOUT output sent to wherever it was before 'start'

# In 'scalar context' returns next line
$line = $capture->read;
print "$line";         # prints "Test Line One"

$line = $capture->read;
print "$line";         # prints "Test Line Two"

# move line pointer to line 1
$capture->line_pointer(1);

$line = $capture->read;
print "$line";         # prints "Test Line One"

# Find out current line number
$current_line_position = $capture->line_pointer;

# In 'List Context' return an array(list)
@all_lines = $capture->read;

# More useful example 1 - "Using in module tests"
#  Note: If you don't want to make users install
#        the IO::Capture module just for your tests,
#        you can just install in the t/lib directory
#        of your module and use the lib pragma in
#        your tests.

use lib "t/lib";
use IO::Capture::Stdout;

use Test::More;

my $capture =  IO::Capture::Stdout->new;
$capture->start

# execute with a bad parameter to make sure get
# an error.

ok( ! $test("Bad Parameter") );

$capture->stop();

---

🦋 DESCRIPTION 🦋

So IO::Capture::Stdout is a derived class — it comes from the abstract class IO::Capture, and you should go look at IO::Capture if you want the full lore. The whole point of this module (the name is lowkey a spoiler) is to grab any output sent to STDOUT. Snatch it. Keep it. 💅

Once the capture is stopped, the STDOUT filehandle gets reset back to wherever it was before — like nothing ever happened. So say you'd previously redirected it into a file: the moment IO::Capture->stop gets called, output starts going into that file again. Iconic. Restored. Periodt. ✨

Note: this module will not work with the perl function, system(), or any other operation involving a fork(). If you want to capture the output from a system command, it is faster to use open() or back-ticks.

my $output = `/usr/sbin/ls -l 2>&1`;

---

💖 METHODS 💖

💅 new

• Creates a new capture object. Slay. 🫶
• An object can be reused as needed, so will only need to do one of these.
  • Be aware, any data previously captured will be discarded if a new capture session is started. <em>Gone. Deleted. Not even a trace.</em> 💀

💅 start

• Start capturing data into the IO::Capture Object.
• Can not be called on an object that is already capturing.
• Can not be called while STDOUT tied to an object.
• undef will be returned on an error.

💅 stop

• Stop capturing data and point STDOUT back to it's previous output location I.e., untie STDOUT. Bye bestie, we're putting you back where we found you 🎀

💅 read

• In Scalar Context
  • Lines are read from the buffer at the position of the line_pointer, and the pointer is incremented by one.

$next_line = $capture->read;

• In List Context
  • The array is returned. The line_pointer is not affected. <em>(Untouched. Unbothered. Flourishing.)</em>

@buffer = $capture->read;

• Data lines are returned exactly as they were captured. You may want to use chomp on them if you don't want the end of line character(s)

while (my $line = $capture->read) {
    chomp $line;
    $cat_line = join '', $cat_line, $line;
}

💅 line_pointer

• Reads or sets the line_pointer.

my $current_line = $capture->line_pointer;
$capture->line_pointer(1);

---

🌈 SUB-CLASSING 🌈

👑 Adding Features

If you would like to sub-class this module to add a feature (method) or two, here is a couple of easy steps. Also see IO::Capture::Overview.

1. Give your package a name

package MyPackage;

2. Use this IO::Capture::Stdout as your base class like this:

package MyPackage;

use base qw/IO::Capture::Stdout/;

3. Add your new method like this

package MyPackage;

use base qw/IO::Capture::Stdout/;

sub grep {
    my $self = shift;

    for $line (
}

---

🧚 See Also 🧚

IO::Capture::Overview

IO::Capture

IO::Capture::Stderr

---

💜 AUTHORS 💜

Mark Reynolds reynolds@sgi.com

Jon Morgan jmorgan@sgi.com

---

⭐ COPYRIGHT ⭐

Copyright (c) 2003, Mark Reynolds. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

---

Okay bestie, that's the whole page 💖 Shoutout to perl v5.36.0, dated 2022-10-13 — she's the one who signed off on all of this. Love that for us. 🎀✨🦋