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)

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

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

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

   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

	   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

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


       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

       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

	   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 filedescriptor to C
	   land, instead of by invoking	methods	on it.

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


       Yuval Kogman

	       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.

perl v5.32.1			  2018-10-06		   IO::Handle::Util(3)


Want to link to this manual page? Use this URL:

home | help