GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DATA::UTIL (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

This document describes Data::Util version 0.63

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 <B>numberB> 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 <B>integerB> is also a <B>numberB>, 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: Cant 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 <B>stashB>) 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DATA::UTIL (3) 2014-03-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.