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 loca‐
68       tion. E.g., If previously redirected to a file, when "IO::Cap‐
69       ture->stop" is called, output will start going into that file again.
70
71       Note:  This module won't work with the perl function, system(), or any
72       other operation
73              involving a fork().  If you want to capture the output from a
74       system command,
75              it is faster to use open() or back-ticks.
76
77              my $output = `/usr/sbin/ls -l 2>&1`;
78

METHODS

80       new
81
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
92       ·   Start capturing data into the "IO::Capture" Object.
93
94       ·   Can not be called on an object that is already capturing.
95
96       ·   Can not be called while STDERR tied to an object.
97
98       ·   "undef" will be returned on an error.
99
100       stop
101
102       ·   Stop capturing data and point STDERR back to it's previous output
103           location I.e., untie STDERR
104
105       read
106
107       ·   In Scalar Context
108
109           ·   Lines are read from the buffer at the position of the
110               "line_pointer", and the pointer is incremented by one.
111
112                   $next_line = $capture->read;
113
114       ·   In List Context
115
116           ·   The array is returned.  The "line_pointer" is not affected.
117
118                   @buffer = $capture->read;
119
120       ·   Data lines are returned exactly as they were captured.  You may
121           want to use "chomp" on them if you don't want the end of line char‐
122           acter(s)
123
124               while (my $line = $capture->read) {
125                   chomp $line;
126                   $cat_line = join '', $cat_line, $line;
127               }
128
129       line_pointer
130
131       ·   Reads or sets the "line_pointer".
132
133               my $current_line = $capture->line_pointer;
134               $capture->line_pointer(1);
135

ARGUMENTS

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

SUB-CLASSING

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

AUTHORS

187       Mark Reynolds reynolds@sgi.com
188
189       Jon Morgan jmorgan@sgi.com
190

COPYRIGHT

192       Copyright (c) 2003, Mark Reynolds. All Rights Reserved.  This module is
193       free software. It may be used, redistributed and/or modified under the
194       same terms as Perl itself.
195
196
197
198perl v5.8.8                       2005-04-29            IO::Capture::Stderr(3)