CLI Usage

$ </bin/ls hexer

API Usage

Simple mode: buffer -> string

Got as buffer? We can render it:

var hex = require('hexer');
console.log(hex(someBuffer));

Simply steram spy mode: in -> hex.Spy (->sink) -> out

Want to see what's going through a stream?

var hex = require('hexer');

stream
    .pipe(hex.Spy(process.stdout)) // argument is where to dump to
    .pipe(somewhere);              // normal output flows through

Simple streaming mode: in -> hex.Transform -> out

Got a stream? We can render it:

var hex = require('hexer');
process.stdin
    .pipe(hex.Transform())
    .pipe(process.stdout);

Chunked streaming mode: in -> hex.ChunkedTransform -> out

Got a stream? We can render each of its chunks:

var hex = require('hexer');
process.stdin
    .pipe(hex.ChunkedTransform())
    .pipe(process.stdout);

Advanced chunked streaming mode

Finally you can control the sessionization yourself if that makes sense:

var hex = require('hexer');
var hexer = hex.Transform();
hexer.pipe(process.stdout);

process.stdin.on('data', function onData(chunk) {
    if (decideToReset(chunk)) {
        hexer.reset();
    }
    hexer.write(chunk);
});

However that example is a bit contrived, a more realistic example would be:

var hex = require('hexer');
var hexer = hex.Transform();
hexer.pipe(process.stdout);

process.stdin.on('data', function onData(chunk) {
    var i = findBoundary(chunk);
    while (i > 0) {
        hexer.write(chunk.slice(0, i));
        hexer.reset();
        chunk = chunk.slice(i);
        i = findBoundary(chunk);
    }
    if (chunk.length) {
        hexer.write(chunk);
    }
});

Options

prefix: a string that will be printed at the beginning of every line. (default empty string, "")
cols: the number of bytes to display on each line (default 16)
group: the number of bytes to display adjacently (default 2)
groupSeparator: a string that appears between byte groups (default one space " ")
headSep: a string that appears between the offset column and the byte column (default colon space, ": ")
divide: a string that appears between the byte value column and the character representation column (default two spaces, " ")
gutter: the minimum width of the gutter, the region on the left that contains the byte offset that each line starts with. (default 0)
offsetWidth: the minimum number of digits to display in the byte offset column.
decorateHexen(totalOffset, screenOffset, hexen): A function that has an opportunity to alter the numeric representation of a byte. Decoration is typically used to change the color of the byte based on its position in the stream or position in the line.
decorateHuman(totalOffset, screenOffset, human, byte): A function that has an opportunity to alter the appearance of a given human-readable representation of a byte. Decoration is typically used to change the color of the byte based on its position in the stream, position on the line, its representation, or its value.
renderHexen(byte): a function that accepts a byte value and returns a hexen readable, two character representation of that byte. By default, the hexen representation is lower-case zero-padded hex.
renderHuman(byte): a function that accepts a byte value and returns a human readable, single character representation of that byte. By default, the human representation is the character itself for all printable ASCII characters, and a period "." for control characters and EASCII bytes.
emptyHexen: a two character representation of a non-existant byte at a particular offset for the byte value representation. (default spaces, " ")
emptyHuman: the representation of a non-existant byte in the human readable characters column (default null string, "")
nullHuman: if an entire buffer or stream is empty, the default behavior is to represent it as an empty string or stream. With this option, the empty line will be expressly rendered, with offset zero, empty byte columns, and this string in the human readable characters section.
colored: if set true, enables ANSI coloring of output

ajbogh/hexer