NAME
    String::Dump - Dump strings of characters or bytes for printing and
    debugging

VERSION
    This document describes String::Dump version 0.05.

SYNOPSIS
        use String::Dump;

        say 'hex: ', dump_hex($string);  # hex mode
        say 'oct: ', dump_oct($string);  # octal mode

DESCRIPTION
    When debugging or reviewing strings containing non-ASCII or non-printing
    characters, String::Dump is your friend. It provides simple functions to
    return a dump of the characters or bytes of your string in several
    different formats, such as hex, octal, decimal, Unicode names, and more.

    An OO interface is forthcoming with additional options and the ability
    to reuse them among multiple calls. Some benefits will include the
    ability to set the delimiter between characters, set padding for the
    characters, and force a string to be treated as a string of characters
    or a series of bytes. Don't worry, the standard functions will remain
    simple.

    Check out String::Dump::Debugging for tips on debugging Unicode and
    encoded strings with this module. Also check out the bundled
    command-line tool dumpstr.

FUNCTIONS
    The following functions are all exported by default. This is convenient
    for debugging and one-liners, but explicitly exporting individual
    functions is recommended in other cases. It's up to you!

    These functions all accept a single argument: the string to dump, which
    may either be a Perl internal string or an encoded series of bytes.

  dump_hex($string)
    Hexadecimal (base 16) mode.

        use utf8;
        # string of 6 characters
        say dump_hex('Ĝis! ☺');  # 11C 69 73 21 20 263A

        no utf8;
        # series of 9 bytes
        say dump_hex('Ĝis! ☺');  # C4 9C 69 73 21 20 E2 98 BA

    For a lowercase hex dump, simply pass the response to "lc".

        say lc dump_hex('Ĝis! ☺');  # 11c 69 73 21 20 263a

  dump_dec($string)
    Decimal (base 10) mode.

        use utf8;
        say dump_dec('Ĝis! ☺');  # 284 105 115 33 32 9786

        no utf8;
        say dump_dec('Ĝis! ☺');  # 196 156 105 115 33 32 226 152 186

  dump_oct($string)
    Octal (base 8) mode.

        use utf8;
        say dump_oct('Ĝis! ☺');  # 434 151 163 41 40 23072

        no utf8;
        say dump_oct('Ĝis! ☺');  # 304 234 151 163 41 40 342 230 272

  dump_bin($string)
    Binary (base 2) mode.

        use utf8;
        say dump_bin('Ĝis! ☺');
        # 100011100 1101001 1110011 100001 100000 10011000111010

        no utf8;
        say dump_bin('Ĝis! ☺');
        # 11000100 10011100 1101001 1110011 100001 100000 11100010 10011000 10111010

  dump_names($string)
    Named Unicode character mode. Unlike the various numeral modes above,
    this mode uses ', ' for the delimiter.

        use utf8;
        say dump_names('Ĝis! ☺');
        # LATIN CAPITAL LETTER G WITH CIRCUMFLEX, LATIN SMALL LETTER I,
        # LATIN SMALL LETTER S, EXCLAMATION MARK, SPACE, WHITE SMILING FACE

    This mode makes no sense for a series of bytes, but it still works if
    that's what you really want!

        no utf8;
        say dump_names('Ĝis! ☺');
        # LATIN CAPITAL LETTER A WITH DIAERESIS, STRING TERMINATOR,
        # LATIN SMALL LETTER I, LATIN SMALL LETTER S, EXCLAMATION MARK,
        # SPACE, LATIN SMALL LETTER A WITH CIRCUMFLEX, START OF STRING,
        # MASCULINE ORDINAL INDICATOR

    The output in the examples above has been manually split into multiple
    lines for the layout of this document.

CONTRIBUTIONS
    This is an early release of String::Dump. Feedback is appreciated! To
    give suggestions or report an issue, contact <mailto:patch@cpan.org> or
    open an issue at <https://github.com/patch/string-dump-pm5/issues>. Pull
    requests are welcome at <https://github.com/patch/string-dump-pm5>.

SEE ALSO
    *   dumpstr - Dump strings of characters on the command line

    *   String::Dump::Debugging - String debugging tips with String::Dump

    *   Template::Plugin::StringDump - String::Dump plugin for TT

    *   Data::HexDump - Simple hex dumping using the default output of the
        Unix "hexdump" utility

    *   Data::Hexdumper - Advanced formatting of binary data, similar to
        "hexdump"

AUTHOR
    Nick Patch <patch@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2011 Nick Patch

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

