NAME

Devel::Util - a collection of general-utility development subroutines

SYNOPSIS

    use Devel::Util qw(dt tz oiaw printr forked);

DESCRIPTION

Devel::Util contains a collection of subroutines to be used during the development phase, and also possibly in production.

By default Devel::Util does not export any subroutines.

dt

dt BLOCK [NAME]

do_time BLOCK [NAME]

    dt {
        my $i = 10_000_000;
        rand while $i--;
    } '10 million rands';

Executes BLOCK and print a timing message to STDERR when done, similar to the Linux time commands, reporting real, user and sys times taken by the execution of block up to the millisecond.

The NAME argument is optional and inteneded to help identify the timed block in the printed message. If none is provided the filename and line of the dt command is used.

Similarly to do, dt returns the value of the last command of the block, evaluated with the same context as the dt command itself.

dt does not print any timing message if $Devel::Util::QUIET is true.

Setting $Devel::Util::QUIET to true prevents dt from printing any timing message.

tz

tz BLOCK TZ

timezone BLOCK TZ

    tz {
        printf "Current time is %s\n", scalar localtime
    } 'Pacific/Honolulu';

Executes BLOCK, locally setting the TZ environement variable and calling POSIX::tzset

Similarly to do, tz returns the value of the last command of the block, evaluated with the same context as the tz command itself.

oiaw

oiaw BLOCK TIME

once_in_a_while BLOCK TIME

    my $i = 0;
    my $t = time;
    while (time-$t < 3) {
        ++$i;
        oiaw {
            print STDERR "\rprogress: $i"
        } 0.5;
    }

Execute BLOCK only when at least TIME seconds have passed since the last call to that same block.

TIME can be fractional.

oiaw can also return a code reference to be used afterward:

    my $i = 0;
    my $t = time;
    my $progress = oiaw { print STDERR "\rprogress: $i" } 0.5;
    while (time-$t < 3) {
        ++$i;
        $progress->();
    }

This second form is faster as the closure is only created once, and also makes it easier to silence by setting the code reference to an empty sub.

printr

printr STR

printr FORMAT, LIST

print_refresh STR

print_refresh FORMAT, LIST

    printr 'this';
    sleep 1;
    printr 'is';
    sleep 1;
    printr 'simple';

printr prints STR to STDERR, replacing anything formerly printr-ed on the same line.

It uses \b characters to delete previous messages in a controlled way, playing nice with \n, shorter strings, or strings with a common prefix.

If more than one argument is used, printr formats its output similarly to what printf does:

    printr '1+1=%d', 1+1;

    # same as:
    printr sprintf('1+1=%d', 1+1);

It makes sure everything that is common is not deleted, and that everything that is longer than the new message.

Of course any interlaced direct call to print STDERR will prevent printr to work properly on a given line.

Setting $Devel::Util::QUIET to true makes printr no-op.

forked

    if (forked) {
        warn 'We are in a forked process'
    } else {
        warn 'We are in the main process'
    }

Returns true if current PID is different than when the module was loaded.

$Devel::Util::QUIET

If set to true, dt and printr do not print anything.

oiaw is not affected as it can be used to do other things than printing progress.

This variable has also no effect on tz and forked.

EXPORTS

Nothing by default. Functions can be imported explicitly, by their short or long aliases

    # short
    use Devel::Util qw(dt tz oiaw printr forked);

    # long
    use Devel::Util qw(do_time timezone once_in_a_while print_refresh forked);

    # everything
    use Devel::Util qw(:all);

SEE ALSO

Scalar::Util, List::Util

AUTHOR

Thomas Drugeon, <tdrugeon@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2021 by Thomas Drugeon

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10 or, at your option, any later version of Perl 5 you may have available.

cpanm Devel::Util

perl -MCPAN -e shell
install Devel::Util