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

FreeBSD Manual Pages

  
 
  

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

NAME
       IO::Detect - is this a frickin' filehandle or what?!

SYNOPSIS
	       use IO::Detect;

	       if (is_filehandle $fh)
	       {
		       my $line	= <$fh>;
	       }

DESCRIPTION
       It is stupidly complicated to detect whether a given scalar is a
       filehandle (or something	filehandle like) in Perl. This module attempts
       to do so, but probably falls short in some cases. The primary advantage
       of using	this module is that it gives you somebody to blame (me)	if
       your code can't detect aA filehandle.

       The main	use case for IO::Detect	is for when you	are writing functions
       and you want to allow the caller	to pass	a file as an argument without
       being fussy as to whether they pass a file name or a file handle.

   Functions
       Each function takes a single argument, or if called with	no argument,
       operates	on $_.

       "is_filehandle $thing"
	   Theoretically returns true if and only if $thing is a file handle,
	   or may be treated as	a filehandle. That includes blessed references
	   to filehandles, things that inherit from IO::Handle,	etc.

	   It's	never going to work 100%. What Perl allows you to use as a
	   filehandle is mysterious and	somewhat context-dependent, as the
	   following code illustrates.

		   my $fh = "STD" . "OUT";
		   print $fh "Hello World!\n";

       "is_filename $thing"
	   Returns true	if $thing is a IO::All object or Path::Class::Entity
	   or "any non-reference, non-zero-length string with no line breaks".
	   That's because depending on your operating system, virtually
	   anything can	be used	as a filename. (In fact, on many systems,
	   including Linux, filenames can contain line breaks. However,	this
	   is unlikely to be intentional.)

	   This	function doesn't tell you whether $thing is an existing	file
	   on your system. It attempts to tell you whether $thing could
	   possibly be a filename on some system somewhere.

       "is_fileuri $thing"
	   Returns true	if $thing is a URI beginning with "file://". It	allows
	   for URI objects, RDF::Trine::Node::Resource objects,	strings	and
	   objects that	overload stringification.

	   This	function actually returns an "interesting value	of true". The
	   value returned is a URI::file object.

       "as_filehandle $thing, $mode"
	   Returns $thing if it	is a filehandle; otherwise opens it with mode
	   $mode (croaking if it cannot	be opened). $mode defaults to "<"
	   (read access).

	   This	function is not	exported by default, but needs to be requested
	   explicitly:

		   use IO::Detect qw(as_filehandle);

	   You may even	specify	a different default mode, or import it several
	   times with different	names:

		   use IO::Detect
		     as_filehandle => {	-as => 'as_filehandle_read',  mode => '<' },
		     as_filehandle => {	-as => 'as_filehandle_write', mode => '>' };

   Smart Matching
       You can import three constants for use in smart matching:

	       use IO::Detect -smartmatch;

       These constants are:

       "FileHandle"
       "FileName"
       "FileUri"

       They can	be used	like this:

	       if ($file ~~ FileHandle)
	       {
		       ...
	       }

       Note that there does exist a FileHandle package in Perl core. This
       module attempts to do the right thing so	that "FileHandle->new" still
       works, but there	are conceivably	places this could go wrong, or be
       plain old confusing.

       Although	"is_filehandle"	and its	friends	support	Perl 5.8 and above,
       smart match is only available in	Perl 5.10 onwards.

   Use with Scalar::Does
       The smart match constants can also be used with Scalar::Does:

	       if (does	$file, FileHandle)
	       {
		       ...;
	       }
	       elsif (does $file, FileName)
	       {
		       ...;
	       }

   Precedence
       Because there is	some overlap/ambiguity between what is a filehandle
       and what	is a filename, etc, if you need	to detect between them,	I
       recommend checking "is_filehandle" first, then "is_fileuri" and falling
       back to "is_filename".

	       for ($file)
	       {
		       when (FileHandle)  { ...	}
		       when (FileUri)	  { ...	}
		       when (FileName)	  { ...	}
		       default		  { die	"$file is not a	file!" }
	       }

   Export
       Like Scalar::Does, IO::Detect plays some	tricks with namespace::clean
       to ensure that any functions it exports to your namespace are cleaned
       up when you're finished with them.

       Duck Typing

       In some cases you might be happy	to accept something less than a
       complete	file handle. In	this case you can import a customised "duck
       type" test...

	       use IO::Detect
		       -default,
		       ducktype	=> {
			       -as     => 'is_slurpable',
			       methods => [qw(getlines close)],
		       };

	       sub do_something_with_a_file
	       {
		       my $f = shift;
		       if ( is_filehandle $f or	is_slurpable $f	)
			       { ... }
		       elsif ( is_filename $f )
			       { ... }
	       }

       Duck type test functions	only test that the argument is blessed and can
       do all of the specified methods.	They don't test	any other aspect of
       "filehandliness".

BUGS
       Please report any bugs to
       <http://rt.cpan.org/Dist/Display.html?Queue=IO-Detect>.

SEE ALSO
       This module is an attempt to capture some of the	wisdom from this
       PerlMonks thread	<http://www.perlmonks.org/?node_id=980665> into
       executable code.

       Various other modules that may be of interest, in no particular
       order...	 Scalar::Does, Scalar::Util, FileHandle, IO::Handle,
       IO::Handle::Util, IO::All, Path::Class, URI::file.

AUTHOR
       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
       This software is	copyright (c) 2012-2014, 2017 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
       THIS PACKAGE IS PROVIDED	"AS IS"	AND WITHOUT ANY	EXPRESS	OR IMPLIED
       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.24.1			  2017-01-31			 IO::Detect(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENCE | DISCLAIMER OF WARRANTIES

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

home | help