Provided by: libdata-util-perl_0.62-1build1_amd64 bug

NAME

       Data::Util - A selection of utilities for data and data types

VERSION

       This document describes Data::Util version 0.62

SYNOPSIS

               use Data::Util qw(:validate);

               sub foo{
                       # they will die if invalid values are supplied
                       my $sref = scalar_ref(shift);
                       my $aref = array_ref(shift);
                       my $href = hash_ref(shift);
                       my $cref = code_ref(shift);
                       my $gref = glob_ref(shift);
                       my $rx   = rx(shift); # regular expression
                       my $obj  = instance(shift, 'Foo');
                       # ...
               }

               use Data::Util qw(:check);

               sub bar{
                       my $x = shift;
                       if(is_scalar_ref $x){
                               # $x is an array reference
                       }
                       # ...
                       elsif(is_instance $x, 'Foo'){
                               # $x is an instance of Foo
                       }
                       # ...
               }

               # miscelaneous
               use Data::Util qw(:all);

               my $x = anon_scalar();
               $x = anon_scalar($x); # OK

               my $stash = get_stash('Foo');

               install_subroutine('Foo',
                       hello  => sub{ "Hello!\n" },
                       goodby => sub{ "Goodby!\n" },
               );

               print Foo::hello(); # Hello!

               my($pkg, $name) = get_code_info(\&Foo::hello); # => ('Foo', 'hello')
               my $fqn         = get_code_info(\&Foo::hello); # =>  'Foo::hello'
               my $code        = get_code_ref('Foo', 'hello');  # => \&Foo::hello

               uninstall_subroutine('Foo', qw(hello goodby));

           # simple format for errro messages (not the same as Data::Dumper)
               print neat("Hello!\n"); # => "Hello!\n"
               print neat(3.14);       # => 3.14
               print neat(undef);      # => undef

DESCRIPTION

       This module provides utility functions for data and data types, including functions for
       subroutines and symbol table hashes (stashes).

       The implementation of this module is both Pure Perl and XS, so if you have a C compiler,
       all the functions this module provides are really faster.

       There are many benchmarks in the DIST-DIR/benchmark/ directory.

