Test::...HexDump(3pm)

🌸 Test::HexDifferences::HexDump — the glow-up guide 🌸

okay bestie, come sit with me because we're about to make binary data look cute. this is the perl manual page for Test::HexDifferences::HexDump (you'll also see it filed under the manual name Test::...HexDump(3pm), that's just the same girl in a different outfit 💅), and she formats binary into hexadecimal strings. iconic behavior fr fr.

---

✨ NAME ✨

Test::HexDifferences::HexDump — Format binary to hexadecimal strings 🦋

✨ VERSION ✨

0.008 — yes ma'am, we're on 0.008, she's vintage, she's timeless 💖

✨ SYNOPSIS ✨

okay so here's the vibe. you pull the module in, you hand it some binary, and it gives you back a string:

use Test::HexDifferences::HexDump;

$string = hex_dump(
    $binary,
);

and if you want to be extra (we love extra), you pass in a hashref with your own address and format:

$string = hex_dump(
    $binary,
    {
        address => $start_address,
        format  => "%a : %4C : %d\n",
    }
);

🎀 Format elements

every format element in the format string starts with %, just like sprintf. no cap. 🌈

if the format you gave is shorter than what the data length needs, the leftover data gets shown in the default format. if the format you gave is longer than the data length, the output gets filled with space and it stops before the next repetition. periodt. 💅

💖 Data format

ngl it is not very clever to use little-endian formats for tests. there's a fallback to bytes if multibyte formats can not be displayed. so like, the safety net is real. 🫶

• %C — unsigned char
• %S — unsigned 16-bit, endian depends on machine
• %S< — unsigned 16-bit, little-endian
• %S> — unsigned 16-bit, big-endian
• %v — unsigned 16-bit, little-endian
• %n — unsigned 16-bit, big-endian
• %L — unsigned 32-bit, endian depends on machine
• %L< — unsigned 32-bit, little-endian
• %L> — unsigned 32-bit, big-endian
• %V — unsigned 32-bit, little-endian
• %N — unsigned 32-bit, big-endian
• %Q — unsigned 64-bit, endian depends on machine
• %Q< — unsigned 64-bit, little-endian
• %Q> — unsigned 64-bit, big-endian

pack and unpack before Perl v5.10 do not allow < and > to mark the byte order. here? allowed for all Perl versions. we don't gatekeep. ✨

pack and unpack on a 32 bit machine do not allow the Q formats. here? allowed for all machines. inclusivity queen 👑

💜 Address format

• %a — 16 bit address
• %4a — 16 bit address
• %8a — 32 bit address

💙 ASCII format

it can not display all chars, sorry babe. first it must be a printable ASCII char. and it can not be anything of space, q{.}, q{'}, q{"} or q{\}. otherwise q{.} will be printed. that's the rule, we live by it. 💀

• %d — display ASCII

💚 Repetition

• %*x — repetition endless
• %1x — repetition 1 time
• %2x — repetition 2 times
• ...

🧚 Special formats

• %\n — ignore \n

🌟 Default format

the default format is:

"%a : %4C : %d\n"

or, fully written out, she's serving:

"%a : %4C : %d\n%*x"

🦋 Complex formats

the %...x lets you write mixed formats, e.g.

Format:
 %a : %N %4C : %d\n%1x%
 %a : %n %2C : %d\n%*x
Input:
   \0x01\0x23\0x45\0x67\0x89\0xAB\0xCD\0xEF
   \0x01\0x23\0x45\0x67
   \0x89\0xAB\0xCD\0xEF
Output:
   0000 : 01234567 89 AB CD EF : .#-Eg...
   0008 : 0123 45 67 : .#-E
   000C : 89AB CD EF : g...

look at that output. literally chef's kiss. 🔥

✨ EXAMPLE ✨

inside of this Distribution is a directory named example. run this *.t files. 🎀

✨ DESCRIPTION ✨

this is a formatter for binary data. that's it, that's the whole vibe. 🍓

✨ SUBROUTINES/METHODS ✨

🌸 subroutine hex_dump

$string = hex_dump(
    $binary,
    {
        address => $display_start_address,
        format  => $format_string,
    }
);

bestie this is the main character right here. give her binary, get back a string. 👑

✨ DIAGNOSTICS ✨

nothing. she's quiet. lowkey mysterious. 🙈

✨ CONFIGURATION AND ENVIRONMENT ✨

nothing. no env vars, no config files, we keep it minimal. ✨

✨ DEPENDENCIES ✨

• Hash::Util
• Sub::Exporter

✨ INCOMPATIBILITIES ✨

none. she gets along with everyone. 🫶

✨ BUGS AND LIMITATIONS ✨

none. no bugs, no limitations, she's perfect, and I will not be taking questions. 💅

✨ SEE ALSO ✨

• Test::HexDifferences
• Data::Hexdumper inspired by

✨ AUTHOR ✨

Steffen Winkler 🌟

✨ LICENSE AND COPYRIGHT ✨

Copyright (c) 2012 - 2014, Steffen Winkler "<steffenw at cpan.org>". All rights reserved.

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

---

and that's the whole page, bestie. no notes. go format something pretty. 💖

mwah 💋 — this was perl v5.30.3, dated 2020-08-04, and yes the manual page is still called Test::...HexDump(3pm) even though the module is Test::HexDifferences::HexDump. she contains multitudes. ✨