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().  But
60       that puts the burden on them.  Another way to do it is to use IO::Wrap.
61
62       Clearly, when wrapping a raw external filehandle (like "\*STDOUT"), I
63       didn't want to close the file descriptor when the wrapper object is
64       destroyed; the user might not appreciate that! Hence, there's no
65       "DESTROY" method in this class.
66
67       When wrapping a FileHandle object, however, I believe that Perl will
68       invoke the "FileHandle::DESTROY" when the last reference goes away, so
69       in that case, the filehandle is closed if the wrapped FileHandle really
70       was the last reference to it.
71

FUNCTIONS

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

METHODS

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

AUTHOR

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

CONTRIBUTORS

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

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