Data::Hexdumper - Make binary data human-readable

    use Data::Hexdumper qw(hexdump);
    $results = hexdump(
        data           => $data, # what to dump
        number_format  => 'S',   # display as unsigned 'shorts'
        start_position => 100,   # start at this offset ...
        end_position   => 148    # ... and end at this offset
    );
    print $results;

    $results = hexdump($string);

    $results = hexdump(
        $string,
        { start_position => 100, end_position   => 148 }
    );

# $Id: Hexdumper.pm,v 1.6 2009/03/03 20:18:06 drhyde Exp $
package Data::Hexdumper;

$VERSION = "2.01";

require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(hexdump);

use strict;
use warnings;

use constant BIGENDIAN    => (unpack("h*", pack("s", 1)) =~ /01/);
use constant LITTLEENDIAN => (unpack("h*", pack("s", 1)) =~ /^1/);

# this is a magic number
use constant CHUNKSIZE => 16;

# static data, tells us the length of each type of word
my %num_bytes=(
    'C'  => 1, # unsigned char
    'S'  => 2, # unsigned 16-bit
    'L'  => 4, # unsigned 32-bit
    'L<' => 4, # unsigned 32-bit, little-endian
    'L>' => 4, # unsigned 32-bit, big-endian
    'V'  => 4, # unsigned 32-bit, little-endian
    'N'  => 4, # unsigned 32-bit, big-endian
    'S<' => 2, # unsigned 16-bit, little-endian
    'S>' => 2, # unsigned 16-bit, big-endian
    'v'  => 2, # unsigned 16-bit, little-endian
    'n'  => 2, # unsigned 16-bit, big-endian
    'Q'  => 8, # unsigned 64-bit
    'Q<' => 8, # unsigned 64-bit, little-endian
    'Q>' => 8, # unsigned 64-bit, big-endian
);

sub hexdump {
    my @params = @_;
    # first let's see if we need to massage the data into canonical form ...
    if($#params == 0) {                 # one param: hexdump($string)
        @params = (data => $params[0]);
    } elsif($#params == 1 && ref($params[1])) { # two: hexdump($foo, {...})
        @params = (
            data => $params[0],
            %{$params[1]}
        )
    }

    my %params=@params;
    my($data, $number_format, $start_position, $end_position)=
        @params{qw(data number_format start_position end_position)};

    my $addr = $start_position ||= 0;
    $number_format ||= 'C';
    $end_position ||= length($data)-1;
    my $num_bytes = $num_bytes{$number_format};
    if($number_format eq 'V') { $number_format = 'L<'; }
    if($number_format eq 'N') { $number_format = 'L>'; }
    if($number_format eq 'v') { $number_format = 'S<'; }
    if($number_format eq 'n') { $number_format = 'S>'; }

    # sanity-check the parameters

    die("No data given to hexdump.") unless length($data);
    die("start_position must be numeric.") if($start_position=~/\D/);
    die("number_format $number_format not recognised.") unless $num_bytes;
    die("end_position must be numeric.") if($end_position=~/\D/);
    die("end_position must not be before start_position.")
        if($end_position < $start_position);

    # extract the required range and pad end with NULLs if necessary

    $data=substr($data, $start_position, 1+$end_position-$start_position);
    if(length($data)/$num_bytes != int(length($data)/$num_bytes)) {
        warn "Data::Hexdumper: data doesn't exactly fit into an integer number ".
                 "of '$number_format' words,\nso has been padded ".
                 "with NULLs at the end.\n"
            unless($params{suppress_warnings});
        $data .= pack('C', 0) x ($num_bytes - length($data) + int(length($data)/$num_bytes)*$num_bytes);
    }

    my $output=''; # where we put the formatted results

    while(length($data)) {
        # Get a chunk
        my $chunk = substr($data, 0, CHUNKSIZE);
        $data = ($chunk eq $data) ? '' : substr($data, CHUNKSIZE);
        
        $output.=sprintf('  0x%04X : ', $addr);

        # have to keep chunk for printing, so make a copy we
        # can 'eat' $num_bytes at a time.
        my $line=$chunk;

        my $lengthOfLine=0;         # used for formatting in inner loop

        while(length($line)) {
            # grab a $num_bytes element, and remove from line
            my $thisElement=substr($line,0,$num_bytes);
            if(length($line)>$num_bytes) {
                $line=substr($line,$num_bytes);
            } else { $line=''; }
            my $thisData = _format_word($number_format, $thisElement);
            $lengthOfLine+=length($thisData);
            $output.=$thisData;
        }
        # replace any non-printable character with .
        if($params{space_as_space}) {
            $chunk=~s/[^a-z0-9\\|,.<>;:'\@[{\]}#`!"\$%^&*()_+=~?\/ -]/./gi;
                }
                else {
            $chunk=~s/[^a-z0-9\\|,.<>;:'\@[{\]}#`!"\$%^&*()_+=~?\/-]/./gi;
                }
        # Yes, this 48 *is* a magic number.
        $output.=' ' x (48-$lengthOfLine) .": $chunk\n";
        $addr += CHUNKSIZE;
    }
    $output;
}

sub _format_word {
    my($format, $data) = @_;

    # big endian
    my @bytes = map { ord($_) } split(//, $data);
    # make little endian if necessary
    @bytes = reverse(@bytes)
        if($format =~ /</ || ($format !~ />/ && LITTLEENDIAN));
    return join('', map { sprintf('%02X', $_) } @bytes).' ';
}

1;