/ 
Data-Util-0.29_01
River stage three • 29 direct dependents • 134 total dependents
/ Data::Util

NAME

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

VERSION

This document describes Data::Util version 0.29_01

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 $rref = regex_ref(shift);
	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 $ref_to_undef = 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::bar'

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

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.

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

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_regex_ref(value)

For a regular expression reference made 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.

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.

regex_ref(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 value.

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(package)

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

It is similar to do{ no strict 'refs'; \%{$package.'::'} }, but does not create the stash if package does not exist.

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 relocated into package as a named subroutine &package::name.

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.

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 full qualified name in scalar context.

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.

wrap_subroutine(subr, ...)

Wraps subr with subroutine modifiers and returns the wrapped 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 is considered as a constructor of wrapped subroutines, and subroutine_modifier() property accessors.

subroutine_modifier(wrapped)

Returns whether wrapped is a wrapped subroutine.

subroutine_modifier(wrapped, property)

Gets property from wrapped.

Valid properties are: before, around, after and original.

subroutine_modifier(wrapped, modifier => [subroutine(s)])

Adds subroutine modifier to wrapped.

Valid modifiers are: before, around, after.

mkopt(input, moniker, require_unique, must_be)

Produces an array of an array reference from input.

It is similar to 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 similar to Data::OptList::mkopt_hash(). In addition to it, must_be can be a HASH reference with name => tyupe pairs.

For example:

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

DEPENDENCIES

Perl 5.8.1 or later.

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::Method::Modifiers.

Data::OptList.

AUTHOR

Goro Fuji <gfuji(at)cpan.org>

LICENSE AND COPYRIGHT

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

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