<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Peta/Shell/Printer.md. Do not edit. -->

```{index} single: Peta::Shell::Printer
```

# Peta::Shell::Printer

show a Perl value as bounded, readable text

## SYNOPSIS

```perl
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.

    ```perl
    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

```perl
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

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

The values as text, without a trailing newline.