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->new("/tmp/foo.txt", "r");
    $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 "new" in IO::Wrap constructor method.

close

    $fh->close();

The "close" method will attempt to close the system file descriptor. For a more complete description, read "close" in perlfunc.

fileno

    my $int = $fh->fileno();

The "fileno" method returns the file descriptor for the wrapped filehandle. See "fileno" in perlfunc for more information.

getline

    my $data = $fh->getline();

The "getline" method mimics the function by the same name in IO::Handle. It's like calling "my $data = <$fh>;" but only in scalar context.

getlines

    my @data = $fh->getlines();

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

new

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

    # 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's interface
    $fh = IO::Wrap->new($some_object);

The "new" 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 "STDOUT" or "Class::HANDLE" can be wrapped, returning an IO::Wrap object instance.

A raw filehandle glob, like "\*STDOUT" can also be wrapped, returning an IO::Wrawp object instance.

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 "read" method.

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.

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.

If you get back an IO::Wrap object, it will obey a basic subset of the "IO::" interface. It will do so with object methods, not operators.

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 "\*FOO" or as "Foo::FOO". However, "STDIN" and friends will work just fine.

print

    $fh->print("Some string");
    $fh->print("more", " than one", " string");

The "print" method will attempt to print a string or list of strings to the filehandle. For a more complete description, read "print" in perlfunc.

read

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

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 "read" in perlfunc for more information.

seek

    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);

The "seek" method will attempt to set the cursor to a given position in bytes for the wrapped file handle. See "seek" in perlfunc for more information.

tell

    my $bytes = $fh->tell();

The "tell" method will attempt to return the current position of the cursor in bytes for the wrapped file handle. See "tell" in perlfunc for more information.