/ 
Devel-Bug-0.02
/ Devel::Bug

NAME

Devel::Bug - Transparent inline debugging probe (pure Perl)

SYNOPSIS

use Devel::Bug;                           # output to STDERR
use Devel::Bug out => *STDOUT;            # redirect output
use Devel::Bug ':pfl';                    # package + filename + lineno by default
use Devel::Bug ':pfl', out => *STDOUT;    # label:flags with options
use Devel::Bug bug => 'dbg';              # export under a different name

# Scalar: value passes through; appears on STDERR (no label)
my $result = bug = substr($str, $offset);
# OUTPUT: (value)

# Inline in any expression
my $path = $dir . '/' . (bug('label') = substr($str, $offset));
# OUTPUT: label=(images/logo.png)

# List: parens around bug() are required to force list-context assignment
my @items = (bug 'items') = get_items();
# OUTPUT: items=(foo bar baz)

# Flags in the label string
my @items = (bug 'items:@')  = get_items();   # N: index prefixes
my %hash  = (bug 'data:%')   = get_pairs();   # key => value format
my %hash  = (bug 'data:@%')  = get_pairs();   # both
my @items = (bug 'items:m')  = get_items();   # multiline

# Per-call options
my $x = (bug 'result', vc => 'green') = compute();

DESCRIPTION

Devel::Bug exports bug(), named for the wiretap sense of the word: plant it inline inside any existing assignment to tap into values as they flow through your code. The value(s) assigned through bug() will reach the left-hand side unmodified; the only side effect is output to the configured filehandle. For list assignments, bug() must be wrapped in parentheses to force list context: (bug ...) = list_expr(). Without them bug is called in scalar context and captures only a single value.

Output format:

label=(value)               # scalar
label=(v1 v2 v3)            # list
label=(a => 1 b => 2)       # keyval
pkg file line: label=(...)  # with caller info enabled

By default, ANSI colors are applied when the output handle is a terminal, and multiline layout is applied automatically when output would overflow the terminal width. Both behaviors are configurable; see color, delims, and noterm.

IMPORT AND CALL OPTIONS

Options apply in two contexts: as import-time defaults via use or import(), and as per-call overrides passed directly to bug().

use Devel::Bug out => *STDOUT, lineno => 1;       # import-time defaults
my $x = (bug 'result', vc => 'green') = ...;      # per-call override

Options follow an optional label:flags string as key/value pairs (see "LABEL:FLAGS SYNTAX"). The bug option (export name) is only valid at import time.

Output

out (aliases: output, o)

Filehandle to print to. Accepts anything print accepts as an indirect filehandle: typeglobs, lexical filehandles, and filehandle objects. Default: *STDERR.

use Devel::Bug out => *STDOUT;    # typeglob
use Devel::Bug out => $fh;        # lexical filehandle or object

Caller information

When enabled, the corresponding field is prepended to every line of output.

package (aliases: pkg, p)

Calling package name.

filename (aliases: fn, f)

Source filename.

lineno (aliases: line, ln, l)

Source line number.

Display

multiline (aliases: ml, m)

Print each value on its own indented line.

indices (aliases: indexes, index, i, @)

Prefix each list element with N:. Implies multiline.

keyval (aliases: kv, k, %)

Treat the list as alternating key/value pairs and format each as key => value. Combine with indices/@ to add N: prefixes; the index counts pairs, not individual elements. Implies multiline.

delims (aliases: delimiters, d)

Controls whether the value is wrapped in parentheses. Three states:

on (also 1)

Always wrap in parentheses.

off (also undef)

Never wrap in parentheses.

auto (also '', default)

Wrap when output is not colored; omit when colored (color already delineates the value visually).

Colors

color

Controls when ANSI colors are applied. Three states:

on (also 1)

Always apply colors, even to non-terminal output.

off (also undef)

Never apply colors.

auto (also '', default)

Apply colors only when the output handle is a terminal.

infocolor (alias: ic)

Term::ANSIColor color specification for the caller-info prefix, e.g. 'bold', 'cyan on_black'. Default: none.

labelcolor (alias: lc)

