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

FreeBSD Manual Pages

  
 
  

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

NAME
       IO::Handle::Util	- Functions for	working	with IO::Handle	like objects.

SYNOPSIS
	   # make something that looks like a filehandle from a	random data:
	   my $io = io_from_any	$some_data;

	   # or	from a callback	that returns strings:
	   my $io = io_from_getline sub	{ return $another_line };

	   # create a callback that iterates through the handle
	   my $read_cb = io_to_read_cb $io;

DESCRIPTION
       This module provides a number of	helpful	routines to manipulate or
       create IO::Handle like objects.

EXPORTS
   Coercions resulting in IO objects
       These are available using the ":io_from"	export group.

       io_from_any $whatever
	   Inspects the	value of "whatever" and	calls the appropriate coercion
	   function on it, either "io_from_ref"	or "io_from_string".

       io_from_ref $some_ref
	   Depending on	the reference type of $some_ref	invokes	either
	   "io_from_object", "io_from_array" or	"io_from_scalar_ref".

	   Code	references are not coerced automatically because either
	   "io_from_thunk" or "io_from_getline"	or "io_from_write_cb" could
	   all make sense.

	   Globs are returned as is only if they have a	valid "IO" slot.

       io_from_object $obj
	   Depending on	the class of $obj either returns or coerces the
	   object.

	   Objects that	are passed through include anything that subclasses
	   IO::Handle or seems to duck type (supports the "print" and
	   "getline" methods, which might be a bit too permissive).

	   Objects that	are coerced currently only include Path::Class::File,
	   which will have the "openr" method invoked on it.

	   Anything else is an error.

	   io_from_string $str
	       Instantiates an IO::String object using $str as the buffer.

	       Note that $str is not passed as an alias, so writing to the IO
	       object will not modify string. For that see
	       "io_from_scalar_ref".

	   io_from_array \@array
	       Creates an IO::Handle::Iterator that will return	the elements
	       of @array one by	one.

	       Note that a copy	of @array is made.

	       In order	to be able to append more elements to the array	or
	       remove the ones that have been returned use
	       IO::Handle::Iterator yourself directly.

	   io_from_scalar_ref \$str
	       Creates an IO::String object using $str as the buffer.

	       Writing to the IO object	will modify $str.

	   io_from_thunk sub { ... }
	       Invokes the callback once in list context the first time	it's
	       needed, and then	returns	each element of	the list like
	       "io_from_array" would.

	   io_from_getline sub { ... }
	       Creates an IO::Handle::Iterator object using the	callback.

	   io_from_write_cb sub	{ ... }
	       Creates an IO::Handle::Prototype::Fallback using	the callback.

	       The callback will always	be invoked with	one string argument
	       and with	the values of $, and "$\" localized to "undef".

   Coercions utilizing IO objects
       These coercions will actually call "io_from_any"	on their argument
       first. This allows you to do things like:

	   my $str = '';
	   my $sub = io_to_write_cb(\$str);

	   $sub->("foo");

       These are available using the ":io_to" export group.

       io_to_write_cb $thing
	   Creates a code ref that will	invoke "print" on the handle with the
	   arguments to	the callback.

	   $, and "$\" will both be localized to "undef".

       io_to_read_cb $thing
	   Creates a code ref that will	invoke "getline" on the	handle.

	   $/ will not be localized and	should probably	be set to a reference
	   to a	number if you want efficient iteration.	See perlvar for
	   details.

       io_to_string $thing
	   Slurps a string out of the IO object	by reading all the data.

	   If a	string was passed it is	returned as is.

       io_to_array $thing
	   Returns an array reference containing all the lines of the IO
	   object.

	   If an array reference was passed it is returned as is.

       io_to_list $thing
	   Returns the list of lines from the IO object.

	   Warns if not	invoked	in list	context.

	   If an array reference was passed it is dereferenced an its elements
	   are returned.

       io_to_glob $thing
	   If the filehandle is	an unblessed glob returns it as	is, otherwise
	   returns a new glob which is tied to delegate	to the OO interface.

	   This	lets you use most of the builtins without the method syntax:

	       my $fh =	io_to_glob($some_kind_of_OO_handle);

	       while ( defined(	my $line = <$fh> ) ) {
		   ...
	       }

   Misc	functions
       io_prototype %callbacks
	   Given a key-value pair list of named	callbacks, constructs an
	   IO::Handle::Prototype::Fallback object with those callbacks.

	   For example:

	       my $io =	io_prototype print => sub {
		   my $self = shift;

		   no warnings 'uninitialized';
		   $string .= join($,, @_) . $\;
	       };

	       $io->say("Hello"); # $string now	has "Hello\n"

	   See IO::Handle::Prototype::Fallback for more	details.

       is_real_fh $io
	   Returns true	if the IO handle probably could	be passed to something
	   like	AnyEvent::Handle which would break encapsulation.

	   Checks for the following conditions:

	   o   The handle has a	reftype	of either a "GLOB" with	an "IO"	slot,
	       or is an	"IO" itself.

	   o   The handle's "fileno" method returns a positive number,
	       corresponding to	a filedescriptor.

	   o   The "fileno" builtin returns the	same thing as "fileno" invoked
	       as a method.

	   If these conditions hold the	handle is probably OK to work with
	   using the IO	builtins directly, or passing the filedesctiptor to C
	   land, instead of by invoking	methods	on it.

SEE ALSO
       IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc

VERSION	CONTROL
       <http://github.com/nothingmuch/io-handle-util>

AUTHOR
       Yuval Kogman

COPYRIGHT & LICENSE
	       Copyright (c) 2009 Yuval	Kogman.	All rights reserved
	       This program is free software; you can redistribute
	       it and/or modify	it under the same terms	as Perl	itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 425:
	   You forgot a	'=back'	before '=head2'

perl v5.24.1			  2009-10-01		   IO::Handle::Util(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTS | SEE ALSO | VERSION CONTROL | AUTHOR | COPYRIGHT & LICENSE | POD ERRORS

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

home | help