Functions

"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

        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

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

Precedence

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

Export

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