Color specification for the label. Default: 'bold'.

valcolor (aliases: vc, valuecolor)

Color specification for values. Default: 'red on_grey23'.

Terminal detection

noterm (aliases: noterminal, n)

Disable terminal width detection. When set, neither stty nor Term::Size::Perl is consulted, making both entirely optional. With noterm enabled, terminal-width-based multiline layout is suppressed, and color => 'auto' behaves as if the output is not a terminal.

A warning is issued if terminal detection is attempted, stty size fails, and Term::Size::Perl cannot be loaded. Set noterm to suppress both the detection and the warning.

Pretty-printer

pp

Fully-qualified name of the function used to format reference values, in the form 'Module::Name::function'. The function is called with the reference as its first argument and must return a string. The module is loaded automatically on first use. If the specified module cannot be loaded or the named sub does not exist, a warning is issued and the default is used instead.

Default: 'Data::Dumper::Dumper'.

use Devel::Bug pp => 'Data::Dump::pp';          # import-time default
my $x = (bug 'data', pp => 'Data::Dump::pp') = get_data();  # per-call

Alternative display value

val (aliases: value, v, override)

Display a different value in the output than the one being assigned. The actual assigned value still passes through unchanged.

Use this when the assigned value is opaque or uninteresting, but a related value at the same point in the code is more informative. Particularly useful in ternary expressions, where the probe fires only when that branch is taken.

# Without bug(): a do {} block is needed to log and still return a value
my $installed =
    $sub =~ /^(.+)::/
    ?   do {
            print "package=($1)\n";
            *{ $caller . '::' . $name }= \&{ $sub }
        }
    :   carp "Cannot determine package from '$sub'";

# With bug(): val => $1 is displayed; the glob assignment passes through
my $installed =
    $sub =~ /^(.+)::/
    ?   bug('package', val => $1)=
            *{ $caller . '::' . $name }= \&{ $sub }
    :   carp "Cannot determine package from '$sub'";

Export name

bug

Rename or suppress the exported function.

use Devel::Bug bug => 'tap';   # exports as tap()
use Devel::Bug bug => '';      # suppresses export  ('', 0, undef all work)

The name must be a valid Perl identifier (/^[a-z]\w*$/i or /^_\w+$/). This option is only valid at import time; it may not be passed to bug().

LABEL:FLAGS SYNTAX

A label:flags string may optionally appear as the first argument to bug() or use (import()).

The string has the form label:flags, where both parts are optional. A leading colon means an empty label; the characters after the colon each enable a boolean option by its single-char alias.

use Devel::Bug ':pfl';            # empty label, flags p, f, l
use Devel::Bug 'app:pf';          # label 'app', flags p, f
use Devel::Bug 'app';             # label 'app', no flags

my @r = (bug 'data:@%') = ...;   # label 'data', flags @ and %
my @r = (bug ':m')      = ...;   # empty label, flag m

Flag characters:

@   i   indices      %   k   keyval       m   multiline
p       package      f       filename     l   lineno
d       delims       n       noterm

CHAINING

Bug probes can be placed at different points in a pipeline to capture each intermediate value independently.

my @data = (1, 2, 3, 4, 5, 6);
my @doubled =
    (bug 'doubled')=      # parens make this a list assignment; bug() passes the whole list through
    map  { $_ * 2 }
    (bug 'evens')=        # parens force list context; without them bug() captures only one value
    grep { $_ % 2 == 0 } @data;

# OUTPUT:
# doubled=(4 8 12)
# evens=(2 4 6)

'evens' captures the elements that passed the grep; 'doubled' captures those elements after multiplication. Output fires left-to-right as Perl frees temporaries at end-of-statement, which is the reverse of data flow - hence 'doubled' prints before 'evens'.

DEPENDENCIES

Term::ANSIColor, Data::Dumper.

Terminal width detection first tries stty size. Term::Size::Perl is loaded on demand only if stty is unavailable or returns no output, and is never consulted when noterm is set.

Data::Dump and other pretty-printer modules are optional; see the pp option.

AUTHOR

Kevin Shea

LICENSE

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