/ 
Util-Underscore-v1.2.0_1-TRIAL
River stage zero No dependents
/ Util::Underscore

NAME

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

VERSION

version v1.2.0_1

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 selected functions from the following modules: Carp, Const::Fast, Data::Alias, Data::Dump, List::MoreUtils, List::Util, POSIX, Scalar::Util, Try::Tiny.

Not all functions from those are available, some have been renamed, and some functions of our own have been added.

FUNCTION REFERENCE

The function reference is split into separate topics which each have their own documentation:

Scalars

see Util::Underscore::Scalars

alias, const, is_dual, is_identifier, is_package, is_plain, is_readonly, is_string, is_bool, is_tainted, is_vstring, new_dual

Numbers

see Util::Underscore::Numbers

ceil, floor, is_int, is_numeric, is_uint

References

see Util::Underscore::References

ref_addr, ref_is_weak, ref_type, ref_unweaken, ref_weaken

Objects

see Util::Underscore::Objects

blessed, can, class, class_does, class_isa, does, is_instance, is_object, isa, safecall

List Utils

see Util::Underscore::ListUtils

all, any, each_array, first, first_index, last, last_index, max, max_str, min, min_str, natatime, none, pairfirst, pairgrep, pairmap, part, product, reduce, shuffle, sum, uniq, zip

Exception handling

see below

carp, carpf, catch, cluck, cluckf, confess, confessf, croak, croakf, finally, try

Miscellaneous Functions

see below

dd, Dir, File, is_open, pp, prototype

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

$dir = _::Dir "foo/bar", "baz"

Creates a new Path::Class::Dir instance.

$dir = _::File "foo/bar", "baz.txt"

Creates a new Path::Class::File 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.

RATIONALE

Context and Package Name

There are a variety of good utility modules like Carp or Scalar::Util. I noticed I don't import these (in order to avoid namespace pollution), but rather refer to these functions via their fully qualified names (e.g. Carp::carp). This is ultimately annoying and repetitive.

This module populates the _ package (a nod to JavaScript's Underscore.js library) with various helpers so that they can be used without having to import them, with a per-usage overhead of only three characters _::. The large number of dependencies makes this module somewhat heavyweight, but it avoids the “is any in List::Util or List::MoreUtils”-problem.

In retrospect, choosing the _ package name was a mistake: A certain part of Perl's infrastructure doesn't recognize _ as a valid package name (although Perl itself does). More importantly, Perl's filetest operators can use the magic _ filehandle which would interfere with this module if it were intended for anything else than fully qualified access to its functions. Still, a single underscore is less intrusive than some jumbled letters like Ut::any.

Scope and Function Naming

This module collects various utility functions that – in my humble opinion – should be part of the Perl language, if the main namespace wouldn't become too crowded as a result. Because everything is safely hedged into the _ namespace, we can go wild without fearing name collisions. However, a few naming conventions were adhered to:

  • Functions with a boolean return value start with is_.

  • If the source module already provided a sensible name, it is kept to reduce confusion.

  • Factory functions that return an object use CamelCase.

RELATED MODULES

The following modules were once considered for inclusion or were otherwise influental in the design of this collection: Data::Types, Data::Util, Params::Util, Safe::Isa.

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>

CONTRIBUTORS

  • Lukas Atkinson (cpan: AMON) <amon@cpan.org>

  • Olivier Mengué (cpan: DOLMEN) <dolmen@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