Catmandu::Util - A collection of utility functions
use Catmandu::Util qw(:string); $str = trim($str);
use Catmandu::Util qw(:io);
Takes a file path, glob, glob reference, scalar reference or IO::Handle object and returns an opened IO::Handle object.
my $fh = io '/path/to/file'; my $fh = io *STDIN; my $fh = io \*STDOUT, mode => 'w', binmode => ':crlf'; my $write_cb = sub { my $str = $_[0]; ... }; my $fh = io $write_cb, mode => 'w'; my $scalar = ""; my $fh = io \$scalar, mode => 'w'; $fh->print("some text");
Options are:
Default is "r".
"r"
Default is ":encoding(UTF-8)".
":encoding(UTF-8)"
Alias for binmode.
binmode
[deprecated]: use tools like Path::Tiny instead.
Reads the file at $path into a string.
$path
my $str = read_file('/path/to/file.txt');
Throws a Catmandu::Error on failure.
Reads an IO::Handle into a string.
my $str = read_file($fh);
[deprecated]: use tools like use tools like File::Slurp::Tiny instead.
Writes the string $str to a file at $path.
$str
write_file('/path/to/file.txt', "contents");
Reads the YAML file at $path into a Perl hash.
my $cfg = read_yaml($path);
Dies on failure reading the file or parsing the YAML.
Reads the JSON file at $path into a Perl hash.
my $cfg = read_json($path);
Dies on failure reading the file or parsing the JSON.
Joins relative paths into an absolute path.
join_path('/path/..', './to', 'file.txt'); # => "/to/file.txt"
Normalizes a relative path to an absolute path.
normalize_path('/path/../to/./file.txt'); # => "/to/file.txt"
my $id = "FB41144C-F0ED-11E1-A9DE-61C894A0A6B4"; segmented_path($id, segment_size => 4); # => "FB41/144C/F0ED/11E1/A9DE/61C8/94A0/A6B4" segmented_path($id, segment_size => 2, base_path => "/files"); # => "/files/FB/41/14/4C/F0/ED/11/E1/A9/DE/61/C8/94/A0/A6/B4"
Guess the content type of a file name.
content_type("book.pdf"); # => "application/pdf"
use Catmandu::Util qw(:hash);
A collection of functions that operate on hash references.
Merge <hash1> through <hashN>, with the nth-most (rightmost) hash taking precedence. Returns a new hash reference representing the merge.
hash_merge({a => 1}, {b => 2}, {a => 3}); # => { a => 3 , b => 2}
use Catmandu::Util qw(:array);
A collection of functions that operate on array references.
Returns 1 if $index is in the bounds of $array
1
$index
$array
array_exists(["a", "b"], 2); # => 0 array_exists(["a", "b"], 1); # => 1
my $list = [{color => 'black', id => 1}, {color => 'white', id => 2}, {id => 3}, {color => 'black', id => 4}]; array_group_by($list, 'color'); # => {black => [{color => 'black', id => 1}, {color => 'black', id => 4}], # white => [{color => 'white', id => 2}]}
my $list = [{id => 1}, {}, {id => 3}]; array_pluck($list, 'id'); # => [1, undef, 3]
array_to_sentence([1,2,3]); # => "1, 2 and 3" array_to_sentence([1,2,3], ","); # => "1,2 and 3" array_to_sentence([1,2,3], ",", " & "); # => "1,2 & 3"
array_sum([1,2,3]); # => 6
Returns 1 if $array includes a value that is deeply equal to $val, 0 otherwise. Comparison is done with is_same().
$val
is_same()
array_includes([{color => 'black'}], {color => 'white'}); # => 0 array_includes([{color => 'black'}], {color => 'black'}); # => 1
array_any(["green", "blue"], sub { my $color = $_[0]; $color eq "blue" }); # => 1
Returns a copy of $array without the head.
array_rest([1,2,3,4]); # => [2,3,4] array_rest([1]); # => []
Returns a copy of $array with all duplicates removed.
Returns $array or a new array by splitting $string at commas.
$string
use Catmandu::Util qw(:string);
Returns a copy of $str flagged as UTF-8.
Returns a copy of $str with leading and trailing whitespace removed.
Equivalent to ucfirst lc as_utf8 $str.
ucfirst lc as_utf8 $str
use Catmandu::Util qw(:is); is_number(42) ? "it's numeric" : "it's not numeric"; is_maybe_hash_ref({}); # => 1 is_maybe_hash_ref(undef); # => 1 is_maybe_hash_ref([]); # => 0
A collection of predicate functions that test the type or value of argument $val. Each function (except is_same() and is_different) also has a maybe variant that also tests true if $val is undefined. Returns 1 or 0.
is_different
0
Tests if $val is callable (is an existing package or blessed object).
Tests if $val is callable and has all methods in @method_names.
@method_names
Tests if $val is a blessed object and an instance of all the classes in @class_names.
@class_names
Tests if $val is a reference. Equivalent to ref $val ? 1 : 0.
ref $val ? 1 : 0
Tests if $val is a scalar reference.
Tests if $val is an array reference.
Tests if $val is a hash reference.
Tests if $val is a subroutine reference.
Tests if $val is a regular expression reference generated by the qr// operator.
qr//
Tests if $val is a glob reference.
Tests if $val is a real value (defined, not a reference and not a glob.
Tests if $val is a non-empty string. Equivalent to is_value($val) && length($val) > 0.
is_value($val) && length($val) > 0
Tests if $val is a number.
Tests if $val is an integer.
Tests if $val is a non-negative integer. Equivalent to is_integer($val) && $val >= 0.
is_integer($val) && $val >= 0
Tests if $val is a positive integer. Equivalent to is_integer($val) && $val >= 1.
is_integer($val) && $val >= 1
Tests if $val is deeply equal to $other_val.
$other_val
The opposite of is_same().
use Catmandu::Util qw(:check); check_hash_ref({color => 'red'}); # => {color => 'red'} check_hash_ref([]); # dies
A group of assert functions similar to the :is group, but instead of returning true or false they return their argument or die.
:is
use Catmandu::Util qw(:human);
Insert a comma a 3-digit intervals to make $num more readable. Only works with integers for now.
$num
human_number(64354); # => "64,354"
human_byte_size(64); # => "64 bytes" human_byte_size(10005000); # => "10.01 MB"
human_content_type('application/x-dos_ms_excel'); # => "Excel" human_content_type('application/zip'); # => "ZIP archive" human_content_type('foo/x-unknown'); # => "foo/x-unknown" human_content_type('foo/x-unknown', 'Unknown'); # => "Unknown"
use Catmandu::Util qw(:xml);
Returns qq(<?xml version="1.0" encoding="UTF-8"?>\n).
qq(<?xml version="1.0" encoding="UTF-8"?>\n)
Returns an XML escaped copy of $str.
Load package $pkg at runtime with require and return it's full name.
$pkg
require
my $pkg = require_package('File::Spec'); my $dir = $pkg->tmpdir(); require_package('Util', 'Catmandu'); # => "Catmandu::Util" require_package('Catmandu::Util', 'Catmandu'); # => "Catmandu::Util"
Add directories to @INC at runtime.
@INC
Get documentation of a package for a selected section. Additional options are passed to Pod::Usage.
Returns the current datetime as a string. $formatcan be any strftime format. There are also 2 builtin formats, iso_date_time and iso_date_time_millis. iso_date_time is equivalent to %Y-%m-%dT%H:%M:%SZ. iso_date_time_millis is the same, but with added milliseconds.
$format
strftime
iso_date_time
iso_date_time_millis
%Y-%m-%dT%H:%M:%SZ
now('%Y/%m/%d'); now('iso_date_time_millis');
The default format is iso_date_time;
To install Catmandu, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catmandu
CPAN shell
perl -MCPAN -e shell install Catmandu
For more information on module installation, please visit the detailed CPAN module installation guide.