IO::Capture::Stdout(3pm)

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

NAME

6       IO::Capture::Stdout - Capture any output sent to STDOUT
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

SUB-CLASSING

135       Adding Features
136
137       If you would like to sub-class this module to add a feature (method) or
138       two, here is a couple of easy steps. Also see IO::Capture::Overview.
139
140       1   Give your package a name
141
142               package MyPackage;
143
144       2   Use this "IO::Capture::Stdout" as your base class like this:
145
146               package MyPackage;
147
148               use base qw/IO::Capture::Stdout/;
149
150       3   Add your new method like this
151
152               package MyPackage;
153
154               use base qw/IO::Capture::Stdout/;
155
156               sub grep {
157                   my $self = shift;
158
159                   for $line (
160               }
161

AUTHORS

170       Mark Reynolds reynolds@sgi.com
171
172       Jon Morgan jmorgan@sgi.com
173

COPYRIGHT

175       Copyright (c) 2003, Mark Reynolds. All Rights Reserved.  This module is
176       free software. It may be used, redistributed and/or modified under the
177       same terms as Perl itself.
178
179
180
181perl v5.8.8                       2005-04-29            IO::Capture::Stdout(3)