Functions for printing binary data (subset of the od(1) UNIX tool)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
.gitignore
.travis.yml
COPYING
README.org
utilities.binary-dump.asd
version-string.sexp

README.org

utilities.binary-dump README

1 Introduction

The utilities.binary-dump system provides functions for formatting binary data in some of the ways supported by the od(1) UNIX program.

https://travis-ci.org/scymtym/utilities.binary-dump.svg

2 STARTED Tutorial

Naming convention note: number of bits is called “length” (to match cl:integer-length).

(utilities.binary-dump:binary-dump (nibbles:octet-vector 1 15 255 65) :base 16)
01 0F FF 41                                           ...A

Slightly more interesting example:

(let ((buffer (nibbles:make-octet-vector 1024)))
  (with-open-file (stream "/dev/urandom" :element-type '(unsigned-byte 8))
    (read-sequence buffer stream))
  (utilities.binary-dump:binary-dump buffer :base 16 :offset-base 16))
00 F2 34 FB 3D F5 49 5E 6F FB 72 7B 47 7E 56 03 AD B6 .4.=.I^o.r{G~V...
11 AE E0 C3 86 C4 E6 FC 5C 19 0F B7 63 6E C2 E5 1E 87 .......\...cn....
22 55 66 A4 39 E7 E4 11 EF AD 7B D3 6D 47 A5 A6 C7 5A Uf.9.....{.mG...Z
33 83 1C D8 01 FD 3F EE 29 A6 42 BF 74 8D 64 67 C5 4A .....?.).B.t.dg.J
44 F4 7E EB BF 37 3D 44 89 3C A3 D2 BC 09 1A D9 3B E2 .~..7=D.<......;.
55 0C C0 5E FE 2F F6 11 93 24 09 6B 0D 09 02 ..       ..^./...$.k....

3 STARTED Dictionary

3.1 STARTED Access Functions

map-units FUNCTION DATA LENGTH ENDIAN TYPE &KEY (START 0) (END (LENGTH DATA))

Call FUNCTION on subsequent "units" in DATA, return DATA.

Units are subsequences characterized by and interpreted according
to LENGTH, ENDIAN and TYPE:

* LENGTH specifies the number of bits in each unit. Must be 8, 16,
32 or 64 if TYPE is [un]signed-byte and 32 or 64 if TYPE is
`float'.

* ENDIAN specifies the endianess for the interpretation of the
unit. Possible values: the keywords `:little' and `:big'.

* TYPE specifies the type for the interpretation of the
unit. Possible value: the symbols `unsigned-byte', `signed-byte'
and `float'
map-chunks FUNCTION DATA CHUNK-LENGTH &KEY (START 0) (END (LENGTH DATA))
           MAX-CHUNKS

Call FUNCTION with subsequent chunks of CHUNK-LENGTH octets of DATA.

Return four values: 1) DATA 2) the start index of the processed
sub-sequence of DATA (i.e. START) 3) the corresponding end
index (not necessarily END) 4) the number of processed chunks.

FUNCTION has to have a lambda-list compatible to the following one:

(offset data start end last-chunk?)

where

* OFFSET is the offset in octets of the current chunk relative to
the beginning of DATA.

* DATA passed through unmodified.

* START and END are the offset in octets of the beginning and end
of the current chunk relative to the beginning of DATA
respectively.

* LAST-CHUNK? is true when the current chunk is the last in DATA.

The last chunk may be shorter than CHUNK-LENGTH.

When supplied, START and/or END select a subsequence of DATA for
processing.

3.2 STARTED Formatting Functions

binary-dump DATA &KEY (START 0) (END (LENGTH DATA) END-SUPPLIED?) STREAM
            (WIDTH (%STREAM-REMAINING-COLUMNS STREAM)) (LINES *PRINT-LINES*)
            OFFSET-BASE (LENGTH 8) (ENDIAN LITTLE) (TYPE 'UNSIGNED-BYTE)
            (BASE *PRINT-BASE*) PRINT-TYPE

Print DATA to STREAM as a binary, octal, decimal, hexadecimal,
etc. dump of the form

[HEADER]
[OFFSET ]B₁ B₂ B₃ ... S₁S₂S₃ ...
...

where OFFSET - the offset of B₁ printed in base OFFSET-BASE - is
only printed when OFFSET-BASE is an integer designating a base.

B₁, B₂, ... are the bytes (or larger units according to LENGTH) of
DATA printed in base BASE. LENGTH, ENDIAN and TYPE characterize the
length, type and decoding of units:

LENGTH is either 8, 16, 32 or 64 if TYPE is [UN]SIGNED-BYTE and
either 32 or 64 if TYPE is FLOAT.

ENDIAN is either :LITTLE or :BIG and only matters if LENGTH is
not 8.

TYPE is one of [UN]SIGNED-BYTE and FLOAT.

The default behavior is formatting unsigned byte units in base
*PRINT-BASE*.

S₁S₂... is the part of DATA which corresponds to B₁ B₂ ... rendered
as a string. In S₁S₂..., unprintable and whitespace characters are
replaced with ".".

Return four values: 1) DATA 2) the start index of the processed
sub-sequence of DATA (i.e. START) 3) the corresponding end
index (not necessarily END) 4) the number of processed chunks.

If START and/or END are supplied, the subsequence of DATA bounded
by START and END instead of all of DATA is processed.

Additionally, if LINES is non-nil (either the keyword argument is
supplied or its default value, the value of `*print-lines*' is
non-nil), the output is limited to LINES lines. Supplying :lines
nil removes this limitation, even if `*print-lines*' is non-nil.

When PRINT-TYPE is true, the output is preceded by a line of the
form

N-byte TYPE

where TYPE is the type of DATA.

Depending on the length of DATA and WIDTH, the printed
representation can span multiple lines.
print-binary-dump STREAM DATA &OPTIONAL COLON? AT? WIDTH START END
                  (BASE *PRINT-BASE*)

Print DATA to STREAM as a binary, octal, decimal, hexadecimal,
etc. dump of the form

[HEADER]
[OFFSET ]B₁ B₂ B₃ ... S₁S₂S₃ ...
...

COLON? controls whether the offset column is printed (the
corresponding `binary-dump' keyword parameter is `offset-base').

AT? controls whether the header is printed (the corresponding
`binary-dump' keyword parameter is `print-type').

WIDTH specifies the maximum number of columns a line of output
should occupy.

START and END can be used to restrict processing to a subsequence
of DATA.

BASE controls the radix in which numbers in the offset column (if
any) and the numeric data columns are printed.

For more details, see `binary-dump'.

This function is designed for use in ~/ format directives.

4 Settings