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 Wed May 15 07:15:31 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 utilities.binary-dump

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

Maintainer

Jan Moringen <>

Author

Jan Moringen <>

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.


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.


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

4.2 Static


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.


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.


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


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.


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


A.1 Concepts


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