1IO::Wrap(3)           User Contributed Perl Documentation          IO::Wrap(3)
2
3
4

NAME

6       IO::Wrap - Wrap raw filehandles in the IO::Handle interface
7

SYNOPSIS

9           use strict;
10           use warnings;
11           use IO::Wrap;
12
13           # this is a fairly senseless use case as IO::Handle already does this.
14           my $wrap_fh = IO::Wrap->new(\*STDIN);
15           my $line = $wrap_fh->getline();
16
17           # Do stuff with any kind of filehandle (including a bare globref), or
18           # any kind of blessed object that responds to a print() message.
19
20           # already have a globref? a FileHandle? a scalar filehandle name?
21           $wrap_fh = IO::Wrap->new($some_unknown_thing);
22
23           # At this point, we know we have an IO::Handle-like object! YAY
24           $wrap_fh->print("Hey there!");
25
26       You can also do this using a convenience wrapper function
27
28           use strict;
29           use warnings;
30           use IO::Wrap qw(wraphandle);
31
32           # this is a fairly senseless use case as IO::Handle already does this.
33           my $wrap_fh = wraphandle(\*STDIN);
34           my $line = $wrap_fh->getline();
35
36           # Do stuff with any kind of filehandle (including a bare globref), or
37           # any kind of blessed object that responds to a print() message.
38
39           # already have a globref? a FileHandle? a scalar filehandle name?
40           $wrap_fh = wraphandle($some_unknown_thing);
41
42           # At this point, we know we have an IO::Handle-like object! YAY
43           $wrap_fh->print("Hey there!");
44

DESCRIPTION

46       Let's say you want to write some code which does I/O, but you don't
47       want to force the caller to provide you with a FileHandle or IO::Handle
48       object.  You want them to be able to say:
49
50           do_stuff(\*STDOUT);
51           do_stuff('STDERR');
52           do_stuff($some_FileHandle_object);
53           do_stuff($some_IO_Handle_object);
54
55       And even:
56
57           do_stuff($any_object_with_a_print_method);
58
59       Sure, one way to do it is to force the caller to use "tiehandle()".
60       But that puts the burden on them.  Another way to do it is to use
61       IO::Wrap.
62
63       Clearly, when wrapping a raw external filehandle (like "\*STDOUT"), I
64       didn't want to close the file descriptor when the wrapper object is
65       destroyed; the user might not appreciate that! Hence, there's no
66       "DESTROY" method in this class.
67
68       When wrapping a FileHandle object, however, I believe that Perl will
69       invoke the "FileHandle::DESTROY" when the last reference goes away, so
70       in that case, the filehandle is closed if the wrapped FileHandle really
71       was the last reference to it.
72

FUNCTIONS

74       IO::Wrap makes the following functions available.
75
76   wraphandle
77           # wrap a filehandle glob
78           my $fh = wraphandle(\*STDIN);
79           # wrap a raw filehandle glob by name
80           $fh = wraphandle('STDIN');
81           # wrap a handle in an object
82           $fh = wraphandle('Class::HANDLE');
83
84           # wrap a blessed FileHandle object
85           use FileHandle;
86           my $fho = FileHandle->new("/tmp/foo.txt", "r");
87           $fh = wraphandle($fho);
88
89           # wrap any other blessed object that shares IO::Handle's interface
90           $fh = wraphandle($some_object);
91
92       This function is simply a wrapper to the "new" in IO::Wrap constructor
93       method.
94

METHODS

