Peta::Shell::Printer#

show a Perl value as bounded, readable text

SYNOPSIS#

use Peta::Shell::Printer;

my $printer = Peta::Shell::Printer->new(width => 72);

print $printer->format(42), "\n";                 # 42
print $printer->format('$5 each'), "\n";          # '$5 each'
print $printer->format("a\tb"), "\n";             # "a\tb"
print $printer->format(1, 2, 3), "\n";            # (1, 2, 3)
print $printer->format({ b => [1, 2], a => undef }), "\n";
                                                  # { a => undef, b => [1, 2] }

DESCRIPTION#

format turns values into text.

  • A number is shown bare, a string quoted, undef as undef, a boolean as true or false. Whether a scalar is a number or a string is what it was created as: 42 and '42' look different. A float is shown with as many digits as it takes to read it back as the same number: 0.1 + 0.2 is 0.30000000000000004.

  • A string is quoted so that it needs as few escapes as it allows; what is shown is Perl that evaluates to the string.

    text                 'text'
$x and @y            '$x and @y'
say "hi"             'say "hi"'
it's "quoted"        q{it's "quoted"}
C:\dir\file          'C:\dir\file'
a tab inside         "a\tb"
a tab and a "        qq{a\t"b"}

    When nothing in it has to be written as an escape sequence it is in a literal form, where $, @ and " are characters like any other: '...', or q{...} when it has a single quote, with the first of {}, (), [], <> that does not occur in it. When it has a character that cannot be shown as itself it is in an interpolating form, "..." or qq{...} by the same choice. Shown as a number, never as themselves, are control characters, the bytes above 127 of a byte string, and in a character string whatever has no shape of its own or changes how its neighbours are laid out: a zero-width space, a direction override, a no-break space.

  • An array is [1, 2, 3], a hash { key => value } with its keys sorted. Both stay on one line when they fit the width and are laid out one element per line when they do not.

  • An object is its class in front of its contents, Point { x => 1 }, or its class and its string when it overloads stringification: URI("http://example.com/").

  • A code reference is \&main::name when the sub has a name and sub { ... } when it has none. A compiled pattern is qr/.../, a glob \*main::STDOUT, a reference to a scalar \"text".

  • Several values are a list in parentheses. No value at all is the empty string.

Everything is bounded: a container shows its first max_items elements and says how many more there are, nesting stops at max_depth, a string is cut at max_string characters with its full length noted. A structure that contains itself is shown once and marked where it repeats.

METHODS#

new#

my $printer = Peta::Shell::Printer->new(%options);

  • width

    Columns available; a container that fits is printed on one line. Default 80.

  • max_items

    Elements of one array or hash to show. Default 24. 0 means all.

  • max_depth

    Levels of nesting to show. Default 6. 0 means all.

  • max_string

    Characters of one string to show. Default 240. 0 means all.

  • indent

    Spaces per level in the multi-line layout. Default 2.

format#

my $text = $printer->format(@values);

The values as text, without a trailing newline.