/ 
Util-Underscore-v1.1.0
River stage zero No dependents
/ Util::Underscore

NAME

Util::Underscore - Common helper functions without having to import them

VERSION

version v1.1.0

SYNOPSIS

use Util::Underscore;

_::croak "$foo must do Some::Role" if not _::does($foo, 'Some::Role');

DESCRIPTION

This module contains various utility functions, and makes them accessible through the _ package. This allows the use of these utilities (a) without much per-usage overhead and (b) without namespace pollution.

It contains functions from the following modules:

Not all functions from those are available, and some have been renamed.

FUNCTION REFERENCE

Scalars

These functions are about manipulating scalars.

$scalar = _::new_dual $num, $str

wrapper for Scalar::Util::dualvar

$bool = _::is_dual $_

wrapper for Scalar::Util::isdual

$bool = _::is_vstring $_

wrapper for Scalar::Util::isvstring

$bool = _::is_readonly $_

wrapper for Scalar::Util::readonly

$bool = _::is_tainted $_

wrapper for Scalar::Util::tainted

$bool = _::is_plain $_

Checks that the value is defined and not a reference of any kind. This is as close as Perl gets to checking for a string.

$bool = _::is_identifier $_

Checks that the given string would be a legal identifier: a letter followed by zero or more word characters.

$bool = _::is_package $_

Checks that the given string is a valid package name. It only accepts Foo::Bar notation, not the Foo'Bar form. This does not assert that the package actually exists.

Numbers

$bool = _::is_numeric $_

wrapper for Scalar::Util::looks_like_number

$bool = _::is_int $_

The argument is a plain scalar, and its stringification matches a signed integer.

$bool = _::is_uint $_

Like _::is_int, but the stringification must match an unsigned integer (i.e. the number is zero or positive).

References

$int = _::ref_addr $_

wrapper for Scalar::Util::refaddr

$str = _::ref_type $_

wrapper for Scalar::Util::reftype

_::ref_weaken $_

wrapper for Scalar::Util::weaken

_::ref_unweaken $_

wrapper for Scalar::Util::unweaken

$bool = _::ref_is_weak $_

wrapper for Scalar::Util::isweak

Type Validation

These are inspired from Params::Util and Data::Util.

The reference validation routines take one argument (or $_) and return a boolean value. They return true when the value is intended to be used as a reference of that kind: either ref $arg is of the requested type, or it is an overloaded object that can be used as a reference of that kind. It will not be checked that an object claims to perform an appropriate role (e.g. $arg->DOES('ARRAY')).

  • _::is_ref (any nonblessed reference)

  • _::is_scalar_ref

  • _::is_array_ref

  • _::is_hash_ref

  • _::is_code_ref

  • _::is_glob_ref

  • _::is_regex (note that regexes are blessed objects, not plain references)

Classes and Objects

$str = _::blessed $_
$str = _::class $_

wrapper for Scalar::Util::blessed

$bool = _::is_object $_

Checks that the argument is a blessed object. It's just an abbreviation for defined _::blessed $_

$bool = _::class_isa $class, $supertype

Checks that the $class inherits from the given $supertype, both given as strings. In most cases, one should use _::class_does instead.

$bool = _::class_does $class, $role

Checks that the $class performs the given $role, both given as strings.

$bool = _::isa $object, $class

Checks that the $object inherits from the given class. In most cases, one should use _::does or _::is_instance instead.

$code = _::can $object, 'method'

Checks that the given $object can perform the method. Returns undef on failure, or the appropriate code ref on success, so that one can do $object->$code(@args) afterwards.

$bool = _::is_instance $object, $role
$bool = _::does $object, $role

Checks that the given $object can perform the $role.

any = $maybe_object->_::safecall(method => @args)

This will call the method only if the $maybe_object is a blessed object. We do not check that the object can perform the method, so this might still raise an exception.

