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

VERSION
    This document describes String::Dump version 0.04.

SYNOPSIS
        use String::Dump;

        say 'hex: ', dumpstr($string);  # hex mode by default
        say 'oct: ', dumpstr(oct => $string);  # octal mode

DESCRIPTION
    This module provides the "dumpstr" function and exports it by default.
    Those who prefer their function names unabridged may manually export
    "dump_string" instead. When debugging or reviewing strings containing
    non-ASCII or non-printing characters, "dumpstr" is your friend. It's a
    simple utility to view 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 "dumpstr" function will remain
    simple.

  dumpstr($mode, $string)
    The mode is optional and defaults to "hex". Other valid modes are "dec",
    "oct", "bin", and "names", and are described below. The string may
    either be a series of Unicode characters or binary bytes.

  Modes
   hex
    Hexadecimal (base 16) mode. This is the default when only a string is
    passed without the mode.

        use utf8;
        # string of 6 characters
        say dumpstr('Ĝis! ☺');  # 11C 69 73 21 20 263A
        say dumpstr(hex => 'Ĝis! ☺');  # same thing

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

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

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

   dec
    Decimal (base 10) mode.

        use utf8;
        say dumpstr(dec => 'Ĝis! ☺');  # 284 105 115 33 32 9786

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

   oct
    Octal (base 8) mode.

        use utf8;
        say dumpstr(oct => 'Ĝis! ☺');  # 434 151 163 41 40 23072

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

   bin
    Binary (base 2) mode.

        use utf8;
        say dumpstr(bin => 'Ĝis! ☺');
        # 100011100 1101001 1110011 100001 100000 10011000111010

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

   names
    Named Unicode character mode. Unlike the various numeral modes above,
    this mode uses ', ' for the delimiter.

        use utf8;
        say dumpstr(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 dumpstr(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.

  Tips
   Literal strings
    When dumping literal strings in your code, as in the examples above, use
    the utf8 pragma when strings of Unicode characters are desired and don't
    use it or disable it when series of bytes are desired. The pragma may
    also be lexically enabled or disabled.

        use utf8;

        {
            no utf8;
            say dumpstr('Ĝis! ☺');  # C4 9C 69 73 21 20 E2 98 BA
        }

        say dumpstr('Ĝis! ☺');  # 11C 69 73 21 20 263A

   Command-line input and filehandles
    The simplest way to ensure that you're working with strings of
    characters from all of your basic sources of input is to use the
    utf8::all pragma. This extends the utf8 pragma to automatically convert
    command-line arguments provided by @ARGV, user-defined filehandles, as
    well as "STDIN", among others.

   Other sources of input
    To handle strings provided by other sources of input, such as from
    network protocols or a web server request, pass the value to
    Encode::decode_utf8, which will return the desired string.

        use Encode;

        say dumpstr( decode_utf8($string) );

    To convert a variable in-place, pass it to utf8::decode instead.

        utf8::decode($string);

        say dumpstr($string);

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
    *   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.