The utilities.binary-dump Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The utilities.binary-dump Reference Manual

This is the utilities.binary-dump Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 07:30:46 2022 GMT+0.

Table of Contents


1 Introduction

#+TITLE:       utilities.binary-dump README
#+AUTHOR:      Jan Moringen
#+EMAIL:       jmoringe@techfak.uni-bielefeld.de
#+DESCRIPTION: Functions for formatting binary data
#+KEYWORDS:    binary, hex, octal, dump, print, utilities, od
#+LANGUAGE:    en

#+OPTIONS: H:2 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+SEQ_TODO: TODO STARTED | DONE

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

  #+ATTR_HTML: :alt "build status image" :title Build Status :align right
  [[https://travis-ci.org/scymtym/utilities.binary-dump][https://travis-ci.org/scymtym/utilities.binary-dump.svg]]

* STARTED Tutorial
  #+begin_src lisp :results none :exports none :session "doc"
    (ql:quickload '(:utilities.binary-dump :alexandria :split-sequence))
  #+end_src

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

  #+begin_src lisp :results output :exports both :session "doc"
    (utilities.binary-dump:binary-dump (nibbles:octet-vector 1 15 255 65) :base 16)
  #+end_src

  #+RESULTS:
  : 01 0F FF 41                                           ...A

  Slightly more interesting example:
  #+begin_src lisp :results output :exports both :session "doc"
    (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))
  #+end_src

  #+RESULTS:
  : 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
  #+begin_src lisp :results none :exports none :session "doc"
    (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)))
  #+end_src

** STARTED Access Functions
   #+begin_src lisp :exports results :session "doc"
     (doc 'utilities.binary-dump:map-units 'function)
   #+end_src

   #+RESULTS:
   #+begin_example
   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'
#+end_example

   #+begin_src lisp :exports results :session "doc"
     (doc 'utilities.binary-dump:map-chunks 'function)
   #+end_src

   #+RESULTS:
   #+begin_example
   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.
#+end_example

** STARTED Formatting Functions
   #+begin_src lisp :exports results :session "doc"
     (doc 'utilities.binary-dump:binary-dump 'function)
   #+end_src

   #+RESULTS:
   #+begin_example
   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.
#+end_example

   #+begin_src lisp :exports results :session "doc"
     (doc 'utilities.binary-dump:print-binary-dump 'function)
   #+end_src

   #+RESULTS:
   #+begin_example
   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.
#+end_example


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 utilities.binary-dump

Formatting of binary data similar to the od(1) UNIX program.

Maintainer

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

Author

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

License

LLGPLv3

Version

0.1.0

Dependencies
  • alexandria (system).
  • let-plus (system).
  • nibbles (system).
Source

utilities.binary-dump.asd.

Child Components

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 utilities.binary-dump/src

Source

utilities.binary-dump.asd.

Parent Component

