view release on metacpan or  search on metacpan

lib/Acrux/Util.pm  view on Meta::CPAN

package Acrux::Util;
use strict;
use utf8;

=encoding utf8

=head1 NAME

Acrux::Util - The Acrux utilities

=head1 SYNOPSIS

    use Acrux::Util;

=head1 DESCRIPTION

This module provides portable utility functions for Acrux

=head2 clone

    my $copy = clone(\@array);
    my $copy = clone(\%hash);

This function is a proxy function for L<Storable/dclone>

It makes recursive copies of nested hash, array, scalar and reference types, including tied variables and objects.
The C<clone()> takes a scalar argument and duplicates it. To duplicate lists, arrays or hashes, pass them in by reference, e.g.

=head2 color

    say color(blue => "Format %s %s" => "text", "foo");
    say color(cyan => "text");
    say color("red on_bright_yellow" => "text");
    say STDERR color("red on_bright_yellow" => "text");

Returns colored formatted string if is session was runned from terminal

Supported normal foreground colors:

    black, red, green, yellow, blue, magenta, cyan, white

Bright foreground colors:

    bright_black, bright_red,     bright_green, bright_yellow
    bright_blue,  bright_magenta, bright_cyan,  bright_white

Normal background colors:

    on_black, on_red,     on_green, on yellow
    on_blue,  on_magenta, on_cyan,  on_white

Bright background color:

    on_bright_black, on_bright_red,     on_bright_green, on_bright_yellow
    on_bright_blue,  on_bright_magenta, on_bright_cyan,  on_bright_white

See also L<Term::ANSIColor>

=head2 deprecated

    deprecated('foo is DEPRECATED in favor of bar');

Warn about deprecated feature from perspective of caller.
You can also set the C<ACRUX_FATAL_DEPRECATIONS> environment
variable to make them die instead with L<Carp>

=head2 dformat

    $string = dformat( $mask, \%replacehash );
    $string = dformat( $mask, %replacehash );

Replace substrings "[...]" in mask and
returns replaced result. Data for replacing get from \%replacehash

For example:

    # -> 01-foo-bar.baz.tgz
    $string = dformat( "01-[NAME]-bar.[EXT].tgz", {
        NAME => 'foo',
        EXT  => 'baz',
    });

See also L<CTK::Util/dformat>

=head2 dtf

See L</fdt>

=head2 dumper

    my $perl = dumper({some => 'data'});

Dump a Perl data structure with L<Data::Dumper>

=head2 eqtime

    eqtime("from/file", "to/file") or die "Oops";

Sets modified time of destination to that of source

=head2 fbytes

    print fbytes( 123456 );

Returns formatted size value

=head2 fdate

    print fdate( time );

Returns formatted date value

=head2 fdatetime

    print fdatetime( time );

Returns formatted date value

=head2 fdt

    print fdt( $format, $time );
    print fdt( $format, $time, 1 ); # in GMT context

Returns time in your format.
Each conversion specification is replaced by appropriate characters as described in the following list

    s, ss, _s - Seconds
    m, mm, _m - Minutes
    h, hh, _h - Hours
    D, DD, _D - Day of month
    M, MM, _M - Month
    Y, YY, YYY, YYYY - Year
    w       - Short form of week day (Sat, Tue and etc)
    W       - Week day (Saturdat, Tuesday and etc)
    MON, mon - Short form of month (Apr, May and etc)
    MONTH, month - Month (April, May and etc)
    Z       - Diff of TimeZone in short format (+0300)
    z       - Diff of TimeZone in lomg format (+03:00)
    G       - Short name of TimeZone GMT (for GMT context only)
    U       - Short name of TimeZone UTC (for GMT context only)

Examples:

    # RFC822 (RSS)
    say fdt("%w, %D %MON %YY %hh:%mm:%ss %G", time(), 1); # Tue, 3 Sep 2013 12:31:40 GMT

    # RFC850
    say fdt("%W, %DD-%MON-%YY %hh:%mm:%ss %G", time(), 1); # Tuesday, 03-Sep-13 12:38:41 GMT

    # RFC1036
    say fdt("%w, %D %MON %YY %hh:%mm:%ss %G", time(), 1); # Tue, 3 Sep 13 12:44:08 GMT

    # RFC1123
    say fdt("%w, %D %MON %YYYY %hh:%mm:%ss %G", time(), 1); # Tue, 3 Sep 2013 12:50:42 GMT

    # RFC2822
    say fdt("%w, %DD %MON %YYYY %hh:%mm:%ss %Z"); # Tue, 12 Feb 2013 16:07:05 +0400
    say fdt("%w, %DD %MON %YYYY %hh:%mm:%ss ".tz_diff());

    # W3CDTF, ATOM (Same as RFC 3339/ISO 8601) -- Mail format
    say fdt("%YYYY-%MM-%DDT%hh:%mm:%ss%z"); # 2013-02-12T16:10:28+04:00

    # CTIME
    say fdt("%w %MON %_D %hh:%mm:%ss %YYYY"); # Tue Feb  2 16:15:18 2013

    # Russian date and time format
    say fdt("%DD.%MM.%YYYY %hh:%mm:%ss"); # 12.02.2013 16:16:53

    # DIG form
    say fdt("%YYYY%MM%DD%hh%mm%ss"); # 20130212161844

    # HTTP headers format (See CGI::Util::expires)
    say fdt("%w, %DD %MON %YYYY %hh:%mm:%ss %G", time, 1); # Tue, 12 Feb 2013 13:35:04 GMT

    # HTTP/cookie format (See CGI::Util::expires)
    say fdt("%w, %DD-%MON-%YYYY %hh:%mm:%ss %G", time, 1); # Tue, 12-Feb-2013 13:35:04 GMT

    # COOKIE (RFC2616 as rfc1123-date)
    say fdt("%w, %DD %MON %YYYY %hh:%mm:%ss %G", time, 1); # Tue, 12 Feb 2013 13:35:04 GMT

For more features please use L<Date::Format>, L<DateTime> and L<POSIX/strftime>

=head2 fduration

    print fduration( 123 );

Returns formatted duration value

=head2 humanize_duration

    print humanize_duration ( 123 );

Turns duration value into a simplified human readable format

=head2 humanize_number

    print humanize_number( $number, $sep );

Placement of separators discharges among digits.
For example 1`234`567 if $sep is char "`" (default)

=head2 human2bytes

    my $bytes = human2bytes("100 kB");

Converts a human readable byte count into the pure  number of bytes without any suffix

See also L<Mojo::Util/humanize_bytes>

=head2 indent

    my $indented = indent($str, 4, ' ');
    my $indented = indent($str, 1, "\t");

Indent multi-line string

    # "  foo\n  bar\n  baz\n"
    print indent("foo\nbar\nbaz\n", 2);

You can use number of indent-chars and indent-symbol manuality:

    # "> foo\n> bar\n> baz\n"
    my $data = indent("foo\nbar\nbaz\n", 1, '> ');

See also L<Mojo::Util/unindent> to unindent multi-line strings

=head2 is_os_type

    $is_windows = is_os_type('Windows');
    $is_unix    = is_os_type('Unix', 'dragonfly');

Given an OS type and OS name, returns true or false if the OS name is of the given type.
As with os_type, it will use the current operating system as a default
if no OS name is provided

Original this function see in L<Perl::OSType/is_os_type>

=head2 load_class