[ANN] hexy.js : hexdump Buffers

[Tim Becker]

Hi,

Trying to debug binary protocol stuff by `console.log`ing buffers made
me VERY angry, so I wrote a little utility to pretty print them, just
like `xxd`.

Below is the README, which should contain all pertinent information.

Cheers,
-tim

= hexy.js -- utility to create hex dumps

`hexy` is a javascript (node) library that's easy to use to create
hex
dumps from within node. It contains a number of options to configure
how the hex dumb will end up looking.

It should create a pleasant looking hex dumb by default:

var hexy = require('hexy.js'),
b = new
Buffer("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789")

console.log(hexy.hexy(b))

results in this dump:

0000000: 00 01 03 05 1f 0a 09 62 63 64 65 66 67 68 69
6a .......b cdefghij
0000010: 6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79 7a
klmnopqr stuvwxyz
0000020: 30 31 32 33 34 35 36 37 38 39
01234567 89

but it's also possible to configure:

* Line numbering
* Line width
* Format
* Case of hex decimals
* Presence of the ASCII annotation in the right column.

This mean you can do exciting dumps like:

0000000: 0001 0305 1f0a 0962 .... ...b
0000008: 6364 6566 6768 696a cdef ghij
0000010: 6b6c 6d6e 6f70 7172 klmn opqr
0000018: 7374 7576 7778 797a stuv wxyz
0000020: 3031 3233 3435 3637 0123 4567
0000028: 3839 89

or even:

0000000: 00 01 03 05 1f 0a 09 62 63 64 65 66 67 68 69 6a
0000010: 6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79 7a
0000020: 30 31 32 33 34 35 36 37 38 39

with hexy!

Formatting options are configured by passing a `format` object to the
`hexy` function:

var format = {}
format.width = width // how many bytes per line, default 16
format.numbering = n // ["hex_bytes" | "none"], default
"none"
format.format = f // ["fours"|"twos"|"none"], how many
nibbles per group
// default
"fours"
format.caps = c // ["lower"|"upper"], default lower
format.annotate=a // ["ascii"|"none"], ascii annotation at
end of line?
// default
"ascii"
format.prefix=p // <string> something pretty to put in
front of each line
// default ""
format.indent=i // <num> number of spaces to indent
// default 0

console.log(hexy.hexy(buffer, format))

In case you're really nerdy, you'll have noticed that the defaults
correspond
to how `xxd` formats it's output.


== Installing

Either use `npm`:

npm install hexy.js

This will install the lib which you'll be able to use like so:

var hexy = require("hexy.js"),
buf = // get Buffer from somewhere,
str = hexy.hexy(buf)

It will also install `hexy.js` into your path in case you're totally
fed up
with using `xxd`.


If you don't like `npm`, grab the source from github:

http://github.com/a2800276/hexy.js

== TODOS

The current version only pretty prints Buffers. Which probably means
it
can only be used from within node. What's more important what it
doesn't support: Strings (which would be nice for the sake of
completeness) and Streams/series of Buffers which would be nice so
you
don't have to collect the whole things you want to pretty print in
memory. `hexy` is probably most useful for debugging and getting
binary
protocol stuff working, so that's probably not an too much of an
issue.

== History

This is a fairly straightforward port of `hexy.rb` which does more or
less the
same thing. You can find it here:

http://github.com/a2800276/hexy

in case these sorts of things interest you.

== Mail

In case you discover bugs, spelling errors, offer suggestions for
improvements or would like to help out with the project, you can
contact
me directly (t...@kuriositaet.de).

[Tim Becker]

Oh good grief, the google groups formatting kill the README.
In case you're interested in making hexdumps, go here:

http://github.com/a2800276/hexy.js

Sorry about that.
-tim

[Isaac Schlueter]

Awesome. This is really handy :)

I'd recommend naming the package in npm just simply "hexy" rather than
"hexy.js". I know that there's a ruby program called "hexy" already,
but npm is sort of assumed to be for js programs only, so the ".js" is
implied in that context. Also, this means that you'll have folders
named "hexy.js", which is just weird.

Then you can do require("hexy") rather than require("hexy.js"). Both
work if you've put the hexy.js file in the require path, but
require("hexy") will still work either way. (If you rename the
package, then require("hexy.js") won't work, because the "main" module
will actually live at hexy/index.js)

--i

> --
> You received this message because you are subscribed to the Google Groups "nodejs" group.
> To post to this group, send email to nod...@googlegroups.com.
> To unsubscribe from this group, send email to nodejs+un...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/nodejs?hl=en.
>
>

[Tim Becker]

> I'd recommend naming the package in npm just simply "hexy" rather than
> "hexy.js".

I was in fact aware of that, and decided to call it hexy.js for the
reasons you mentioned.
BUT, I am a big fan of "when in rome, do as the romans" (I even indent
with *gasp* inferior spaces), though, and well shucks, I guess you're
right...
So I'll just leave the library's real name on github as hexy.js to
keep tell the two apart and change the npm name to `hexy` for nicer
importing.

Thanks for the reminder,
-tim

[Isaac Schlueter]

Kewl. Once you publish it as "hexy", you can "npm unpublish hexy.js".
Best to do that asap, so there's less chance of someone depending on
"hexy.js" in their package.

--i

[Jeremy Johnstone]

On Tue, Sep 21, 2010 at 11:38 AM, Isaac Schlueter <i...@izs.me> wrote:

Awesome.  This is really handy :)

I couldn't agree more! Was about to code up something like this myself, so glad I read the list instead. :)

-Jeremy 

[Tim Becker]

> Kewl.  Once you publish it as "hexy", you can "npm unpublish hexy.js".
>  Best to do that asap, so there's less chance of someone depending on
> "hexy.js" in their package.

I've renamed the package...

It's now called:

hexy

From within npm. The github project name is still hexy.js, because I
wrote the same thing for ruby as well.
So in case anyone needs beautiful hexdumps of `Buffer`s in node like
this:

00000000: 7661 7220 6820 3d20 7265 7175 6972 6528
00000010: 2768 6578 7927 290a 636f 6e73 6f6c 652e
00000020: 6c6f 6728 6829 0a

or like this:

00000000: 7661 7220 6820 3d20 var.h.=.
00000008: 7265 7175 6972 6528 require(
00000010: 2768 6578 7927 290a 'hexy').
00000018: 636f 6e73 6f6c 652e console.
00000020: 6c6f 6728 6829 0a log(h).

or EVEN like so:

76 61 72 20 68 20 3d 20 var.h.=.
72 65 71 75 69 72 65 28 require(
27 68 65 78 79 27 29 0a 'hexy').
63 6f 6e 73 6f 6c 65 2e console.
6c 6f 67 28 68 29 0a log(h).


you can install hexy with this command:

npm install hexy

and then use it by requiring `hexy`.

If you've already installed the original version, please uninstall
first:

npm uninstall hexy.js

and require 'hexy' instead of 'hexy.js'

Cheers,
-tim

ps incidentally, I'm nearly certain I already successfully posted
this, my apologies if this is a double post.