Context is propagated correctly to the method call. If the $maybe_object is not an object, this will simply return. In scalar context, this evaluates to undef, in list context this is the empty list.

List::Util and List::MoreUtils

$scalar = _::reduce { BLOCK } @list

wrapper for List::Util::reduce

$bool = _::any { PREDICATE } @list

wrapper for List::Util::any

$bool = _::all { PREDICATE } @list

wrapper for List::Util::all

$bool = _::none { PREDICATE } @list

wrapper for List::Util::none

$scalar = _::first { PREDICATE } @list

wrapper for List::MoreUtils::first_value

$int = _::first_index { PREDICATE } @list

wrapper for List::MoreUtils::first_index

$scalar = _::last { PREDICATE } @list

wrapper for List::MoreUtils::last_value

$int = _::last_index { PREDICATE } @list

wrapper for List::MoreUtils::last_index

$num = _::max @list
$str = _::max_str @list

wrappers for List::Util::max and List::Util::maxstr, respectively.

$num = _::min @list
$str = _::min_str @list

wrappers for List::Util::min and List::Util::minstr, respectively.

$num = _::sum 0, @list

wrapper for List::Util::sum

$num = _::product @list

wrapper for List::Util::product

%kvlist = _::pairgrep { PREDICATE } %kvlist

wrapper for List::Util::pairgrep

($k, $v) = _::pairfirst { PREDICATE } %kvlist

wrapper for List::Util::pairfirst

%kvlist = _::pairmap { BLOCK } %kvlist

wrapper for List::Util::pairmap

@list = _::shuffle @list

wrapper for List::Util::shuffle

$iter = _::natatime $size, @list

wrapper for List::MoreUtils::natatime

@list = _::zip \@array1, \@array2, ...

wrapper for List::MoreUtils::zip

Unlike List::MoreUtils::zip, this function directly takes array references, and not array variables. It still uses the same implementation. This change makes it easier to work with anonymous arrayrefs, or other data that isn't already inside a named array variable.

@list = _::uniq @list

wrapper for List::MoreUtils::uniq

@list = _::part { INDEX_FUNCTION } @list

wrapper for List::MoreUtils::part

$iter = _::each_array \@array1, \@array2, ...

wrapper for List::MoreUtils::each_arrayref

Exception handling

The functions _::carp, _::cluck, _::croak, and _::confess from the Carp module are available. They all take a list of strings as argument. How do they differ from each other?

Stack Trace || Fatal    | Warning
------------##====================
    No      || croak    | carp
    Yes     || confess  | cluck

How do they differ from Perl's builtin die and warn? The error messages of die and warn are located on the line where the exception is raised. This makes debugging hard when the error points to some internal function of a module you are using, as this provides no information on where your client code made a mistake. The Carp family of error functions report the error from the point of usage, and optionally provide stack traces. If you write a module, please use the Carp functions instead of plain die.

Additionally, the variants _::carpf, _::cluckf, _::croakf, and _::confessf are provided. These take a sprintf patterns as first argument: _::carpf "pattern", @arguments.

To handle errors, the following keywords from Try::Tiny are available:

  • _::try

  • _::catch

  • _::finally

They are all direct aliases for their namesakes in Try::Tiny.

Miscellaneous Functions

$fh = _::is_open $fh

wrapper for Scalar::Util::openhandle

$str = _::prototype \&code
_::prototype \&code, $new_proto

gets or sets the prototype, wrapping either CORE::prototype or Scalar::Util::set_prototype

$instance = _::package $str

This will construct a new Package::Stash instance.

Data::Dump is an alternative to Data::Dumper. The main difference is the output format: Data::Dump output tends to be easier to read.

$str = _::pp @values

wrapper for Data::Dump::pp

_::dd @values

wrapper for Data::Dump::dd.

RELATED MODULES

The following modules were once considered for inclusion or were otherwise influental in the design of this collection:

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/latk/Underscore/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Lukas Atkinson <amon@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by Lukas Atkinson.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007