/ 
String-Dump-0.01
River stage one • 4 direct dependents • 5 total dependents
/ String::Dump

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.