utilities.binary-dump (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

4.1 Lisp


4.1.1 utilities.binary-dump/utilities.binary-dump.asd

Source

utilities.binary-dump.asd.

Parent Component

utilities.binary-dump (system).

ASDF Systems

utilities.binary-dump.


4.1.2 utilities.binary-dump/src/package.lisp

Source

utilities.binary-dump.asd.

Parent Component

src (module).

Packages

utilities.binary-dump.


4.1.3 utilities.binary-dump/src/util.lisp

Dependency

package.lisp (file).

Source

utilities.binary-dump.asd.

Parent Component

src (module).

Internals

%stream-remaining-columns (function).


4.1.4 utilities.binary-dump/src/access.lisp

Dependency

util.lisp (file).

Source

utilities.binary-dump.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.5 utilities.binary-dump/src/formatting.lisp

Dependency

access.lisp (file).

Source

utilities.binary-dump.asd.

Parent Component

src (module).

Public Interface
Internals

Previous: , Up: Files   [Contents][Index]

4.2 Static


Previous: , Up: Static   [Contents][Index]

4.2.1 utilities.binary-dump/README.org

Source

utilities.binary-dump.asd.

Parent Component

utilities.binary-dump (system).


5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 utilities.binary-dump

This package contains functions for printing binary data.

The formatting possibilities resemble some of the ways supported by the od(1) UNIX program.

The functions ‘binary-dump’ and ‘print-binary-dump’ constitute the API. The former is intended to be called directly while the latter is intended for use in ~/ ‘cl:format’ directives.

Source

package.lisp.

Use List
  • alexandria.
  • common-lisp.
  • let-plus.
  • nibbles.
Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface


6.1.1 Ordinary functions

Function: binary-dump (data &key start end stream width lines offset-base length endian type 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.

Package

utilities.binary-dump.

Source

formatting.lisp.

Function: map-chunks (function data chunk-length &key start end 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.

Package

utilities.binary-dump.

Source

access.lisp.

Function: map-units (function data length endian type &key start end)

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’

Package

utilities.binary-dump.

Source

access.lisp.

Function: print-binary-dump (stream data &optional colon? at? width start end 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.

Package

utilities.binary-dump.

Source

formatting.lisp.


6.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

6.2.1 Special variables

Special Variable: *unit-accessors*
Package

utilities.binary-dump.

Source

access.lisp.

Special Variable: *unit-formatters*
Package

utilities.binary-dump.

Source

formatting.lisp.


Previous: , Up: Internals   [Contents][Index]

6.2.2 Ordinary functions

Function: %binary-dump (data start end stream width lines shortened? offset-base length endian type base print-type)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: %stream-remaining-columns (stream)
Package

utilities.binary-dump.

Source

util.lisp.

Function: ensure-unit-formatter (width endian type base)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: find-unit-accessor (width endian type)
Package

utilities.binary-dump.

Source

access.lisp.

Function: find-unit-accessor/no-cache (width endian type)
Package

utilities.binary-dump.

Source

access.lisp.

Function: find-unit-formatter (width endian type base)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: (setf find-unit-formatter) (width endian type base)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: make-unit-formatter (width endian type base)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: numeric-part-width (width unit-width count)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: print-chunk/numeric (data start end shortened? length endian type base stream width &optional formatter)
Package

utilities.binary-dump.

Source

formatting.lisp.

Function: print-chunk/string (data start end shortened? stream width)
Package

utilities.binary-dump.

Source

formatting.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
B   E   F   M   N   P  
Index Entry  Section

%
%binary-dump: Private ordinary functions
%stream-remaining-columns: Private ordinary functions

(
(setf find-unit-formatter): Private ordinary functions

B
binary-dump: Public ordinary functions

E
ensure-unit-formatter: Private ordinary functions

F
find-unit-accessor: Private ordinary functions
find-unit-accessor/no-cache: Private ordinary functions
find-unit-formatter: Private ordinary functions
Function, %binary-dump: Private ordinary functions
Function, %stream-remaining-columns: Private ordinary functions
Function, (setf find-unit-formatter): Private ordinary functions
Function, binary-dump: Public ordinary functions
Function, ensure-unit-formatter: Private ordinary functions
Function, find-unit-accessor: Private ordinary functions
Function, find-unit-accessor/no-cache: Private ordinary functions
Function, find-unit-formatter: Private ordinary functions
Function, make-unit-formatter: Private ordinary functions
Function, map-chunks: Public ordinary functions
Function, map-units: Public ordinary functions
Function, numeric-part-width: Private ordinary functions
Function, print-binary-dump: Public ordinary functions
Function, print-chunk/numeric: Private ordinary functions
Function, print-chunk/string: Private ordinary functions

M
make-unit-formatter: Private ordinary functions
map-chunks: Public ordinary functions
map-units: Public ordinary functions

N
numeric-part-width: Private ordinary functions

P
print-binary-dump: Public ordinary functions
print-chunk/numeric: Private ordinary functions
print-chunk/string: Private ordinary functions

Jump to:   %   (  
B   E   F   M   N   P