- FUNCTION REFERENCE
- RELATED MODULES
- COPYRIGHT AND LICENSE
Util::Underscore - Common helper functions without having to import them
use Util::Underscore; _::croak "$foo must do Some::Role" if not _::does($foo, 'Some::Role');
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.
Not all functions from those are available, some have been renamed, and some functions of our own have been added.
The function reference is split into separate topics which each have their own documentation:
(*) if Data::Alias is installed.
- List Utils
- Exception handling
- Miscellaneous Functions
_::confess from the
Carp module are available. They all take a list of strings as argument. How do they differ from each other?
Fatal Warning ------- ------- --------------------- croak carp from call location confess cluck with full stack trace
How do they differ from Perl's builtin
warn? The error messages of
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
Additionally, the variants
_::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:
They are all direct aliases for their namesakes in
$fh = _::is_open $fh
$str = _::prototype \&code
_::prototype \&code, $new_proto
gets or sets the prototype, wrapping either
$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.
This module also includes an object-oriented interface to the callstack. See Util::Underscore::CallStackFrame for further details.
@stack_frames = _::callstack
@stack_frames = _::callstack $start_from_level
Assembles a list of call stack frames.
$start_from_level: The level starting from which frames should be constructed. For example,
1would start from the immediate caller, whereas
0includes the current frame as well. If ommited, uses
returns: A list of
$stack_frame = _::caller
$stack_frame = _::caller $level
Assembles an object representing a specific call stack frame.
$level: The level of which the call stack frame is to be returned. A value of
1would return the immediate caller, whereas
0would indicate the current frame. If ommited, uses
Util::Underscore::CallStackFrameinstance representing the requested stack frame. If no such frame exists,
For invoking external commands, Perl offers the
system command, various modes for
open, and the backtick operator (
qx//). However, these modes encourage interpolating variables directly into a string, which opens up shell injection issues. In fact,
system can't avoid shell injection when piping or redirection is involved. The IPC::Run module avoids this by offering a flexible interface for launching and controlling external processes.
$success = _::process_run COMMAND_SPEC
Spawns the specified command(s), and blocks until completion.
COMMAND_SPEC: An IPC::Run harness specification.
returns: A boolean indicating whether all spawned processes completed without errors (all sub-processes have exit code zero). This is inverse to Perl's built in
my $data = "stuff you want to display with a pager."; # The contents of $data are entered via STDIN _::process_run ['less', '-R'], \$data or die "Couldn't run less: $?"; # To do that same thing using builtin functions, we'd have to do: my $less_pid = open my $less_fh, '|-', 'less', '-R' or die "Couldn't start less: $!"; print $less_fh $data; close $less_fh or die "Couldn't close pipe to less: $!"; waitpid $less_pid, 0;
$process = _::process_start COMMAND_SPEC
Spawns the specified command(s).
COMMAND_SPEC: An IPC::Run harness specification.
returns: A IPC::Run object that represents the launched process(es). To await completion, call
There are a variety of good utility modules like
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
_::. 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
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
If the source module already provided a sensible name, it is kept to reduce confusion.
Factory functions that return an object use CamelCase.
Please report any bugs or feature requests on the bugtracker website https://github.com/latk/p5-Util-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.
Lukas Atkinson (cpan: AMON) <email@example.com>
Olivier Mengué (cpan: DOLMEN) <firstname.lastname@example.org>
This software is copyright (c) 2017 by Lukas Atkinson.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.