DOKK / manpages / debian 12 / libcatmandu-perl / Catmandu::Util.3pm.en
Catmandu::Util(3pm) User Contributed Perl Documentation Catmandu::Util(3pm)

Catmandu::Util - A collection of utility functions

    use Catmandu::Util qw(:string);
    $str = trim($str);

IO functions

    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".
Default is ":encoding(UTF-8)".
Alias for "binmode".
[deprecated]: use tools like Path::Tiny instead.

Reads the file at $path into a string.

    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.

    write_file('/path/to/file.txt', "contents");

Throws a Catmandu::Error on failure.

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 

    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()". 

    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.

    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".

    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.

Tests if $val is callable (is an existing package or blessed object).
Tests if $val is callable and has all methods in @method_names.
Tests if $val is a blessed object and an instance of all the classes in @class_names.
Tests if $val is a reference. Equivalent to "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.
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".
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".
Tests if $val is a positive integer. Equivalent to "is_integer($val) && $val >= 1".
Tests if $val is a floating point number.
Tests if $val is deeply equal to $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.

    use Catmandu::Util qw(:human);
Insert a comma a 3-digit intervals to make $num more readable. Only works with integers for now. 

    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"

XML functions

    use Catmandu::Util qw(:xml);
Returns "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. 

    my $pkg = require_package('File::Spec');
    my $dir = $pkg->tmpdir();
    require_package('Util', 'Catmandu');
    # => "Catmandu::Util"
    require_package('Catmandu::Util', 'Catmandu');
    # => "Catmandu::Util"

Throws a Catmandu::Error on failure.

Add directories to @INC at runtime.

Throws a Catmandu::Error on failure.

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. 

    now('%Y/%m/%d');
    now('iso_date_time_millis');

The default format is "iso_date_time";

2023-03-03 perl v5.36.0