INTERFACE

   Check functions
       Check functions are introduced by the ":check" import tag, which check the argument type
       and return a bool.

       These functions also checks overloading magic, e.g. "${}" for a SCALAR reference.

       is_scalar_ref(value)
           For a SCALAR reference.

       is_array_ref(value)
           For an ARRAY reference.

       is_hash_ref(value)
           For a HASH reference.

       is_code_ref(value)
           For a CODE reference.

       is_glob_ref(value)
           For a GLOB reference.

       is_rx(value)
           For a regular expression reference generated by the "qr//" operator.

       is_instance(value, class)
           For an instance of class.

           It is equivalent to something like "Scalar::Util::blessed($value) &&
           $value->isa($class)".

       is_invocant(value)
           For an invocant, i.e. a blessed reference or existent package name.

           If value is a valid class name but does not exist, it will return false.

       is_value(value)
           Checks whether value is a primitive value, i.e. a defined, non-ref, and non-type-glob
           value.

           This function has no counterpart for validation.

       is_string(value)
           Checks whether value is a string with non-zero-length contents, equivalent to
           "is_value($value) && length($value) > 0".

           This function has no counterpart for validation.

       is_number(value)
           Checks whether value is a number.  Here, a number means that the perl parser can
           understand it and that the perl numeric converter (e.g. invoked by "sprintf '%g',
           $value") doesn't complain about it.

           It is similar to "Scalar::Util::looks_like_number()" but refuses "infinity", "not a
           number" and "0 but true".  Note that "9**9**9" makes "infinity" and "9**9**9 -
           9**9**9" makes "not a number".

           This function has no counterpart for validation.

       is_integer(value)
           Checks whether value is an integer.  An integer is also a number, so this function
           refuses "infinity" and "not a number". See also "is_number()".

           This function has no counterpart for validation.

   Validating functions
       Validating functions are introduced by the ":validate" tag which check the argument and
       returns the first argument.  These are like the ":check" functions but dies if the
       argument type is invalid.

       These functions also checks overloading magic, e.g. "${}" for a SCALAR reference.

       scalar_ref(value)
           For a SCALAR reference.

       array_ref(value)
           For an ARRAY reference.

       hash_ref(value)
           For a HASH reference.

       code_ref(value)
           For a CODE reference.

       glob_ref(value)
           For a GLOB reference.

       rx(value)
           For a regular expression reference.

       instance(value, class)
           For an instance of class.

       invocant(value)
           For an invocant, i.e. a blessed reference or existent package name.

           If value is a valid class name and the class exists, then it returns the canonical
           class name, which is logically cleaned up. That is, it does "$value =~
           s/^::(?:main::)*//;" before returns it.

           NOTE: The canonization is because some versions of perl has an inconsistency on
           package names:

                   package ::Foo; # OK
                   my $x = bless {}, '::Foo'; # OK
                   ref($x)->isa('Foo'); # Fatal

           The last sentence causes a fatal error: "Can't call method "isa" without package or
           object reference".  However, "invocant(ref $x)->isa('Foo')" is always OK.

   Miscellaneous utilities
       There are some other utility functions you can import from this module.

       anon_scalar()
           Generates an anonymous scalar reference to "undef".

       anon_scalar(value)
           Generates an anonymous scalar reference to the copy of value.

           It is equivalent to "do{ my $tmp = $value; \$tmp; }".

       neat(value)
           Returns a neat string that is suitable to display.

           This is a smart version of "<do{ defined($value) ? qq{"$value"} : 'undef' }">.

       get_stash(invocant)
           Returns the symbol table hash (also known as stash) of invocant if the stash exists.

       install_subroutine(package, name => subr [, ...])
           Installs subr into package as name.

           It is similar to "do{ no strict 'refs'; *{$package.'::'.$name} = \&subr; }".  In
           addition, if subr is an anonymous subroutine, it is located into package as a named
           subroutine &package::name.

           For example:

                   install_subroutine($pkg,   say => sub{ print @_, "\n" });
                   install_subroutine($pkg,
                           one => \&_one,
                           two => \&_two,
                   );

                   # accepts a HASH reference
                   install_subroutine($pkg, { say => sub{ print @_, "\n" }); #

           To re-install subr, use "no warnings 'redefine'" directive:

                   no warnings 'redefine';
                   install_subroutine($package, $name => $subr);

       uninstall_subroutine(package, names...)
           Uninstalls names from package.

           It is similar to "Sub::Delete::delete_sub()", but uninstall multiple subroutines at a
           time.

           If you want to specify deleted subroutines, you can supply "name => \&subr" pairs.

           For example:

                   uninstall_subroutine('Foo', 'hello');

                   uninstall_subroutine('Foo', hello => \&Bar::hello);

                   uninstall_subroutine($pkg,
                           one => \&_one,
                           two => \&_two,
                   );

                   # accepts a HASH reference
                   uninstall_subroutine(\$pkg, { hello => \&Bar::hello });

       get_code_info(subr)
           Returns a pair of elements, the package name and the subroutine name of subr.

           It is similar to "Sub::Identify::get_code_info()", but it returns the fully qualified
           name in scalar context.

       get_code_ref(package, name, flag?)
           Returns &package::name if it exists, not touching the symbol in the stash.

           if flag is a string "-create", it returns &package::name regardless of its existence.
           That is, it is equivalent to "do{ no strict 'refs'; \&{package . '::' . $name} }".

           For example:

                   $code = get_code_ref($pkg, $name);          # like  *{$pkg.'::'.$name}{CODE}
                   $code = get_code_ref($pkg, $name, -create); # like \&{$pkg.'::'.$name}

       curry(subr, args and/or placeholders)
           Makes subr curried and returns the curried subroutine.

           This is also considered as lightweight closures.

           See also Data::Util::Curry.

       modify_subroutine(subr, ...)
           Modifies subr with subroutine modifiers and returns the modified subroutine.  This is
           also considered as lightweight closures.

           subr must be a code reference or callable object.

           Optional arguments: "before => [subroutine(s)]" called before subr.  "around =>
           [subroutine(s)]" called around subr.  "after  => [subroutine(s)]" called after  subr.

           This seems a constructor of modified subroutines and "subroutine_modifier()" is
           property accessors, but it does not bless the modified subroutines.

       subroutine_modifier(subr)
           Returns whether subr is a modified subroutine.

       subroutine_modifier(modified_subr, property)
           Gets property from modified.

           Valid properties are: "before", "around", "after".

       subroutine_modifier(modified_subr, modifier => [subroutine(s)])
           Adds subroutine modifier to modified_subr.

           Valid modifiers are: "before", "around", "after".

       mkopt(input, moniker, require_unique, must_be)
           Produces an array of an array reference from input.

           It is compatible with "Data::OptList::mkopt()". In addition to it, must_be can be a
           HASH reference with "name => type" pairs.

           For example:

                   my $optlist = mkopt(['foo', bar => [42]], $moniker, $uniq, { bar => 'ARRAY' });
                   # $optlist == [[foo => undef], [bar => [42]]

       mkopt_hash(input, moniker, must_be)
           Produces a hash reference from input.

           It is compatible with "Data::OptList::mkopt_hash()". In addition to it, must_be can be
           a HASH reference with "name => type" pairs.

           For example:

                   my $optlist = mkopt(['foo', bar => [42]], $moniker, { bar => 'ARRAY' });
                   # $optlist == {foo => undef, bar => [42]}

ENVIRONMENT VARIABLES

   DATA_UTIL_PUREPERL
       If true, "Data::Util" uses the Pure Perl implementation.

DEPENDENCIES

       Perl 5.8.1 or later.

       If you have a C compiler, you can use the XS backend, but the Pure Perl backend is also
       available if you have no C compilers.

BUGS AND LIMITATIONS

       No bugs have been reported.

       Please report any bugs or feature requests to the author.

SEE ALSO

       Scalar::Util.

       overload.

       Params::Util.

       Sub::Install.

       Sub::Identify.

       Sub::Delete.

       Sub::Curry.

       Class::MOP.

       Class::Method::Modifiers.

       Data::OptList.

       Mouse

AUTHOR

       Goro Fuji(gfx) <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT

       Copyright (c) 2008-2010, Goro Fuji <gfuji(at)cpan.org>. All rights reserved.

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