Provided by: libcatmandu-perl_1.2020-1_all bug

NAME

       Catmandu::Util - A collection of utility functions

SYNOPSIS

           use Catmandu::Util qw(:string);

           $str = trim($str);

FUNCTIONS

   IO functions
           use Catmandu::Util qw(:io);

       io($io, %opts)
           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:

           mode        Default is "r".

           binmode     Default is ":encoding(UTF-8)".

           encoding    Alias for "binmode".

       read_file($path);
           [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.

       read_io($io)
           Reads an IO::Handle into a string.

              my $str = read_file($fh);

       write_file($path, $str);
           [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.

       read_yaml($path);
           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.

       read_json($path);
           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.

       join_path(@path);
           Joins relative paths into an absolute path.

               join_path('/path/..', './to', 'file.txt');
               # => "/to/file.txt"

       normalize_path($path);
           Normalizes a relative path to an absolute path.

               normalize_path('/path/../to/./file.txt');
               # => "/to/file.txt"

       segmented_path($path);
               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"

       content_type($filename);
           Guess the content type of a file name.

               content_type("book.pdf");
               # => "application/pdf"

   Hash functions
           use Catmandu::Util qw(:hash);

       A collection of functions that operate on hash references.

       hash_merge($hash1, $hash2, ... , $hashN)
           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}

   Array functions
           use Catmandu::Util qw(:array);

       A collection of functions that operate on array references.

       array_exists($array, $index)
           Returns 1 if $index is in the bounds of $array

               array_exists(["a", "b"], 2);
               # => 0
               array_exists(["a", "b"], 1);
               # => 1

       array_group_by($array, $key)
               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}]}

       array_pluck($array, $key)
               my $list = [{id => 1}, {}, {id => 3}];
               array_pluck($list, 'id');
               # => [1, undef, 3]

       array_to_sentence($array)
       array_to_sentence($array, $join)
       array_to_sentence($array, $join, $join_last)
               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($array)
               array_sum([1,2,3]);
               # => 6

       array_includes($array, $val)
           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($array, \&sub)
               array_any(["green", "blue"], sub { my $color = $_[0]; $color eq "blue" });
               # => 1

       array_rest($array)
           Returns a copy of $array without the head.

               array_rest([1,2,3,4]);
               # => [2,3,4]
               array_rest([1]);
               # => []

       array_uniq($array)
           Returns a copy of $array with all duplicates removed.

       array_split($array | $string)
           Returns $array or a new array by splitting $string at commas.

   String functions
           use Catmandu::Util qw(:string);

       as_utf8($str)
           Returns a copy of $str flagged as UTF-8.

       trim($str)
           Returns a copy of $str with leading and trailing whitespace removed.

       capitalize($str)
           Equivalent to "ucfirst lc as_utf8 $str".

   Is functions
           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_invocant($val)
       is_maybe_invocant($val)
           Tests if $val is callable (is an existing package or blessed object).

       is_able($val, @method_names)
       is_maybe_able($val, @method_names)
           Tests if $val is callable and has all methods in @method_names.

       is_instance($val, @class_names)
       is_maybe_instance($val, @class_names)
           Tests if $val is a blessed object and an instance of all the classes in @class_names.

       is_ref($val)
       is_maybe_ref($val)
           Tests if $val is a reference. Equivalent to "ref $val ? 1 : 0".

       is_scalar_ref($val)
       is_maybe_scalar_ref($val)
           Tests if $val is a scalar reference.

       is_array_ref($val)
       is_maybe_array_ref($val)
           Tests if $val is an array reference.

       is_hash_ref($val)
       is_maybe_hash_ref($val)
           Tests if $val is a hash reference.

       is_code_ref($val)
       is_maybe_code_ref($val)
           Tests if $val is a subroutine reference.

       is_regex_ref($val)
       is_maybe_regex_ref($val)
           Tests if $val is a regular expression reference generated by the "qr//" operator.

       is_glob_ref($val)
       is_maybe_glob_ref($val)
           Tests if $val is a glob reference.

       is_value($val)
       is_maybe_value($val)
           Tests if $val is a real value (defined, not a reference and not a glob.

       is_string($val)
       is_maybe_string($val)
           Tests if $val is a non-empty string.  Equivalent to "is_value($val) && length($val) >
           0".

       is_number($val)
       is_maybe_number($val)
           Tests if $val is a number.

       is_integer($val)
       is_maybe_integer($val)
           Tests if $val is an integer.

       is_natural($val)
       is_maybe_natural($val)
           Tests if $val is a non-negative integer.  Equivalent to "is_integer($val) && $val >=
           0".

       is_positive($val)
       is_maybe_positive($val)
           Tests if $val is a positive integer.  Equivalent to "is_integer($val) && $val >= 1".

       is_float($val)
       is_maybe_float($val)
           Tests if $val is a floating point number.

       is_same($val, $other_val)
           Tests if $val is deeply equal to $other_val.

       is_different($val, $other_val)
           The opposite of "is_same()".

   Check functions
           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.

       check_invocant($val)
       check_maybe_invocant($val)
       check_able($val, @method_names)
       check_maybe_able($val, @method_names)
       check_instance($val, @class_names)
       check_maybe_instance($val, @class_names)
       check_ref($val)
       check_maybe_ref($val)
       check_scalar_ref($val)
       check_maybe_scalar_ref($val)
       check_array_ref($val)
       check_maybe_array_ref($val)
       check_hash_ref($val)
       check_maybe_hash_ref($val)
       check_code_ref($val)
       check_maybe_code_ref($val)
       check_regex_ref($val)
       check_maybe_regex_ref($val)
       check_glob_ref($val)
       check_maybe_glob_ref($val)
       check_value($val)
       check_maybe_value($val)
       check_string($val)
       check_maybe_string($val)
       check_number($val)
       check_maybe_number($val)
       check_integer($val)
       check_maybe_integer($val)
       check_natural($val)
       check_maybe_natural($val)
       check_positive($val)
       check_maybe_positive($val)
       check_float($val)
       check_maybe_float($val)
       check_same($val, $other_val)
       check_different($val, $other_val)

   Human output functions
           use Catmandu::Util qw(:human);

       human_number($num)
           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($size)
               human_byte_size(64);
               # => "64 bytes"
               human_byte_size(10005000);
               # => "10.01 MB"

       human_content_type($content_type)
       human_content_type($content_type, $default)
               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);

       xml_declaration()
           Returns "qq(<?xml version="1.0" encoding="UTF-8"?>\n)".

       xml_escape($str)
           Returns an XML escaped copy of $str.

   Miscellaneous functions
       require_package($pkg)
       require_package($pkg, $namespace)
           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.

       use_lib(@dirs)
           Add directories to @INC at runtime.

           Throws a Catmandu::Error on failure.

       pod_section($package_or_file, $section [, @options] )
           Get documentation of a package for a selected section. Additional options are passed
           to Pod::Usage.

       now($format)
           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";