Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Wrap(3)	      User Contributed Perl Documentation	   IO::Wrap(3)

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

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->new(\*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!");

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

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:

	   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 "tiehandle()".
       But that	puts the burden	on them.  Another way to do it is to use
       IO::Wrap.

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

       When wrapping a FileHandle object, however, I believe that Perl will
       invoke the "FileHandle::DESTROY"	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.

FUNCTIONS
       IO::Wrap	makes the following functions available.

   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.

METHODS
       IO::Wrap	implements the following methods.

   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.

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

CONTRIBUTORS
       Dianne Skoll (dfs@roaringpenguin.com).

COPYRIGHT & 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.

perl v5.32.0			  2020-01-17			   IO::Wrap(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | METHODS | AUTHOR | CONTRIBUTORS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Wrap&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help