The utilities.binary-dump Reference Manual

Table of Contents

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 2.4 "Will Decker" on Wed Jun 20 12:44:14 2018 GMT+0.


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

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

* 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


* Settings                                                         :noexport:

#+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc


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

2 Systems

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


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

2.1 utilities.binary-dump

Maintainer

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

Author

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

License

LLGPLv3

Description

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

Version

0.1.0

Dependencies
Source

utilities.binary-dump.asd (file)

Components

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

3 Modules

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


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

3.1 utilities.binary-dump/src

Parent

utilities.binary-dump (system)

Location

src/

Components

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

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


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 utilities.binary-dump.asd

Location

utilities.binary-dump.asd

Systems

utilities.binary-dump (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Parent

src (module)

Location

src/package.lisp

Packages

utilities.binary-dump


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

package.lisp (file)

Parent

src (module)

Location

src/util.lisp

Internal Definitions

%stream-remaining-columns (function)


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

util.lisp (file)

Parent

src (module)

Location

src/access.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

access.lisp (file)

Parent

src (module)

Location

src/formatting.lisp

Exported Definitions
Internal Definitions

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

4.2 Other


Previous: , Up: Other files   [Contents][Index]

4.2.1 utilities.binary-dump/README.org

Parent

utilities.binary-dump (system)

Location

README.org


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

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 (file)

Use List
Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 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 (file)

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 (file)

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 (file)

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 (file)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *unit-accessors*
Package

utilities.binary-dump

Source

access.lisp (file)

Special Variable: *unit-formatters*
Package

utilities.binary-dump

Source

formatting.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 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 (file)

Function: %stream-remaining-columns STREAM
Package

utilities.binary-dump

Source

util.lisp (file)

Function: ensure-unit-formatter WIDTH ENDIAN TYPE BASE
Package

utilities.binary-dump

Source

formatting.lisp (file)

Function: find-unit-accessor WIDTH ENDIAN TYPE
Package

utilities.binary-dump

Source

access.lisp (file)

Function: find-unit-accessor/no-cache WIDTH ENDIAN TYPE
Package

utilities.binary-dump

Source

access.lisp (file)

Function: find-unit-formatter WIDTH ENDIAN TYPE BASE
Function: (setf find-unit-formatter) NEW-VALUE WIDTH ENDIAN TYPE BASE
Package

utilities.binary-dump

Source

formatting.lisp (file)

Function: make-unit-formatter WIDTH ENDIAN TYPE BASE
Package

utilities.binary-dump

Source

formatting.lisp (file)

Function: numeric-part-width WIDTH UNIT-WIDTH COUNT
Package

utilities.binary-dump

Source

formatting.lisp (file)

Function: print-chunk/numeric DATA START END SHORTENED? LENGTH ENDIAN TYPE BASE STREAM WIDTH &optional FORMATTER
Package

utilities.binary-dump

Source

formatting.lisp (file)

Function: print-chunk/string DATA START END SHORTENED? STREAM WIDTH
Package

utilities.binary-dump

Source

formatting.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M   O   U  
Index Entry  Section

F
File, Lisp, utilities.binary-dump.asd: The utilities<dot>binary-dump<dot>asd file
File, Lisp, utilities.binary-dump/src/access.lisp: The utilities<dot>binary-dump/src/access<dot>lisp file
File, Lisp, utilities.binary-dump/src/formatting.lisp: The utilities<dot>binary-dump/src/formatting<dot>lisp file
File, Lisp, utilities.binary-dump/src/package.lisp: The utilities<dot>binary-dump/src/package<dot>lisp file
File, Lisp, utilities.binary-dump/src/util.lisp: The utilities<dot>binary-dump/src/util<dot>lisp file
File, other, utilities.binary-dump/README.org: The utilities<dot>binary-dump/readme<dot>org file

L
Lisp File, utilities.binary-dump.asd: The utilities<dot>binary-dump<dot>asd file
Lisp File, utilities.binary-dump/src/access.lisp: The utilities<dot>binary-dump/src/access<dot>lisp file
Lisp File, utilities.binary-dump/src/formatting.lisp: The utilities<dot>binary-dump/src/formatting<dot>lisp file
Lisp File, utilities.binary-dump/src/package.lisp: The utilities<dot>binary-dump/src/package<dot>lisp file
Lisp File, utilities.binary-dump/src/util.lisp: The utilities<dot>binary-dump/src/util<dot>lisp file

M
Module, utilities.binary-dump/src: The utilities<dot>binary-dump/src module

O
Other File, utilities.binary-dump/README.org: The utilities<dot>binary-dump/readme<dot>org file

U
utilities.binary-dump.asd: The utilities<dot>binary-dump<dot>asd file
utilities.binary-dump/README.org: The utilities<dot>binary-dump/readme<dot>org file
utilities.binary-dump/src: The utilities<dot>binary-dump/src module
utilities.binary-dump/src/access.lisp: The utilities<dot>binary-dump/src/access<dot>lisp file
utilities.binary-dump/src/formatting.lisp: The utilities<dot>binary-dump/src/formatting<dot>lisp file
utilities.binary-dump/src/package.lisp: The utilities<dot>binary-dump/src/package<dot>lisp file
utilities.binary-dump/src/util.lisp: The utilities<dot>binary-dump/src/util<dot>lisp file

Jump to:   F   L   M   O   U  

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

A.2 Functions

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

%
%binary-dump: Internal functions
%stream-remaining-columns: Internal functions

(
(setf find-unit-formatter): Internal functions

B
binary-dump: Exported functions

E
ensure-unit-formatter: Internal functions

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

M
make-unit-formatter: Internal functions
map-chunks: Exported functions
map-units: Exported functions

N
numeric-part-width: Internal functions

P
print-binary-dump: Exported functions
print-chunk/numeric: Internal functions
print-chunk/string: Internal functions

Jump to:   %   (  
B   E   F   M   N   P  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*unit-accessors*: Internal special variables
*unit-formatters*: Internal special variables

S
Special Variable, *unit-accessors*: Internal special variables
Special Variable, *unit-formatters*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   P   S   U  
Index Entry  Section

P
Package, utilities.binary-dump: The utilities<dot>binary-dump package

S
System, utilities.binary-dump: The utilities<dot>binary-dump system

U
utilities.binary-dump: The utilities<dot>binary-dump system
utilities.binary-dump: The utilities<dot>binary-dump package

Jump to:   P   S   U