utilities.binary-dump

2016-10-31

Introduction

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

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....

STARTED Dictionary

STARTED Access Functions

#+beginexample 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'

#+endexample

#+beginexample 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.

#+endexample

STARTED Formatting Functions

#+beginexample 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.

#+endexample

#+beginexample 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.

#+endexample

Settings

Author
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
Maintainer
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
License
LLGPLv3