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

VERSION
    This document describes String::Dump version 0.01.

SYNOPSIS
        use String::Dump;

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

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

DESCRIPTION
    This module provides the function "dump_string" and exports it by
    default. When debugging or reviewing non-ASCII data, "dump_string" 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 be the ability to
    set the delimiter between characters and to force a string to be treated
    as a string of characters or a series of bytes. Don't worry, the
    "dump_string" function will remain simple.

  dump_string($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 dump_string('Ĝis! ☺');  # 11C 69 73 21 20 263A
        say dump_string(hex => 'Ĝis! ☺');  # same thing

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

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

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

   dec
    Decimal (base 10) mode.

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

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

   oct
    Octal (base 8) mode.

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

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

   bin
    Binary (base 2) mode.

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

        no utf8;
        say dump_string(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 dump_string(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_string(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 dump_string('Ĝis! ☺');  # C4 9C 69 73 21 20 E2 98 BA
        }

        say dump_string('Ĝ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 dump_string( decode_utf8($string) );

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

        utf8::decode($string);

        say dump_string($string);

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