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

💖 IO::Ca...:Stderr — the perl manual page, but make it cute ✨

okay bestie, so this is IO::Capture::Stderr, from the User Contributed Perl Documentation. Yes the header is truncated, yes it's giving cryptic, but we're gonna get through it together. 🫶

✨ NAME ✨

"IO::Capture::Stderr" — captures all the output you send to "STDERR". That's it, that's the whole job, and she does it flawlessly. 💅

---

🎀 SYNOPSIS 🎀

here's the vibe, copy-paste ready, no notes:

use IO::Capture::Stderr;

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

$capture->start();          # STDERR Output captured
print STDERR "Test Line One\n";
print STDERR "Test Line Two\n";
print STDERR "Test Line Three\n";
$capture->stop();           # STDERR 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;

# 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:Stderr;

use Test::More;

    # Create new capture object.  Showing FORCE_CAPTURE_WARN being cleared
    # for example, but 0 is the default, so you don't need to specify
    # unless you want to set.
my $capture =  IO::Capture:Stderr->new( {FORCE_CAPTURE_WARN => 0} );
$capture->start

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

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

$capture->stop();

---

🌸 DESCRIPTION 🌸

So "IO::Capture::Stderr" is derived from the abstract class "IO::Capture". Go look at IO::Capture if you want the lore. The whole point of this module — as the name is literally telling you — is to capture any output sent to "STDOUT". (yes, we know, the name says Stderr, the description says STDOUT, we are simply reporting the facts bestie, we do not editorialize 🙈)

Once the capture is stopped, the STDOUT filehandle gets reset right back to where it was before. Like, if you'd previously redirected it into a file, then the moment "IO::Capture->stop" is called, output starts flowing into that file again. seamless. no drama. 💖

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`;

like there's your one-liner, go off. 🔥

---

👑 METHODS 👑

new

• Creates a new capture object. baby's first capture. 🦋
• 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. (yes she's ruthless, the old buffer is GONE 💀)

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 STDERR tied to an object.
• "undef" will be returned on an error.

stop

• Stop capturing data and point STDERR back to it's previous output location. I.e., untie STDERR. she goes home, back to her regular filehandle. 🏠

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.

@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". it's giving little cursor bestie, move her where you want her.

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

---

🌈 ARGUMENTS 🌈

Pass any arguments to new() in a single array reference. one array ref, that's the whole dress code.

IO::Capture::Stderr->new( {FORCE_CAPTURE_WARN => 1} );

FORCE_CAPTURE_WARN

Normally, IO::Capture::Stderr will capture text from warn() function calls. That's because output from warn() is normally directed to STDERR. If you wish to force IO::Capture::Stderr to grab the text from warn(), set FORCE_CAPTURE_WARN to a 1. Then "IO::Capture::Stderr" will save the handle that $SIG{__WARN__} was set to, redirect it to itself on "start()", and then set $SIG{__WARN__} back after "stop()" is called. it saves it, it takes it, it puts it back. respectful. 🎀

---

🧚 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::Stderr" as your base class like this:

package MyPackage;

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

3. Add your new method like this

package MyPackage;

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

sub grep {
    my $self = shift;

    for $line (
}

(yes, the example is cut off mid-for loop, no we did not do that, that's genuinely how it is, we're just the messenger 😭)

---

⭐ See Also ⭐

• IO::Capture::Overview
• IO::Capture
• IO::Capture::Stdout

---

💜 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, you ate, go capture some STDERR 💖✨

this ran on perl v5.36.0, dated 2022-10-13, from the User Contributed Perl Documentation — mwah, xoxo, go write some tests that don't spam your terminal 🫶🌸