IO::Capture::Stderr(3pm)

1IO::Capture::Stderr(3)User Contributed Perl DocumentationIO::Capture::Stderr(3)
2
3
4

NAME

6       "IO::Capture::Stderr" - Capture all output sent to "STDERR"
7

SYNOPSIS

9           use IO::Capture::Stderr;
10
11           $capture = IO::Capture::Stderr->new();
12
13           $capture->start();          # STDERR Output captured
14           print STDERR "Test Line One\n";
15           print STDERR "Test Line Two\n";
16           print STDERR "Test Line Three\n";
17           $capture->stop();           # STDERR output sent to wherever it was before 'start'
18
19           # In 'scalar context' returns next line
20           $line = $capture->read;
21           print "$line";         # prints "Test Line One"
22
23           $line = $capture->read;
24           print "$line";         # prints "Test Line Two"
25
26           # move line pointer to line 1
27           $capture->line_pointer(1);
28
29           $line = $capture->read;
30           print "$line";         # prints "Test Line One"
31
32           # Find out current line number
33           $current_line_position = $capture->line_pointer;
34
35           # In 'List Context' return an array(list)
36           @all_lines = $capture->read;
37
38           # Example 1 - "Using in module tests"
39           #  Note: If you don't want to make users install
40           #        the IO::Capture module just for your tests,
41           #        you can just install in the t/lib directory
42           #        of your module and use the lib pragma in
43           #        your tests.
44
45           use lib "t/lib";
46           use IO::Capture:Stderr;
47
48           use Test::More;
49
50               # Create new capture object.  Showing FORCE_CAPTURE_WARN being cleared
51               # for example, but 0 is the default, so you don't need to specify
52               # unless you want to set.
53           my $capture =  IO::Capture:Stderr->new( {FORCE_CAPTURE_WARN => 0} );
54           $capture->start
55
56           # execute with a bad parameter to make sure get
57           # an error.
58
59           ok( ! $test("Bad Parameter") );
60
61           $capture->stop();
62

DESCRIPTION

64       The module "IO::Capture::Stderr", is derived from the abstract class
65       "IO::Capture".  See IO::Capture. The purpose of the module (as the name
66       suggests) is to capture any output sent to "STDOUT".  After the capture
67       is stopped, the STDOUT filehandle will be reset to the previous
68       location. E.g., If previously redirected to a file, when
69       "IO::Capture->stop" is called, output will start going into that file
70       again.
71
72       Note:  This module won't work with the perl function, system(), or any
73       other operation
74              involving a fork().  If you want to capture the output from a
75       system command,
76              it is faster to use open() or back-ticks.
77
78              my $output = `/usr/sbin/ls -l 2>&1`;
79

METHODS

81   new
82       •   Creates a new capture object.
83
84       •   An object can be reused as needed, so will only need to do one of
85           these.
86
87           •   Be aware, any data previously captured will be discarded if a
88               new capture session is started.
89
90   start
91       •   Start capturing data into the "IO::Capture" Object.
92
93       •   Can not be called on an object that is already capturing.
94
95       •   Can not be called while STDERR tied to an object.
96
97       •   "undef" will be returned on an error.
98
99   stop
100       •   Stop capturing data and point STDERR back to it's previous output
101           location I.e., untie STDERR
102
103   read
104       •   In Scalar Context
105
106           •   Lines are read from the buffer at the position of the
107               "line_pointer", and the pointer is incremented by one.
108
109                   $next_line = $capture->read;
110
111       •   In List Context
112
113           •   The array is returned.  The "line_pointer" is not affected.
114
115                   @buffer = $capture->read;
116
117       •   Data lines are returned exactly as they were captured.  You may
118           want to use "chomp" on them if you don't want the end of line
119           character(s)
120
121               while (my $line = $capture->read) {
122                   chomp $line;
123                   $cat_line = join '', $cat_line, $line;
124               }
125
126   line_pointer
127       •   Reads or sets the "line_pointer".
128
129               my $current_line = $capture->line_pointer;
130               $capture->line_pointer(1);
131

ARGUMENTS

133       Pass any arguments to new() in a single array reference.
134
135          IO::Capture::Stderr->new( {FORCE_CAPTURE_WARN => 1} );
136
137   FORCE_CAPTURE_WARN
138           Normally, IO::Capture::Stderr will capture text from warn()
139           function calls. This is because output from warn() is normally
140           directed to STDERR.  If you wish to force IO::Capture::Stderr to
141           grab the text from warn(), set FORCE_CAPTURE_WARN to a 1.  Then
142           "IO::Capture::Stderr" will save the handle that $SIG{__WARN__} was
143           set to, redirect it to itself on "start()", and then set
144           $SIG{__WARN__} back after "stop()" is called.
145

SUB-CLASSING

147   Adding Features
148       If you would like to sub-class this module to add a feature (method) or
149       two, here is a couple of easy steps. Also see IO::Capture::Overview.
150
151       1.  Give your package a name
152
153               package MyPackage;
154
155       2.  Use this "IO::Capture::Stderr" as your base class like this:
156
157               package MyPackage;
158
159               use base qw/IO::Capture::Stderr/;
160
161       3.  Add your new method like this
162
163               package MyPackage;
164
165               use base qw/IO::Capture::Stderr/;
166
167               sub grep {
168                   my $self = shift;
169
170                   for $line (
171               }
172

AUTHORS

181       Mark Reynolds reynolds@sgi.com
182
183       Jon Morgan jmorgan@sgi.com
184

COPYRIGHT

186       Copyright (c) 2003, Mark Reynolds. All Rights Reserved.  This module is
187       free software. It may be used, redistributed and/or modified under the
188       same terms as Perl itself.
189
190
191
192perl v5.32.1                      2021-01-27            IO::Capture::Stderr(3)