WWWWWW

Current Directory: /usr/local/share/man/man3
Viewing File: /usr/local/share/man/man3/IO::Wrap.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Wrap 3"
.TH IO::Wrap 3 "2020-01-17" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Wrap \- Wrap raw filehandles in the IO::Handle interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use strict;
\&    use warnings;
\&    use IO::Wrap;
\&
\&    # this is a fairly senseless use case as IO::Handle already does this.
\&    my $wrap_fh = IO::Wrap\->new(\e*STDIN);
\&    my $line = $wrap_fh\->getline();
\&
\&    # Do stuff with any kind of filehandle (including a bare globref), or
\&    # any kind of blessed object that responds to a print() message.
\&
\&    # already have a globref? a FileHandle? a scalar filehandle name?
\&    $wrap_fh = IO::Wrap\->new($some_unknown_thing);
\&
\&    # At this point, we know we have an IO::Handle\-like object! YAY
\&    $wrap_fh\->print("Hey there!");
.Ve
.PP
You can also do this using a convenience wrapper function
.PP
.Vb 3
\&    use strict;
\&    use warnings;
\&    use IO::Wrap qw(wraphandle);
\&
\&    # this is a fairly senseless use case as IO::Handle already does this.
\&    my $wrap_fh = wraphandle(\e*STDIN);
\&    my $line = $wrap_fh\->getline();
\&
\&    # Do stuff with any kind of filehandle (including a bare globref), or
\&    # any kind of blessed object that responds to a print() message.
\&
\&    # already have a globref? a FileHandle? a scalar filehandle name?
\&    $wrap_fh = wraphandle($some_unknown_thing);
\&
\&    # At this point, we know we have an IO::Handle\-like object! YAY
\&    $wrap_fh\->print("Hey there!");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Let's say you want to write some code which does I/O, but you don't
want to force the caller to provide you with a FileHandle or IO::Handle
object.  You want them to be able to say:
.PP
.Vb 4
\&    do_stuff(\e*STDOUT);
\&    do_stuff(\*(AqSTDERR\*(Aq);
\&    do_stuff($some_FileHandle_object);
\&    do_stuff($some_IO_Handle_object);
.Ve
.PP
And even:
.PP
.Vb 1
\&    do_stuff($any_object_with_a_print_method);
.Ve
.PP
Sure, one way to do it is to force the caller to use \f(CW\*(C`tiehandle()\*(C'\fR.
But that puts the burden on them.  Another way to do it is to
use \fBIO::Wrap\fR.
.PP
Clearly, when wrapping a raw external filehandle (like \f(CW\*(C`\e*STDOUT\*(C'\fR),
I didn't want to close the file descriptor when the wrapper object is
destroyed; the user might not appreciate that! Hence, there's no
\&\f(CW\*(C`DESTROY\*(C'\fR method in this class.
.PP
When wrapping a FileHandle object, however, I believe that Perl will
invoke the \f(CW\*(C`FileHandle::DESTROY\*(C'\fR when the last reference goes away,
so in that case, the filehandle is closed if the wrapped FileHandle
really was the last reference to it.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
IO::Wrap makes the following functions available.
.SS "wraphandle"
.IX Subsection "wraphandle"
.Vb 6
\&    # wrap a filehandle glob
\&    my $fh = wraphandle(\e*STDIN);
\&    # wrap a raw filehandle glob by name
\&    $fh = wraphandle(\*(AqSTDIN\*(Aq);
\&    # wrap a handle in an object
\&    $fh = wraphandle(\*(AqClass::HANDLE\*(Aq);
\&
\&    # wrap a blessed FileHandle object
\&    use FileHandle;
\&    my $fho = FileHandle\->new("/tmp/foo.txt", "r");
\&    $fh = wraphandle($fho);
\&
\&    # wrap any other blessed object that shares IO::Handle\*(Aqs interface
\&    $fh = wraphandle($some_object);
.Ve
.PP
This function is simply a wrapper to the \*(L"new\*(R" in IO::Wrap constructor method.
.SH "METHODS"
.IX Header "METHODS"
IO::Wrap implements the following methods.
.SS "close"
.IX Subsection "close"
.Vb 1
\&    $fh\->close();
.Ve
.PP
The \f(CW\*(C`close\*(C'\fR method will attempt to close the system file descriptor. For a
more complete description, read \*(L"close\*(R" in perlfunc.
.SS "fileno"
.IX Subsection "fileno"
.Vb 1
\&    my $int = $fh\->fileno();
.Ve
.PP
The \f(CW\*(C`fileno\*(C'\fR method returns the file descriptor for the wrapped filehandle.
See \*(L"fileno\*(R" in perlfunc for more information.
.SS "getline"
.IX Subsection "getline"
.Vb 1
\&    my $data = $fh\->getline();
.Ve
.PP
The \f(CW\*(C`getline\*(C'\fR method mimics the function by the same name in IO::Handle.
It's like calling \f(CW\*(C`my $data = <$fh>;\*(C'\fR but only in scalar context.
.SS "getlines"
.IX Subsection "getlines"
.Vb 1
\&    my @data = $fh\->getlines();
.Ve
.PP
The \f(CW\*(C`getlines\*(C'\fR method mimics the function by the same name in IO::Handle.
It's like calling \f(CW\*(C`my @data = <$fh>;\*(C'\fR but only in list context. Calling
this method in scalar context will result in a croak.
.SS "new"
.IX Subsection "new"
.Vb 6
\&    # wrap a filehandle glob
\&    my $fh = IO::Wrap\->new(\e*STDIN);
\&    # wrap a raw filehandle glob by name
\&    $fh = IO::Wrap\->new(\*(AqSTDIN\*(Aq);
\&    # wrap a handle in an object
\&    $fh = IO::Wrap\->new(\*(AqClass::HANDLE\*(Aq);
\&
\&    # wrap a blessed FileHandle object
\&    use FileHandle;
\&    my $fho = FileHandle\->new("/tmp/foo.txt", "r");
\&    $fh = IO::Wrap\->new($fho);
\&
\&    # wrap any other blessed object that shares IO::Handle\*(Aqs interface
\&    $fh = IO::Wrap\->new($some_object);
.Ve
.PP
The \f(CW\*(C`new\*(C'\fR constructor method takes in a single argument and decides to wrap
it or not it based on what it seems to be.
.PP
A raw scalar file handle name, like \f(CW"STDOUT"\fR or \f(CW"Class::HANDLE"\fR can be
wrapped, returning an IO::Wrap object instance.
.PP
A raw filehandle glob, like \f(CW\*(C`\e*STDOUT\*(C'\fR can also be wrapped, returning an
IO::Wrawp object instance.
.PP
A blessed FileHandle object can also be wrapped. This is a special case
where an IO::Wrap object instance will only be returned in the case that
your FileHandle object doesn't support the \f(CW\*(C`read\*(C'\fR method.
.PP
Also, any other kind of blessed object that conforms to the
IO::Handle interface can be passed in. In this case, you just get back
that object.
.PP
In other words, we only wrap it into an IO::Wrap object when what you've
supplied doesn't already conform to the IO::Handle interface.
.PP
If you get back an IO::Wrap object, it will obey a basic subset of
the \f(CW\*(C`IO::\*(C'\fR interface. It will do so with object \fBmethods\fR, not \fBoperators\fR.
.PP
\fI\s-1CAVEATS\s0\fR
.IX Subsection "CAVEATS"
.PP
This module does not allow you to wrap filehandle names which are given
as strings that lack the package they were opened in. That is, if a user
opens \s-1FOO\s0 in package Foo, they must pass it to you either as \f(CW\*(C`\e*FOO\*(C'\fR
or as \f(CW"Foo::FOO"\fR.  However, \f(CW"STDIN"\fR and friends will work just fine.
.SS "print"
.IX Subsection "print"
.Vb 2
\&    $fh\->print("Some string");
\&    $fh\->print("more", " than one", " string");
.Ve
.PP
The \f(CW\*(C`print\*(C'\fR method will attempt to print a string or list of strings to the
filehandle. For a more complete description, read
\&\*(L"print\*(R" in perlfunc.
.SS "read"
.IX Subsection "read"
.Vb 4
\&    my $buffer;
\&    # try to read 30 chars into the buffer starting at the
\&    # current cursor position.
\&    my $num_chars_read = $fh\->read($buffer, 30);
.Ve
.PP
The read method attempts to read a number of characters, starting at the
filehandle's current cursor position. It returns the number of characters
actually read. See \*(L"read\*(R" in perlfunc for more information.
.SS "seek"
.IX Subsection "seek"
.Vb 7
\&    use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
\&    # seek to the position in bytes
\&    $fh\->seek(0, SEEK_SET);
\&    # seek to the position in bytes from the current position
\&    $fh\->seek(22, SEEK_CUR);
\&    # seek to the EOF plus bytes
\&    $fh\->seek(0, SEEK_END);
.Ve
.PP
The \f(CW\*(C`seek\*(C'\fR method will attempt to set the cursor to a given position in bytes
for the wrapped file handle. See \*(L"seek\*(R" in perlfunc for more information.
.SS "tell"
.IX Subsection "tell"
.Vb 1
\&    my $bytes = $fh\->tell();
.Ve
.PP
The \f(CW\*(C`tell\*(C'\fR method will attempt to return the current position of the cursor
in bytes for the wrapped file handle. See \*(L"tell\*(R" in perlfunc for more
information.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Dianne Skoll (\fIdfs@roaringpenguin.com\fR).
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
F1l3 Manager
