Check functions¶

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

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

is_scalar_ref(value)

Checks for a SCALAR reference.

is_array_ref(value)

Checks for an ARRAY reference.

is_hash_ref(value)

Checks for a HASH reference.

is_code_ref(value)

Checks for a CODE reference.

is_glob_ref(value)

Checks for a GLOB reference.

is_rx(value)

Checks for a regular expression reference generated by the "qr//" operator.

is_instance(value, class)

Checks for an instance of class.

It is equivalent to the following statement: "Scalar::Util::blessed($value) && $value->isa($class)".

is_invocant(value)

Checks 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 checks for 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)

Validates a SCALAR reference.

array_ref(value)

Validates an ARRAY reference.

hash_ref(value)

Validates a HASH reference.

code_ref(value)

Validates a CODE reference.

glob_ref(value)

Validates a GLOB reference.

rx(value)

Validates a regular expression reference.

instance(value, class)

Validates an instance of class.

invocant(value)

Validates 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 runs "$value =~ s/^::(?:main::)*//;" before returning it.

NOTE: Canonization is done so due to an inconsistency between Perl versions. For instance:

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

The last code snippet 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]}
    

DATA_UTIL_PUREPERL¶

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