/ 
Debug-Print-0.003
River stage one • 1 direct dependent • 1 total dependent
/ Debug::Print

NAME

Debug::Print - Make debugging with print() more awesome

VERSION

This document describes version 0.003 of Debug::Print (from Perl distribution Debug-Print), released on 2019-09-17.

SYNOPSIS

Example script myscript.pl:

#!/usr/bin/env perl

sub f1 {
    print "Doing stuffs in f1\n";
    for (1..2) { f2(); sleep 1 }
}

sub f2 {
    print "DEBUG: Doing sumtin' in f2\n";
}

f1;

Add more information to your print()

On the command-line:

% perl -MDebug::Print=template,'%d (%F:%L)> %m' myscript.pl

Sample output:

2018-12-20T20:55:00 (script.pl:4)> Doing stuffs in f1
2018-12-20T20:55:00 (script.pl:9)> DEBUG: Doing sumtin' in f2
2018-12-20T20:56:00 (script.pl:9)> DEBUG: Doing sumtin' in f2

Add color

% perl -MDebug::Print=template,'%d (%F:%L)> %m',color,green myscript.pl

Filter

Only show messages that start with "DEBUG:"

% perl -MDebug::Print=template,'%d (%F:%L)> %m',filter,'/\ADEBUG:/' myscript.pl

Sample output:

2018-12-20T20:55:00 (script.pl:9)> DEBUG: Doing sumtin' in f2
2018-12-20T20:56:00 (script.pl:9)> DEBUG: Doing sumtin' in f2

Don't show messages that start with "DEBUG:"

% perl -MDebug::Print=template,'%d (%F:%L)> %m',filter,'!/\ADEBUG:/' myscript.pl

Sample output:

2018-12-20T20:55:00 (script.pl:4)> Doing stuffs in f1

DESCRIPTION

One of the simplest (and oldest) debugging technique is adding print statements to your code. Although not very flexible, it forever remains as one of programmers' favorites.

This module allows you to:

  • Add more information to your print()

    For example: filename and line, timestamp.

  • Add color

  • Filtering

    For example: don't output if string matches qr/\ADEBUG:/.

so debugging using print() can be more useful. (Although I still recommend you to use a proper logging framework.)

This module works by intercepting output to STDOUT using Tie::STDOUT, then filter and/or post-process the output.

Caveat: This module is still in its early development. API might change. Current limitations:

  • Only print() to STDOUT is captured

    Output to STDERR or other filehandles are currently not captured.

    printf() is currently not captured.

IMPORTS

Usage:

use Debug::Print %opts;

The following are known import options:

template

A sprintf()-like layout string to print the print() arguments itself as well as additional information. The following are the known conversions (which are modelled after Log::ger::Layout::Pattern):

%C Fully qualified package (or class) name of the caller
%d Current date in ISO8601 format (YYYY-MM-DD<T>hh:mm:ss) (localtime)
%D Current date in ISO8601 format (YYYY-MM-DD<T>hh:mm:ss) (GMT)
%F File where the print occurred
%H Hostname (if Sys::Hostname is available)
%l Fully qualified name of the calling method followed by the
   callers source the file name and line number between
   parentheses.
%L Line number within the file where the print statement was issued
%m The message to be printed (the actual print() arguments, joined)
%M Method or function where the print was issued
%n Newline (OS-independent)
%P pid of the current process
%r Number of seconds elapsed from program start to logging event
%R Number of seconds elapsed from last logging event to current
   logging event
%T A stack trace of functions called
%% A literal percent (%) sign

If unspecified, the default template is "%m" (just the print() arguments, without additional information).

color

A color name recognized by Term::ANSIColor.

filter

A coderef that will be passed the string to be printed. Should return true if this message should be printed, or false otherwise. As a convenience, the topic variable ($_) is also locally set to the string to be printed.

ENVIRONMENT

NO_COLOR

Force disabling color. Will be consulted before "COLOR". See https://no-color.org.

COLOR

Force enabling/disabling color. If unset, will enable color when output is interactive, disable otherwise.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Debug-Print.

SOURCE

Source repository is at https://github.com/perlancar/perl-Debug-Print.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Debug-Print

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Consider using logging framework instead. Some logging frameworks I recommend: Log::ger, Log::Any. To switch from print to doing logging, you typically just need to add an extra use statement and replace your print() with log_debug() or some other routine. After that, you will get: easy turning on/off of logging by level, customizable output, and more. No need to modify your source code every time!

Devel::Confess can add call stack information to your warn()'s and die()'s.

Capture::Tiny can capture the output of stdout and/or stderr, as is Tie::STDOUT (which Debug::Print uses) or some other modules like Tie::STDERR or IO::Capture::Stdout.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.