<h2>Editing File: /usr/local/share/perl5/IO/Wrap.pm</h2><form method='post'><textarea name='content' class='file-edit'>package IO::Wrap;

use strict;
use Exporter;
use FileHandle;
use Carp;

our $VERSION = '2.113';
our @ISA = qw(Exporter);
our @EXPORT = qw(wraphandle);


#------------------------------
# wraphandle RAW
#------------------------------
sub wraphandle {
    my $raw = shift;
    new IO::Wrap $raw;
}

#------------------------------
# new STREAM
#------------------------------
sub new {
    my ($class, $stream) = @_;
    no strict 'refs';

    ### Convert raw scalar to globref:
    ref($stream) or $stream = \*$stream;

    ### Wrap globref and incomplete objects:
    if ((ref($stream) eq 'GLOB') or      ### globref
	(ref($stream) eq 'FileHandle') &amp;&amp; !defined(&amp;FileHandle::read)) {
	return bless \$stream, $class;
    }
    $stream;           ### already okay!
}

#------------------------------
# I/O methods...
#------------------------------
sub close {
    my $self = shift;
    return close($$self);
}
sub fileno {
    my $self = shift;
    my $fh = $$self;
    return fileno($fh);
}

sub getline {
    my $self = shift;
    my $fh = $$self;
    return scalar(&lt;$fh&gt;);
}
sub getlines {
    my $self = shift;
    wantarray or croak(&quot;Can't call getlines in scalar context!&quot;);
    my $fh = $$self;
    &lt;$fh&gt;;
}
sub print {
    my $self = shift;
    print { $$self } @_;
}
sub read {
    my $self = shift;
    return read($$self, $_[0], $_[1]);
}
sub seek {
    my $self = shift;
    return seek($$self, $_[0], $_[1]);
}
sub tell {
    my $self = shift;
    return tell($$self);
}

1;
__END__


=head1 NAME

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

=head1 SYNOPSIS

    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-&gt;new(\*STDIN);
    my $line = $wrap_fh-&gt;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-&gt;new($some_unknown_thing);

    # At this point, we know we have an IO::Handle-like object! YAY
    $wrap_fh-&gt;print(&quot;Hey there!&quot;);

You can also do this using a convenience wrapper function

    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(\*STDIN);
    my $line = $wrap_fh-&gt;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-&gt;print(&quot;Hey there!&quot;);

=head1 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 L&lt;FileHandle&gt; or L&lt;IO::Handle&gt;
object.  You want them to be able to say:

    do_stuff(\*STDOUT);
    do_stuff('STDERR');
    do_stuff($some_FileHandle_object);
    do_stuff($some_IO_Handle_object);

And even:

    do_stuff($any_object_with_a_print_method);

Sure, one way to do it is to force the caller to use C&lt;tiehandle()&gt;.
But that puts the burden on them.  Another way to do it is to
use B&lt;IO::Wrap&gt;.

Clearly, when wrapping a raw external filehandle (like C&lt;\*STDOUT&gt;),
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
C&lt;DESTROY&gt; method in this class.

When wrapping a L&lt;FileHandle&gt; object, however, I believe that Perl will
invoke the C&lt;FileHandle::DESTROY&gt; when the last reference goes away,
so in that case, the filehandle is closed if the wrapped L&lt;FileHandle&gt;
really was the last reference to it.

=head1 FUNCTIONS

L&lt;IO::Wrap&gt; makes the following functions available.

=head2 wraphandle

    # wrap a filehandle glob
    my $fh = wraphandle(\*STDIN);
    # wrap a raw filehandle glob by name
    $fh = wraphandle('STDIN');
    # wrap a handle in an object
    $fh = wraphandle('Class::HANDLE');

    # wrap a blessed FileHandle object
    use FileHandle;
    my $fho = FileHandle-&gt;new(&quot;/tmp/foo.txt&quot;, &quot;r&quot;);
    $fh = wraphandle($fho);

    # wrap any other blessed object that shares IO::Handle's interface
    $fh = wraphandle($some_object);

This function is simply a wrapper to the L&lt;IO::Wrap/&quot;new&quot;&gt; constructor method.

=head1 METHODS

L&lt;IO::Wrap&gt; implements the following methods.

=head2 close

    $fh-&gt;close();

The C&lt;close&gt; method will attempt to close the system file descriptor. For a
more complete description, read L&lt;perlfunc/close&gt;.

=head2 fileno

    my $int = $fh-&gt;fileno();

The C&lt;fileno&gt; method returns the file descriptor for the wrapped filehandle.
See L&lt;perlfunc/fileno&gt; for more information.

=head2 getline

    my $data = $fh-&gt;getline();

The C&lt;getline&gt; method mimics the function by the same name in L&lt;IO::Handle&gt;.
It's like calling C&lt;&lt; my $data = &lt;$fh&gt;; &gt;&gt; but only in scalar context.

=head2 getlines

    my @data = $fh-&gt;getlines();

The C&lt;getlines&gt; method mimics the function by the same name in L&lt;IO::Handle&gt;.
It's like calling C&lt;&lt; my @data = &lt;$fh&gt;; &gt;&gt; but only in list context. Calling
this method in scalar context will result in a croak.

=head2 new

    # wrap a filehandle glob
    my $fh = IO::Wrap-&gt;new(\*STDIN);
    # wrap a raw filehandle glob by name
    $fh = IO::Wrap-&gt;new('STDIN');
    # wrap a handle in an object
    $fh = IO::Wrap-&gt;new('Class::HANDLE');

    # wrap a blessed FileHandle object
    use FileHandle;
    my $fho = FileHandle-&gt;new(&quot;/tmp/foo.txt&quot;, &quot;r&quot;);
    $fh = IO::Wrap-&gt;new($fho);

    # wrap any other blessed object that shares IO::Handle's interface
    $fh = IO::Wrap-&gt;new($some_object);

The C&lt;new&gt; constructor method takes in a single argument and decides to wrap
it or not it based on what it seems to be.

A raw scalar file handle name, like C&lt;&quot;STDOUT&quot;&gt; or C&lt;&quot;Class::HANDLE&quot;&gt; can be
wrapped, returning an L&lt;IO::Wrap&gt; object instance.

A raw filehandle glob, like C&lt;\*STDOUT&gt; can also be wrapped, returning an
L&lt;IO::Wrawp&gt; object instance.

A blessed L&lt;FileHandle&gt; object can also be wrapped. This is a special case
where an L&lt;IO::Wrap&gt; object instance will only be returned in the case that
your L&lt;FileHandle&gt; object doesn't support the C&lt;read&gt; method.

Also, any other kind of blessed object that conforms to the
L&lt;IO::Handle&gt; interface can be passed in. In this case, you just get back
that object.

In other words, we only wrap it into an L&lt;IO::Wrap&gt; object when what you've
supplied doesn't already conform to the L&lt;IO::Handle&gt; interface.

If you get back an L&lt;IO::Wrap&gt; object, it will obey a basic subset of
the C&lt;IO::&gt; interface. It will do so with object B&lt;methods&gt;, not B&lt;operators&gt;.

=head3 CAVEATS

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 FOO in package Foo, they must pass it to you either as C&lt;\*FOO&gt;
or as C&lt;&quot;Foo::FOO&quot;&gt;.  However, C&lt;&quot;STDIN&quot;&gt; and friends will work just fine.

=head2 print

    $fh-&gt;print(&quot;Some string&quot;);
    $fh-&gt;print(&quot;more&quot;, &quot; than one&quot;, &quot; string&quot;);

The C&lt;print&gt; method will attempt to print a string or list of strings to the
filehandle. For a more complete description, read
L&lt;perlfunc/print&gt;.

=head2 read

    my $buffer;
    # try to read 30 chars into the buffer starting at the
    # current cursor position.
    my $num_chars_read = $fh-&gt;read($buffer, 30);

The L&lt;read&gt; 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&lt;perlfunc/read&gt; for more information.

=head2 seek

    use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
    # seek to the position in bytes
    $fh-&gt;seek(0, SEEK_SET);
    # seek to the position in bytes from the current position
    $fh-&gt;seek(22, SEEK_CUR);
    # seek to the EOF plus bytes
    $fh-&gt;seek(0, SEEK_END);

The C&lt;seek&gt; method will attempt to set the cursor to a given position in bytes
for the wrapped file handle. See L&lt;perlfunc/seek&gt; for more information.

=head2 tell

    my $bytes = $fh-&gt;tell();

The C&lt;tell&gt; method will attempt to return the current position of the cursor
in bytes for the wrapped file handle. See L&lt;perlfunc/tell&gt; for more
information.

=head1 AUTHOR

Eryq (F&lt;eryq@zeegee.com&gt;).
President, ZeeGee Software Inc (F&lt;http://www.zeegee.com&gt;).

=head1 CONTRIBUTORS

Dianne Skoll (F&lt;dfs@roaringpenguin.com&gt;).

=head1 COPYRIGHT &amp; LICENSE

Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Fshare%2Fperl5%2FIO'>Back to Directory</a>