Burak Gürsoy

NAME

Scalar::Util::Reftype - Alternate reftype() interface

SYNOPSIS

    use Scalar::Util::Reftype;
    
    foo() if reftype( "string" )->hash;   # foo() will never be called
    bar() if reftype( \$var    )->scalar; # bar() will be called
    baz() if reftype( []       )->array;  # baz() will be called
    xyz() if reftype( sub {}   )->array;  # xyz() will never be called
    
    $obj  = bless {}, "Foo";
    my $rt = reftype( $obj );
    $rt->hash;        # false
    $rt->hash_object; # true
    $rt->class;       # "Foo"

DESCRIPTION

This document describes version 0.40 of Scalar::Util::Reftype released on 9 September 2009.

This is an alternate interface to Scalar::Util's reftype function. Instead of manual type checking you can just call methods on the result to see if matches the desired type.

FUNCTIONS

reftype EXPR

Exported by default. EXPR can be any value (even undef).

Returns an object with which you can call various test methods. Unless specified otherwise, all of the test methods return either zero (false) or one (true) based on the EXPR you have specified.

Return values of reftype() can not be used in boolean contexts. If you do, it'll die with a verbose error message.

   my $r = reftype( $foo ) || 'something'; # dies
   bar() if reftype( $foo );               # dies

Always call the test methods on the return value:

   bar() if reftype( $foo )->array;

Or, if you want to have multiple tests, without executing reftype multiple times:

   my $r = reftype( $foo );
   bar() if $r->array;
   baz() if $r->array_object;
   die "ooooh! scaaaary..." if $r->format_object;

The available test methods are listed below.

scalar

Tests if EXPR is a SCALAR reference or not.

array

Tests if EXPR is an ARRAY reference or not.

hash

Tests if EXPR is a HASH reference or not.

code

Tests if EXPR is a CODE reference or not.

glob

Tests if EXPR is a GLOB reference or not.

lvalue

Tests if EXPR is a LVALUE reference or not.

format

Tests if EXPR is a FORMAT reference or not.

ref

Tests if EXPR is a reference to a reference or not.

io

Tests if EXPR is a IO reference or not.

CAVEAT: reftype(EXPR)->io_object is also true since there is no way to distinguish them (i.e.: IO refs are already implemented as objects).

regexp

Tests if EXPR is a Regexp reference or not.

scalar_object

Tests if EXPR is a SCALAR reference based object or not.

array_object

Tests if EXPR is an ARRAY reference based object or not.

hash_object

Tests if EXPR is a HASH reference based object or not.

code_object

Tests if EXPR is a CODE reference based object or not.

glob_object

Tests if EXPR is a GLOB reference based object or not.

lvalue_object

Tests if EXPR is a LVALUE reference based object or not.

format_object

Tests if EXPR is a FORMAT reference based object or not.

ref_object

Tests if EXPR is a reference to a reference based object or not.

io_object

Tests if EXPR is a IO reference based object or not.

CAVEAT: reftype(EXPR)->io is also true since there is no way to distinguish them (i.e.: IO refs are already implemented as objects).

regexp_object

Tests if EXPR is a Regexp reference based object or not.

class

Returns the name of the class the object based on if EXPR is an object. Returns an empty string otherwise.

CAVEATS

  • perl versions 5.10 and newer includes the function re::is_regexp to detect if a reference is a regex or not. While it is possible to detect normal regexen in older perls, there is no simple way to detect blessed regexen. Blessing a regex hides it from normal probes. If you are under perl 5.8.x or older, you'll need to install (in fact, it's in the prerequisities list so any automated tool --like cpan shell-- will install it automatically) Data::Dump::Streamer which provides the regex function similar to re::is_regexp.

  • IO refs are already implemented as objects, so both reftype(EXPR)->io and reftype(EXPR)->io_object will return true is EXPR is either and IO reference or an IO reference based object.

  • VSTRING references are not supported and not implemented.

  • FORMAT references can be detected under perl 5.8 and newer. Under older perls, even the accessors are not defined for FORMAT.

SEE ALSO

AUTHOR

Burak Gursoy <burak@cpan.org>.

COPYRIGHT

Copyright 2009 Burak Gursoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.