96       IO::Wrap implements the following methods.
97
98   close
99           $fh->close();
100
101       The "close" method will attempt to close the system file descriptor.
102       For a more complete description, read "close" in perlfunc.
103
104   fileno
105           my $int = $fh->fileno();
106
107       The "fileno" method returns the file descriptor for the wrapped
108       filehandle.  See "fileno" in perlfunc for more information.
109
110   getline
111           my $data = $fh->getline();
112
113       The "getline" method mimics the function by the same name in
114       IO::Handle.  It's like calling "my $data = <$fh>;" but only in scalar
115       context.
116
117   getlines
118           my @data = $fh->getlines();
119
120       The "getlines" method mimics the function by the same name in
121       IO::Handle.  It's like calling "my @data = <$fh>;" but only in list
122       context. Calling this method in scalar context will result in a croak.
123
124   new
125           # wrap a filehandle glob
126           my $fh = IO::Wrap->new(\*STDIN);
127           # wrap a raw filehandle glob by name
128           $fh = IO::Wrap->new('STDIN');
129           # wrap a handle in an object
130           $fh = IO::Wrap->new('Class::HANDLE');
131
132           # wrap a blessed FileHandle object
133           use FileHandle;
134           my $fho = FileHandle->new("/tmp/foo.txt", "r");
135           $fh = IO::Wrap->new($fho);
136
137           # wrap any other blessed object that shares IO::Handle's interface
138           $fh = IO::Wrap->new($some_object);
139
140       The "new" constructor method takes in a single argument and decides to
141       wrap it or not it based on what it seems to be.
142
143       A raw scalar file handle name, like "STDOUT" or "Class::HANDLE" can be
144       wrapped, returning an IO::Wrap object instance.
145
146       A raw filehandle glob, like "\*STDOUT" can also be wrapped, returning
147       an IO::Wrawp object instance.
148
149       A blessed FileHandle object can also be wrapped. This is a special case
150       where an IO::Wrap object instance will only be returned in the case
151       that your FileHandle object doesn't support the "read" method.
152
153       Also, any other kind of blessed object that conforms to the IO::Handle
154       interface can be passed in. In this case, you just get back that
155       object.
156
157       In other words, we only wrap it into an IO::Wrap object when what
158       you've supplied doesn't already conform to the IO::Handle interface.
159
160       If you get back an IO::Wrap object, it will obey a basic subset of the
161       "IO::" interface. It will do so with object methods, not operators.
162
163       CAVEATS
164
165       This module does not allow you to wrap filehandle names which are given
166       as strings that lack the package they were opened in. That is, if a
167       user opens FOO in package Foo, they must pass it to you either as
168       "\*FOO" or as "Foo::FOO".  However, "STDIN" and friends will work just
169       fine.
170
171   print
172           $fh->print("Some string");
173           $fh->print("more", " than one", " string");
174
175       The "print" method will attempt to print a string or list of strings to
176       the filehandle. For a more complete description, read "print" in
177       perlfunc.
178
179   read
180           my $buffer;
181           # try to read 30 chars into the buffer starting at the
182           # current cursor position.
183           my $num_chars_read = $fh->read($buffer, 30);
184
185       The read method attempts to read a number of characters, starting at
186       the filehandle's current cursor position. It returns the number of
187       characters actually read. See "read" in perlfunc for more information.
188
189   seek
190           use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
191           # seek to the position in bytes
192           $fh->seek(0, SEEK_SET);
193           # seek to the position in bytes from the current position
194           $fh->seek(22, SEEK_CUR);
195           # seek to the EOF plus bytes
196           $fh->seek(0, SEEK_END);
197
198       The "seek" method will attempt to set the cursor to a given position in
199       bytes for the wrapped file handle. See "seek" in perlfunc for more
200       information.
201
202   tell
203           my $bytes = $fh->tell();
204
205       The "tell" method will attempt to return the current position of the
206       cursor in bytes for the wrapped file handle. See "tell" in perlfunc for
207       more information.
208

AUTHOR

210       Eryq (eryq@zeegee.com).  President, ZeeGee Software Inc
211       (http://www.zeegee.com).
212

CONTRIBUTORS

214       Dianne Skoll (dfs@roaringpenguin.com).
215

217       Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All
218       rights reserved.
219
220       This program is free software; you can redistribute it and/or modify it
221       under the same terms as Perl itself.
222
223
224
225perl v5.34.0                      2022-01-21                       IO::Wrap(3)
Impressum