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-DDhh:mm:ss) (localtime) %D Current date in ISO8601 format (YYYY-MM-DDhh: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 . COLOR Force enabling/disabling color. If unset, will enable color when output is interactive, disable otherwise. HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website 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 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.