utilities.binary-dump README

1Introduction

The utilities.binary-dump system provides functions for formattingbinary data in some of the ways supported by the od(1) UNIX program.https://travis-ci.org/scymtym/utilities.binary-dump.svg

2STARTED Tutorial

    (ql:quickload '(:utilities.binary-dump :alexandria :split-sequence))

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

3STARTED Dictionary

    (ql:quickload '(:utilities.binary-dump :alexandria :split-sequence))
    (defun doc (symbol kind)
      (let* ((lambda-list (sb-introspect:function-lambda-list symbol))
             (string      (documentation symbol kind))
             (lines       (split-sequence:split-sequence #\Newline string))
             (trimmed     (mapcar (alexandria:curry #'string-left-trim '(#\Space)) lines)))
        (format nil "~(~A~) ~<~{~A~^ ~}~:@>~2%~{~A~^~%~}"
                symbol (list lambda-list) trimmed)))

3.1STARTED Access Functions

     (doc 'utilities.binary-dump:map-units 'function)

   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'

     (doc 'utilities.binary-dump:map-chunks 'function)

   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.2STARTED Formatting Functions

     (doc 'utilities.binary-dump:binary-dump 'function)

   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.

     (doc 'utilities.binary-dump:print-binary-dump 'function)

   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.