The lisp-binary Reference Manual

3.1.1 lisp-binary/lisp-binary.asd

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

ASDF Systems

lisp-binary.

---

3.1.2 lisp-binary/binary-1.lisp

Dependencies

• utils.lisp (file).
• float.lisp (file).
• integer.lisp (file).
• simple-bit-stream.lisp (file).
• reverse-stream.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

lisp-binary.

Public Interface

• *byte-order* (special variable).
• bad-enum-value (condition).
• bad-magic-value (condition).
• buffer (function).
• decode-ip-addr (function).
• define-enum (macro).
• input-string-too-long (condition).
• open-binary (function).
• pointer (special variable).
• pointer (class).
• read-binary (generic function).
• read-binary-type (compiler macro).
• read-binary-type (function).
• read-bytes (method).
• read-counted-string (function).
• read-enum (function).
• read-file (function).
• read-terminated-string (function).
• with-buffered-output (macro).
• with-local-pointer-resolving-context (macro).
• with-open-binary-file (macro).
• write-binary (generic function).
• write-binary-type (compiler macro).
• write-binary-type (function).
• write-bytes (method).
• write-counted-string (function).
• write-enum (function).
• write-terminated-string (function).

Internals

• *always-produce-byte-count* (special variable).
• *base-pointer-tags* (special variable).
• *debug* (special variable).
• *enum-definitions* (special variable).
• *ignore-eval-type-bitstream-issue* (special variable).
• *ignore-on-write* (special variable).
• *known-defbinary-types* (special variable).
• *outer-stream-file-position* (special variable).
• *queued-pointers* (special variable).
• *type-docstrings* (special variable).
• *type-expanders* (special variable).
• *type-info-objects* (special variable).
• *virtual-types* (special variable).
• add-base-pointer-tag (function).
• align-to-boundary (function).
• array-pop (function).
• binary-field (structure).
• binary-field-bit-stream-id (reader).
• (setf binary-field-bit-stream-id) (writer).
• binary-field-defstruct-field (reader).
• (setf binary-field-defstruct-field) (writer).
• binary-field-name (reader).
• (setf binary-field-name) (writer).
• binary-field-p (function).
• binary-field-read-form (reader).
• (setf binary-field-read-form) (writer).
• binary-field-type (reader).
• (setf binary-field-type) (writer).
• binary-field-write-form (reader).
• (setf binary-field-write-form) (writer).
• build-virtual-type-reader/writer-expander (function).
• clear-tag (function).
• copy-binary-field (function).
• copy-enum-definition (function).
• copy-out-pointer (function).
• copy-virtual-type (function).
• debug-data (special variable).
• defbinary-type (special variable).
• defbinary-type (class).
• defbinary-type-align (reader method).
• (setf defbinary-type-align) (writer method).
• defbinary-type-bind-index-to (reader method).
• (setf defbinary-type-bind-index-to) (writer method).
• defbinary-type-byte-count-name (reader method).
• (setf defbinary-type-byte-count-name) (writer method).
• defbinary-type-byte-order (reader method).
• (setf defbinary-type-byte-order) (writer method).
• defbinary-type-element-align (reader method).
• (setf defbinary-type-element-align) (writer method).
• defbinary-type-name (reader method).
• (setf defbinary-type-name) (writer method).
• defbinary-type-previous-defs-symbol (reader method).
• (setf defbinary-type-previous-defs-symbol) (writer method).
• defbinary-type-reader (reader method).
• (setf defbinary-type-reader) (writer method).
• defbinary-type-stream-symbol (reader method).
• (setf defbinary-type-stream-symbol) (writer method).
• defbinary-type-type (reader method).
• (setf defbinary-type-type) (writer method).
• defbinary-type-writer (reader method).
• (setf defbinary-type-writer) (writer method).
• define-lisp-binary-type (macro).
• define-virtual-type (macro).
• dump-tag (function).
• enum-definition (structure).
• enum-definition-byte-order (reader).
• (setf enum-definition-byte-order) (writer).
• enum-definition-name (reader).
• (setf enum-definition-name) (writer).
• enum-definition-p (function).
• enum-definition-reader (reader).
• (setf enum-definition-reader) (writer).
• enum-definition-signed (reader).
• (setf enum-definition-signed) (writer).
• enum-definition-signed-representation (reader).
• (setf enum-definition-signed-representation) (writer).
• enum-definition-size (reader).
• (setf enum-definition-size) (writer).
• enum-definition-variables (reader).
• (setf enum-definition-variables) (writer).
• enum-definition-writer (reader).
• (setf enum-definition-writer) (writer).
• enump (function).
• expand-previous-defs (function).
• expand-read/write-binary-type-body (function).
• expand-read/write-binary-type-static (function).
• get-base-pointer-tag (function).
• get-enum-definition (function).
• get-enum-name (function).
• get-enum-value (function).
• get-tag (function).
• get-type-fields (function).
• interpret-documentation-form (function).
• load-offset (function).
• make-binary-field (function).
• make-enum-definition (function).
• make-fixed-length-string (function).
• make-out-pointer (function).
• make-simple-array (function).
• make-truncated-fixed-length-string (function).
• make-virtual-type (function).
• out-pointer (structure).
• out-pointer-data-writer (reader).
• (setf out-pointer-data-writer) (writer).
• out-pointer-p (function).
• out-pointer-pointer-writer (reader).
• (setf out-pointer-pointer-writer) (writer).
• pointer-base-pointer (reader method).
• (setf pointer-base-pointer) (writer method).
• pointer-offset (reader method).
• (setf pointer-offset) (writer method).
• pointer-stream (reader method).
• (setf pointer-stream) (writer method).
• pointer-type (reader method).
• (setf pointer-type) (writer method).
• push-to-tag (function).
• queue-write-pointer (function).
• read-octets-to-string (macro).
• read/write-binary-type (macro).
• remove-all-restart-case (function).
• remove-double-multiple-value-bind (function).
• remove-impossible-error-checks (function).
• right-pad (function).
• runtime-reader/writer-form (function).
• simple-array-p (function).
• type-size (function).
• unknown-type-size (condition).
• unspecified-type-error (condition).
• virtual-type (structure).
• virtual-type-can-be-in-bit-field (reader).
• (setf virtual-type-can-be-in-bit-field) (writer).
• virtual-type-estimated-total-bits (reader).
• (setf virtual-type-estimated-total-bits) (writer).
• virtual-type-lambda-list (reader).
• (setf virtual-type-lambda-list) (writer).
• virtual-type-lisp-type (reader).
• (setf virtual-type-lisp-type) (writer).
• virtual-type-name (reader).
• (setf virtual-type-name) (writer).
• virtual-type-p (function).
• virtual-type-reader (reader).
• (setf virtual-type-reader) (writer).
• virtual-type-stream-required (reader).
• (setf virtual-type-stream-required) (writer).
• virtual-type-writer (reader).
• (setf virtual-type-writer) (writer).

---

3.1.3 lisp-binary/binary-2.lisp

Dependencies

• utils.lisp (file).
• float.lisp (file).
• integer.lisp (file).
• simple-bit-stream.lisp (file).
• reverse-stream.lisp (file).
• binary-1.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Public Interface

defbinary (macro).

Internals

• %make-reader-let-def (function).
• *last-f* (special variable).
• add-bit-stream-id (function).
• add-bit-stream-vars (function).
• add-stream-definitions (function).
• bit-field-type-p (function).
• bitfield-spec->defstruct-specs (function).
• combine-field-descriptions (function).
• convert-to-bit-fields (function).
• defbinary-constructor-name (function).
• expand-byte-shorthand (function).
• expand-defbinary-field (function).
• expand-defbinary-type-field (function).
• externally-byte-aligned-p (function).
• field-description-plist (function).
• field-description-type (function).
• field-option (function).
• find-bit-field-groups (function).
• group-write-forms (function).
• list-of-fields-p (function).
• make-bit-field (function).
• make-reader-let-def (macro).
• recursive-field-list (function).
• reverse-bit-stream-groups (function).
• var-bit-stream (function).

---

3.1.4 lisp-binary/types.lisp

Dependencies

• utils.lisp (file).
• binary-1.lisp (file).
• binary-2.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

---

3.1.5 lisp-binary/simple-bit-stream.lisp

Dependencies

• integer.lisp (file).
• utils.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

simple-bit-stream.

Public Interface

• bit-stream (class).
• byte-aligned-p (function).
• call-with-file-position (method).
• close (method).
• read-bits (function).
• read-bytes-with-partial (function).
• stream-element-type (method).
• (setf stream-file-position) (method).
• stream-file-position (method).
• stream-finish-output (method).
• stream-force-output (method).
• stream-read-byte (method).
• stream-read-sequence (method).
• stream-write-byte (method).
• stream-write-sequence (method).
• with-wrapped-in-bit-stream (macro).
• wrap-in-bit-stream (generic function).
• write-bits (function).

Internals

• %stream-read-sequence (function).
• %stream-write-sequence (function).
• init-read (function).
• init-write (function).
• read-bits/big-endian (function).
• read-bits/little-endian (function).
• read-bytes-with-partial/macro (macro).
• read-partial-byte/big-endian (function).
• read-partial-byte/little-endian (function).
• reset-op (function).
• trace-read-byte (function).
• trace-write-byte (function).

---

3.1.6 lisp-binary/reverse-stream.lisp

Dependency

integer.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

reverse-stream.

Public Interface

• close (method).
• reverse-stream (class).
• (setf stream-file-position) (method).
• stream-file-position (method).
• stream-finish-output (method).
• stream-force-output (method).
• stream-read-byte (method).
• stream-read-sequence (method).
• stream-write-byte (method).
• stream-write-sequence (method).
• with-wrapped-in-reverse-stream (macro).
• wrap-in-reverse-stream (generic function).

Internals

• %stream-read-sequence (function).
• %stream-write-sequence (function).
• *8-bit-lookup-table* (special variable).
• compute-reversed-byte (function).
• make-lookup-table (function).
• reverse-byte (function).

---

3.1.7 lisp-binary/integer.lisp

Dependency

utils.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

lisp-binary/integer.

Public Interface

• decode-lsb (function).
• decode-msb (function).
• encode-lsb (function).
• encode-msb (function).
• get-lsb-byte (function).
• join-field-bits (function).
• pop-bits (macro).
• pop-bits/le (macro).
• push-bits (macro).
• push-bits/le (macro).
• read-bytes (generic function).
• read-integer (function).
• signed->unsigned (function).
• signed->unsigned/bits (function).
• split-bit-field (function).
• unsigned->signed (function).
• unsigned->signed/bits (function).
• write-bytes (generic function).
• write-integer (function).

Internals

• ash* (function).
• logior* (function).
• ones-complement->twos-complement (function).
• tif (macro).
• tlabels (macro).
• twos-complement->ones-complement (function).

---

3.1.8 lisp-binary/float.lisp

Dependency

integer.lisp (file).

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

lisp-binary/float.

Public Interface

• +inf (special variable).
• -inf (special variable).
• decode-float-bits (macro).
• encode-float-bits (macro).
• infinityp (function).
• nanp (function).
• quiet-nan (special variable).
• read-float (macro).
• signalling-nan (special variable).
• write-float (macro).

Internals

• %infinityp (function).
• %make-infinity (function).
• %make-quiet-nan (function).
• %make-signalling-nan (function).
• %qnanp (function).
• %read-float (function).
• %snanp (function).
• %write-float (function).
• *denormals* (special variable).
• *format-table* (special variable).
• calculate-exponent (function).
• calculate-significand (function).
• decode-float-bits/arithmetic (function).
• decode-float-bits/arithmetic-macro (macro).
• decode-float-bits/cffi (function).
• decode-significand (function).
• denormalp (function).
• denormalp/arithmetic (function).
• encode-float-bits/arithmetic (function).
• encode-float-bits/arithmetic-macro (macro).
• encode-float-bits/cffi (function).
• encode-float-bits/runtime-format (function).
• encode-significand (function).
• exponent-all-ones-p (function).
• exponent-zero-p (function).
• float-coerce (function).
• float-value (function).
• format-size (function).
• get-exponent (function).
• get-format (function).
• get-significand (function).
• make-infinity (function).
• make-largest-denormal (function).
• make-quiet-nan (function).
• make-signalling-nan (function).
• make-smallest-denormal (function).
• popbit (macro).

---

3.1.9 lisp-binary/utils.lisp

Source

lisp-binary.asd.

Parent Component

lisp-binary (system).

Packages

lisp-binary-utils.

Public Interface

• aif (macro).
• assoc-cdr (function).
• awhen (macro).
• bind-class-slots (macro).
• call-with-file-position (generic function).
• destructuring-case (macro).
• destructuring-lambda (macro).
• divisiblep (function).
• find-sublist (function).
• group (function).
• insert-before (function).
• let-values (macro).
• let-values* (macro).
• letf (macro).
• mapseq (function).
• named-let (macro).
• no-destructuring-match (condition).
• plist-replace (function).
• pushover (macro).
• recursive-find (function).
• recursive-find-if (function).
• recursive-find-sublist (function).
• recursive-find/collect (function).
• recursive-map (function).
• recursive-mapcar (function).
• relative-file-position (function).
• remove-binding (function).
• remove-plist-keys (function).
• simple-define-condition (macro).
• struct-like-defclass (macro).
• subst* (function).
• with-file-position (macro).

Internals

• acond (macro).
• add-default-value-if-needed (function).
• expand-struct-like-defclass-slot (function).
• let-values/stupid* (macro).
• list-begins-with-p (function).
• optimize-let-values (function).
• take-while (function).
• with-letf-bindings (macro).

---

5.1.1 Special variables

Special Variable: *byte-order* ¶

Dynamically controls the byte-order in which Lisp-Binary’s primitives read multi-byte values. Allowed values are :LITTLE-ENDIAN and :BIG-ENDIAN.

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: +inf ¶

Package

lisp-binary/float.

Source

float.lisp.

Special Variable: -inf ¶

Package

lisp-binary/float.

Source

float.lisp.

Special Variable: pointer ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: quiet-nan ¶

Package

lisp-binary/float.

Source

float.lisp.

Special Variable: signalling-nan ¶

Package

lisp-binary/float.

Source

float.lisp.

---

5.1.2 Macros

Macro: aif (test then &optional else) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: awhen (test &rest body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: bind-class-slots (class instance &body body) ¶

Evaluates BODY with the slots from the CLASS bound to the values taken from INSTANCE. The CLASS must be a class object at compile-time, so the macro can extract the needed variable names for binding.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: decode-float-bits (integer &key format result-type) ¶

Decodes the bits from an IEEE floating point number. Supported formats are listed in the variable LISP-BINARY/FLOAT::*FORMAT-TABLE*.

If the FORMAT is either :SINGLE or :DOUBLE, then the decoding is
done by storing the bits in memory and having the CPU reinterpret that buffer as a float. Otherwise, arithmetic methods are used to arrive at the correct value.

To prevent precision loss if you are decoding a larger type such as :QUADRUPLE or :OCTUPLE precision, use ’RATIONAL for the RESULT-TYPE to avoid a conversion to a smaller 32- or 64-bit float.

Package

lisp-binary/float.

Source

float.lisp.

Macro: defbinary (name (&rest defstruct-options &key byte-order preserve-*byte-order* align untyped-struct include documentation export byte-count-name &allow-other-keys) &body field-descriptions) ¶

Defines a struct that represents binary data. Also generates two methods for this struct, named
READ-BINARY and WRITE-BINARY, which (de)serialize the struct to or from a stream. The serialization is
a direct binary representation of the fields of the struct. For instance, if there’s a field with a :TYPE of
(UNSIGNED-BYTE 32), 4 bytes will be written in the specified :BYTE-ORDER. The fields are written (or read) in
the order in which they are specified in the body of the DEFBINARY form.

ARGUMENTS

NAME - Used as the name in the generated DEFSTRUCT form.

:BYTE-ORDER - The byte-order to use when reading or writing multi-byte
data. Accepted values are :BIG-ENDIAN, :LITTLE-ENDIAN,
and :DYNAMIC. If :DYNAMIC is specified, then the
READ- and WRITE-BINARY methods will consult the special
variable LISP-BINARY:*BYTE-ORDER* at runtime to decide
which byte order to use. That variable is expected to
be either :LITTLE-ENDIAN or :BIG-ENDIAN.

:PRESERVE-*BYTE-ORDER* - Don’t revert changes that get made to
LISP-BINARY:*BYTE-ORDER* during the call
to either READ- or WRITE-BINARY.

:ALIGN - Align to the specified byte boundary before reading or writing
the struct.

:EXPORT - Export all symbols associated with the generated struct,
including the name of the struct, the name of the constructor,
and all the slot names.

:BYTE-COUNT-NAME - In all value and type forms, bind to this name
the number of bytes in the struct written so far.

&ALLOW-OTHER-KEYS - All other keyword arguments will be passed through
to the generated CL:DEFSTRUCT form as part of the
NAME-AND-OPTIONS argument.

FIELD-DESCRIPTIONS - A list of slot specifications, having the following structure:

(FIELD-NAME DEFAULT-VALUE &KEY TYPE BYTE-ORDER ALIGN ELEMENT-ALIGN
READER WRITER BIND-INDEX-TO)

The parameters have the following meanings:

FIELD-NAME - The name of the slot.

DEFAULT-VALUE - The default value.

TYPE - The type of the field. Some Common Lisp types such as
(UNSIGNED-BYTE 32) are supported. Any type defined
with DEFBINARY is also supported. For more info, see
’TYPES’ below.

BYTE-ORDER - The byte order to use when reading or writing this
field. Defaults to the BYTE-ORDER given for the whole
struct.

ALIGN - If specified, reads and writes will be aligned on this
boundary. When reading, bytes will be thrown away until
alignment is achieved. When writing, NUL bytes will be
written.

UNTYPED-STRUCT - Don’t declare the :TYPEs of the fields in the generated
DEFSTRUCT form.

ELEMENT-ALIGN - If the TYPE is an array, each element of the array will
be aligned to this boundary.

READER - If speficied, this function will be used to read the field.
It must accept one argument (a stream), and return two
values - The object read, and the the number of bytes read.
The number of bytes read is used for alignment purposes.

WRITER - If specified, this function will be used to write the field.
It must accept two arguments (the object to write, and the
stream), and return the number of bytes written, which is
used for alignment purposes.

BIND-INDEX-TO - If the EVAL type specifier is used as an array’s element type
(see below), BIND-INDEX-TO will be bound to the current index
into the array, in case that matters for determining the type
of the next element.

Example:

(defbinary simple-binary (:export t
:byte-order :little-endian)
(magic 38284 :type (magic :actual-type (unsigned-byte 16)
:value 38284))
(size 0 :type (unsigned-byte 32))
(oddball-value 0 :type (unsigned-byte 32)
:byte-order :big-endian)
((b g r) 0 :type (bit-field :raw-type (unsigned-byte 8)
:member-types
((unsigned-byte 2)
(unsigned-byte 3)
(unsigned-byte 3))))
(name "" :type (counted-string 1 :external-format :utf8))
(alias #() :type (counted-buffer 4)
:byte-order :big-endian)
(floating-point 0.0d0 :type double-float)
(big-float 0 :type octuple-float)
(odd-float 0 :type (double-float :byte-order :big-endian))
(c-string "" :type (terminated-buffer 1 :terminator 0))
(nothing nil :type null) ;; Reads and writes nothing.
(other-struct nil :type other-binary
:reader #’read-other-binary
:writer #’write-other-binary)
(struct-array #() :type (counted-array 1 simple-binary))
(blah-type 0 :type (unsigned-byte 32))
(blah nil :type (eval (case oddball-value
((1) ’(unsigned-byte 32))
((2) ’(counted-string 2)))))
(an-array #() :type (simple-array (unsigned-byte 32) ((length c-string))))
(body #() :type (simple-array (unsigned-byte 8) (size))))

The above generates a DEFSTRUCT definition for SIMPLE-BINARY, along with
a definition for a READ-BINARY method and a WRITE-BINARY method.
‘
The READ-BINARY method is EQL-specialized, and will construct the needed
object for you. It can be invoked like this:

(read-binary ’simple-binary stream)

The WRITE-BINARY method is called like this:

(write-binary object stream)

TYPES

DEFBINARY supports two kinds of types: Ordinary Common Lisp types, and Virtual Types.

The list of type names known to the library are listed below. Each one has its own
docstring, which can be accessed in several ways:

1. Emacs/SLIME’s built-in docstring integraton: C-d d
2. (CL:DOCUMENTATION symbol ’LISP-BINARY:LISP-BINARY-TYPE)
3. (DESCRIBE symbol)

UNSIGNED-BYTE
SIGNED-BYTE
SIMPLE-ARRAY
COUNTED-ARRAY
COUNTED-STRING
COUNTED-BUFFER
TERMINATED-STRING
TERMINATED-BUFFER
FIXED-LENGTH-STRING
MAGIC
BASE-POINTER
FILE-POSITION
(REGION-TAG &key base-pointer-name)
(POINTER &key pointer-type data-type base-pointer-name region-tag)
(BIT-FIELD &key raw-type member-types)
(CUSTOM &key reader writer (lisp-type t))
NULL
EVAL - For runtime type selection

NON-BYTE-ALIGNED I/O: AN ALTERNATIVE TO BIT FIELDS

DEFBINARY supports non-byte-aligned reads. For example, if you want to read a 4-bit
unsigned integer and a 12-bit signed integer:

(defbinary non-conforming (:byte-order :big-endian)
(x 0 :type 4)
(y 0 :type 12)) ;; Total: 16 bits.

The above will compile to a single 16-bit read, and the two values will be automatically
extracted into their respective fields. The reverse operation is generated for writing.

In fact, the above is converted into a BIT-FIELD declaration, so it is exactly equivalent
to the following:

(defbinary non-conforming-bit-field-version (:byte-order :big-endian)
((x y) 0 :type (bit-field :raw-type (unsigned-byte 16)
:member-types ((unsigned-byte 4)
(unsigned-byte 12)))))

The macro will group sets signed or unsigned bytes to achieve a read that consists of
whole bytes. This grouping mechanism only works for SIGNED-BYTE and UNSIGNED-BYTE integers.

For other types, DEFBINARY will generate a temporary BIT-STREAM for the non-byte-aligned parts:

(defbinary non-byte-aligned-string (:byte-order :big-endian)
(x 0 :type 4)
(string "" :type (counted-string 1))
(y 0 :type 4))
;; End of non-byte-aligned part
(z "" :type (counted-string 1)))

As long as the sum of the bits adds up to a whole number of bytes, no
special handling is required on the part of the programmer. Internally,
the above generates a temporary bit-stream and reads from it, and it discards
the bit-stream before reading Z, because Z doesn’t require non-byte-aligned I/O.
This is slower than doing whole-byte reads.

Finally, you can specify bytes that throw off the byte-alignment of the
stream:

(defbinary stays-non-byte-aligned ()
(x 0 :type 3))

If the macro cannot group the fields in the struct into byte-aligned reads,
then the struct can only be read from a BIT-STREAM and not a normal
stream (see WRAP-IN-BIT-STREAM and WITH-WRAPPED-IN-BIT-STREAM). In this
case, the macro will generate READ-BINARY and WRITE-BINARY methods that
are specialized to a second argument of type BIT-STREAM.

BIT-STREAMs can wrap any type of stream, including other BIT-STREAMs. This
means that you can nest one struct that does BIT-STREAM I/O inside another:

(defbinary stays-non-byte-aligned ()
(x 0 :type 3)
(y nil :type non-byte-aligned-string)) ;; See above

NON-BYTE-ALIGNED FIELDS and LITTLE ENDIANNESS

Bit fields are inherently confusing when they are applied to little-endian data (unlike
big-endian data, where they make perfect sense). This is because programmers who write
specifications for little-endian formats sometimes still describe the bit fields by
starting with the most significant bit.

Also, code that handles bit fields from little endian data may also handle that data
starting with the most significant bit (including some byte-order-independent code in
this library).

The BIT-FIELD type in DEFBINARY adds to this confusion, since the fields must always
be given starting with the most significant bit, regardless of the format’s byte order.

However, when specifying non-byte-aligned fields without using BIT-FIELDs, they must be
specified starting with the LEAST significant bit in a LITTLE-ENDIAN format, but they
must be specified starting with the MOST significant bit in a BIG-ENDIAN format. For
example, consider the following toy format:

(defbinary toy-format (:byte-order :little-endian)
(a 0 :type 4)
(b 0 :type 16)
(c 0 :type 4))

Write it to disk with the following code:

(with-open-binary-file (out #P"/tmp/test-1.bin" :direction :output
:if-exists :supersede
:if-does-not-exist :create)
(write-binary (make-toy-format :a #x1 :b #x2345 :c #x6) out))

The resulting file would produce the following confusing hex dump:

51 34 62

What is that 5 from the middle doing at the very beginning?!?! Since 0x5 is
the second-least-significant nibble in the structure, it appears in the
most significant nibble of the least significant byte.

Reading the above as a little-endian, 24-bit unsigned integer gives the
integer #x623451, which is what you should have been expecting, since
C is the most significant field, and its value is 6.

You can also specify the above format using the BIT-FIELD type. But then you
have to account for the fact that in a BIT-FIELD type description, you always
describe the most significant bits first, no matter what. So the variables
and their corresponding types have to be reversed:

(defbinary toy-format/bit-field (:byte-order :little-endian)
((c b a) nil :type (bit-field :raw-type (unsigned-byte 24)
:member-types ((unsigned-byte 4)
(unsigned-byte 16)
(unsigned-byte 4)))))

ALIGNMENT

DEFBINARY can generate aligned structures. Alignment is calculated as an offset from the beginning of the structure
being defined. If a SIMPLE-ARRAY is defined with :ALIGN-ELEMENT {boundary}, then each element will be aligned to that
boundary. On writes, the alignment is achieved by writing NUL (0) bytes. On reads, the alignment is performed by
reading bytes from the stream one at a time. Alignment is always performed before reading and writing, never after.

MANUAL ALIGNMENT

If the &KEY argument :BYTE-COUNT-NAME is specified, then the name given will be bound as a variable whose value is the number of bytes read or written so far. This binding is visible in forms that are evaluated at runtime, such as array-length specifiers and EVAL type specifiers.

FLOATING-POINT NUMBERS

DEFBINARY can read IEEE floats ranging from half-precision up to octuple precision. Double-precision and below are
represented in memory by hardware floats, while larger-precision floats are decoded into RATIONALs.

Furthermore, single and double-precision floats are decoded from their byte representation by using CFFI, which
lets the hardware do the work on those systems that have FPUs (such as x86/AMD machines).

All other types of floating-point number are encoded and decoded using arithmetic.

Package

lisp-binary.

Source

binary-2.lisp.

Macro: define-enum (name size/bytes (&key signed signed-representation byte-order reader writer) &body values) ¶

Define an enum type. What this does is allow LISP-BINARY to automatically map between keywords and integer values that are expected to be found in a binary file. The SIZE is in bytes.

Example:

(define-enum speeds 2 ()
slow ;; Implicitly 0
light-speed ;; Implicitly 1
(ridiculous-speed 5) ;; Explicit value
ludicrous-speed) ;; Implicitly 6

The READER and WRITER functions must accept the same lambda-lists
as READ-INTEGER and WRITE-INTEGER, and have the same return
values (ie, the READER returns (VALUES object bytes-read) and the
WRITER returns bytes-written).

Package

lisp-binary.

Source

binary-1.lisp.

Macro: destructuring-case (expression &rest cases) ¶

Matches the EXPRESSION against one of the CASES. Each CASE is of
the form (lambda-list &key where &body body) and can have a guard clause.

The first pattern that successfully DESTRUCTURING-BINDs against the EXPRESSION without an error *and* satisfies the optional :WHERE expression is the one that will be selected. OTHERWISE is supported and works just as in the CL:CASE form.

Example:

(destructuring-case ’(1 2 3)
((a b c) :where (symbolp a)
(declare (ignore b c))
(list :symbol a))
((a b &optional c) :where (number b)
(declare (ignore a c)))
(list :number b))
((a &rest b)
(declare (ignore b))
(list :whatever a))
(otherwise
:nothing-matched))

The DECLARE form is processed before the :WHERE clause even though it appears after it.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: destructuring-lambda (lambda-list &body body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: encode-float-bits (fraction &key format) ¶

Package

lisp-binary/float.

Source

float.lisp.

Macro: let-values (bindings &body body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: let-values* (bindings &body body) ¶

Optimized implementation of LET-VALUES*. You can bind a multiple-value expression to
a list of variables, or you can bind a single value. Generates as few nested MULTIPLE-VALUE-BIND and LET* forms as possible.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: letf (place-bindings &body body) ¶

Temporarily rebind places like you would special variables. Before control enters the BODY, the PLACE-BINDINGS are altered using SETF, and after exiting the BODY, their values are restored to their original values with SETF.

Similar to CL-LETF in Emacs.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: named-let (name defs &body body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: pop-bits (n-bits integer-size integer-place) ¶

Pops the N most significant bits off the front of the INTEGER-PLACE and returns it. INTEGER-SIZE is the number of unpopped bits in the integer.

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: pop-bits/le (n-bits integer-place) ¶

Pops the N LEAST significant bits off the front of the INTEGER-PLACE and returns it. INTEGER-SIZE is the number of bits in the integer.

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: push-bits (n integer-size integer-place) ¶

Pushes N onto the front of INTEGER-PLACE,
the ’front’ being defined as the MOST significant bits. The INTEGER-SIZE specifies how many bits are already in the INTEGER-PLACE.

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: push-bits/le (n n-bits integer-place) ¶

Pushes N-BITS bits from N onto the front of INTEGER-PLACE, the ’front’ being defined as the LEAST significant bits. The INTEGER-SIZE specifies how many bits are already in the INTEGER-PLACE.

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: pushover (obj* place &key key test) ¶

Pushes the OBJ* into the PLACE. If an "identical" object is already there, it is overwritten. Whether something in the PLACE is considered "identical" can be controlled with the :TEST and :KEY keywords.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: read-float (format &key stream result-type byte-order) ¶

Package

lisp-binary/float.

Source

float.lisp.

Macro: simple-define-condition (name parent-classes slots &optional docstring) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: struct-like-defclass (name superclasses &rest slot-defs) ¶

An extremely simplified version of DEFCLASS. Written because I needed to be able to list the slots of a certain struct.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: with-buffered-output ((var stream) &body body) ¶

Creates buffered output stream VAR. Data written to VAR will be written to STREAM after the BODY returns. This makes it possible to write binaries that require streams opened in :DIRECTION :IO to streams that are open in :DIRECTION :OUT

Package

lisp-binary.

Source

binary-1.lisp.

Macro: with-file-position ((position stream) &body body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: with-local-pointer-resolving-context (&body body) ¶

Deal with POINTERs in a thread-safe manner. Generated READ-BINARY and WRITE-BINARY methods rely on special variables to store information to make sure that offsets are calculated correctly. This macro creates local bindings of all the relevant special variables.

Package

lisp-binary.

Source

binary-1.lisp.

Macro: with-open-binary-file ((stream filespec &rest options &key direction if-exists if-does-not-exist) &body body) ¶

Like WITH-OPEN-FILE, but always opens the file as a binary file.

Package

lisp-binary.

Source

binary-1.lisp.

Macro: with-wrapped-in-bit-stream ((var non-bitstream &key byte-order close-when-done) &body body) ¶

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Macro: with-wrapped-in-reverse-stream ((var non-bitstream &key close-when-done) &body body) ¶

Package

reverse-stream.

Source

reverse-stream.lisp.

Macro: write-float (format fraction &key stream byte-order) ¶

Package

lisp-binary/float.

Source

float.lisp.

---

5.1.3 Compiler macros

Compiler Macro: read-binary-type (type stream &key byte-order align element-align) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Compiler Macro: write-binary-type (value type stream &key byte-order align element-align) ¶

Package

lisp-binary.

Source

binary-1.lisp.

---

5.1.4 Ordinary functions

Function: assoc-cdr (item assoc-list &key test) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: buffer (&rest elements) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Function: byte-aligned-p (bit-stream) ¶

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Function: decode-ip-addr (raw-msb) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Function: decode-lsb (bytes) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: decode-msb (bytes) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: divisiblep (num denom) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: encode-lsb (number bytes) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: encode-msb (number bytes) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: find-sublist (sublist list) ¶

Finds any part of LIST is equal to SUBLIST and returns it, otherwise returns NIL

Package

lisp-binary-utils.

Source

utils.lisp.

Function: get-lsb-byte (number byte) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: group (list &key test key) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: infinityp (decoded-value) ¶

Returns two values:
T if the DECODED-VALUE represents a floating-point infinity
T if the DECODED-VALUE represents positive infinity, or NIL if it’s negative infinity.

Some Lisp implementations support real floating-point infinities, but the ANSI standard does
not require it, and some Lisp implementations don’t bother to support them. On those implementations, infinities are represented by the keywords :+INF and :-INF. To detect positive/negative infinity portably, use this function.

Package

lisp-binary/float.

Source

float.lisp.

Function: insert-before (before-item new-item list &key test key) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: join-field-bits (field-bits field-signedness field-values) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: mapseq (function sequence) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: nanp (decoded-value) ¶

Package

lisp-binary/float.

Source

float.lisp.

Function: open-binary (pathname &key direction if-exists if-does-not-exist) ¶

Like OPEN, but always opens a binary stream suitable for use with the DEFBINARY library.

Package

lisp-binary.

Source

binary-1.lisp.

Function: plist-replace (plist indicator new-value) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: read-binary-type (type stream &key byte-order align element-align) ¶

Read a value of type TYPE from the STREAM. TYPE is any type supported by the DEFBINARY macro.

Package

lisp-binary.

Source

binary-1.lisp.

Function: read-bits (bits stream) ¶

Reads BITS bits from STREAM. If the STREAM is big-endian, the most significant BITS bits will be read, otherwise, the least significant BITS bits will be. The result is an integer of BITS bits.

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Function: read-bytes-with-partial (stream bits) ¶

Reads BITS bits from the STREAM, where BITS is expected to be more than a byte’s worth
of bits. Returns three values:

1. A buffer containing as many whole bytes as possible. This buffer
is always read first, regardless of whether the bitstream is byte-aligned.
2. The partial byte.
3. The number of bits that were read for the partial byte.

The byte order is determined from the STREAM object, which must be a SIMPLE-BIT-STREAM:BIT-STREAM.

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Function: read-counted-string (size-len stream &key byte-order) ¶

Reads an unsigned integer of SIZE-LEN bytes in the specified BYTE-ORDER, then reads a byte vector of SIZE-LEN bytes. Returns two values:

1. The byte vector
2. The total number of bytes that were read.

Package

lisp-binary.

Source

binary-1.lisp.

Function: read-enum (enum stream) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Function: read-file (filename &key element-type) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Function: read-integer (length stream &key byte-order signed signed-representation) ¶

Reads an integer of LENGTH bytes from the STREAM in the specified BYTE-ORDER.

If SIGNED is non-NIL, the number is interpreted as being in two’s complement format.

If the STREAM is a BIT-STREAM, then the LENGTH doesn’t have to be an integer.

Package

lisp-binary/integer.

Source

integer.lisp.

Function: read-terminated-string (stream &key terminator) ¶

Reads a string ending in the byte sequence specified by TERMINATOR. The TERMINATOR is not included in the resulting buffer. The default is to read C-style strings, terminated by a zero.

Package

lisp-binary.

Source

binary-1.lisp.

Function: recursive-find (item tree &key test) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: recursive-find-if (pred tree) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: recursive-find-sublist (sublist tree) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: recursive-find/collect (pred tree) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: recursive-map (function tree) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: recursive-mapcar (function tree &optional traverse-results result) ¶

Maps the FUNCTION onto every node in the TREE. Works correctly with improper lists.

If TRAVERSE-RESULTS is non-NIL, then RECURSIVE-MAPCAR will traverse the result of the FUNCTION even if it is not EQ to the original value.

Package

lisp-binary-utils.

Source

utils.lisp.

Function: relative-file-position (stream offset) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: remove-binding (var form) ¶

Removes any binding for VAR from all LET, LET*, LET-VALUES, or LET-VALUES* forms found in the FORM.

Package

lisp-binary-utils.

Source

utils.lisp.

Function: remove-plist-keys (plist &rest keys) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: signed->unsigned (n bytes &optional type) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: signed->unsigned/bits (n bits) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: split-bit-field (integer field-bits &optional field-signedness) ¶

Given the INTEGER, split it up as a bit field. The sizes and number of elements are given by the FIELD-BITS parameter. If FIELD-SIGNEDNESS is specified, then it must be a list that contains NIL for each element that will be interpreted as an unsigned integer, and non-NIL for signed integers.

Example:

CL-USER> (split-bit-field #xffaaff ’(8 8 8))
255
170
255
CL-USER>

Better performance could be acheived if INTEGER could be a FIXNUM, but it can’t.

Package

lisp-binary/integer.

Source

integer.lisp.

Function: subst* (bindings form &key test) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Function: unsigned->signed (n bytes &key type) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: unsigned->signed/bits (n bits) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: write-binary-type (value type stream &key byte-order align element-align) ¶

Write the VALUE, interpreting it as type TYPE, to the STREAM. The TYPE is any type supported by the DEFBINARY macro.

Package

lisp-binary.

Source

binary-1.lisp.

Function: write-bits (n n-bits stream) ¶

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Function: write-counted-string (size-len stream buffer &key byte-order) ¶

Writes the length of the BUFFER on the STREAM as an unsigned integer of SIZE-LEN bytes in the specified BYTE-ORDER, then writes out the BUFFER.

Package

lisp-binary.

Source

binary-1.lisp.

Function: write-enum (enum symbol stream) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Function: write-integer (number size stream &key byte-order signed-representation signed) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Function: write-terminated-string (string stream &key terminator) ¶

Package

lisp-binary.

Source

binary-1.lisp.

---

5.1.5 Generic functions

Generic Function: call-with-file-position (stream position thunk) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Methods

Method: call-with-file-position ((stream bit-stream) position thunk) ¶

Source

simple-bit-stream.lisp.

Method: call-with-file-position (stream position thunk) ¶

Generic Function: read-binary (type stream) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Methods

Method: read-binary ((type (eql lisp-binary:terminated-string)) stream) ¶

Generic Function: read-bytes (n stream &key element-type) ¶

Read N bytes of type ELEMENT-TYPE from STREAM and return them in a newly-allocated array.

Returns two values: The array containing the bytes, and the number of bytes read.

For some types of stream, it is legal to use a fractional number for N. In that case,
the whole bytes are read first, and then the leftover bits. The leftover bits are given
their own byte at the end of the returned array. The second return value (# of bytes read)
will also be fractional in this case. The fractional part can be used to calculate
how many bits the partial byte represents.

If you’re using 8-bit bytes and want to read 11 bits (a whole byte plus three bits), give
11/8 as the value of N.

NOTE: If you’re using this with a bit-stream created with WRAP-IN-BIT-STREAM, the :BYTE-ORDER given to that function should match the one given to this function.

Package

lisp-binary/integer.

Source

integer.lisp.

Methods

Method: read-bytes (n (stream bit-stream) &key element-type) ¶

Source

binary-1.lisp.

Method: read-bytes (n stream &key element-type) ¶

Generic Function: wrap-in-bit-stream (object &key byte-order) ¶

Creates a BIT-STREAM that can read one bit at a time from the OBJECT. The BIT-STREAM can be discarded if BYTE-ALIGNED-P returns T.

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Methods

Method: wrap-in-bit-stream ((object stream) &key byte-order) ¶

Generic Function: wrap-in-reverse-stream (object) ¶

Creates a REVERSE-STREAM that can read one bit at a time from the OBJECT. The REVERSE-STREAM can be discarded if BYTE-ALIGNED-P returns T.

Package

reverse-stream.

Source

reverse-stream.lisp.

Methods

Method: wrap-in-reverse-stream ((object stream)) ¶

Generic Function: write-binary (obj stream) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Generic Function: write-bytes (buffer stream &optional bytes) ¶

Write BYTES bytes of the BUFFER into the STREAM. If
BYTES is not provided, then the whole BUFFER is written.

For some types of stream, it is legal to use a fractional number for BYTES. In that case, the whole bytes are written first, and then the leftover bits. The leftover bits must be given their own byte at the end of the BUFFER. WRITE-BYTES assumes that all bytes are 8 bits long, so to write 4 bits, you would give 1/2 as the value of BYTES.

NOTE: If you’re using this with a bit-stream created with WRAP-IN-BIT-STREAM, the :BYTE-ORDER given to that function should match the one given to this function.

Package

lisp-binary/integer.

Source

integer.lisp.

Methods

Method: write-bytes (buffer (stream bit-stream) &optional bytes) ¶

Source

binary-1.lisp.

Method: write-bytes (buffer stream &optional bytes) ¶

---

5.1.6 Standalone methods

Method: close ((stream reverse-stream) &key abort) ¶

Source

reverse-stream.lisp.

Method: close ((stream bit-stream) &key abort) ¶

Source

simple-bit-stream.lisp.

Method: stream-element-type ((stream bit-stream)) ¶

Source

simple-bit-stream.lisp.

Method: (setf stream-file-position) ((stream reverse-stream)) ¶

Package

trivial-gray-streams.

Source

reverse-stream.lisp.

Method: stream-file-position ((stream reverse-stream)) ¶

Package

trivial-gray-streams.

Source

reverse-stream.lisp.

Method: (setf stream-file-position) ((stream bit-stream)) ¶

Package

trivial-gray-streams.

Source

simple-bit-stream.lisp.

Method: stream-file-position ((stream bit-stream)) ¶

Package

trivial-gray-streams.

Source

simple-bit-stream.lisp.

Method: stream-finish-output ((stream reverse-stream)) ¶

Package

sb-gray.

Source

reverse-stream.lisp.

Method: stream-finish-output ((stream bit-stream)) ¶

Package

sb-gray.

Source

simple-bit-stream.lisp.

Method: stream-force-output ((stream reverse-stream)) ¶

Package

sb-gray.

Source

reverse-stream.lisp.

Method: stream-force-output ((stream bit-stream)) ¶

Package

sb-gray.

Source

simple-bit-stream.lisp.

Method: stream-read-byte ((stream reverse-stream)) ¶

Package

sb-gray.

Source

reverse-stream.lisp.

Method: stream-read-byte ((stream bit-stream)) ¶

Package

sb-gray.

Source

simple-bit-stream.lisp.

Method: stream-read-sequence ((stream reverse-stream) sequence start end &key &allow-other-keys) ¶

Package

trivial-gray-streams.

Source

reverse-stream.lisp.

Method: stream-read-sequence ((stream bit-stream) sequence start end &key &allow-other-keys) ¶

Package

trivial-gray-streams.

Source

simple-bit-stream.lisp.

Method: stream-write-byte ((stream reverse-stream) integer) ¶

Package

sb-gray.

Source

reverse-stream.lisp.

Method: stream-write-byte ((stream bit-stream) integer) ¶

Package

sb-gray.

Source

simple-bit-stream.lisp.

Method: stream-write-sequence ((stream reverse-stream) sequence start end &key &allow-other-keys) ¶

Package

trivial-gray-streams.

Source

reverse-stream.lisp.

Method: stream-write-sequence ((stream bit-stream) sequence start end &key &allow-other-keys) ¶

Package

trivial-gray-streams.

Source

simple-bit-stream.lisp.

---

5.1.7 Conditions

Condition: bad-enum-value ¶

Package

lisp-binary.

Source

binary-1.lisp.

Direct superclasses

simple-error.

Direct slots

Slot: integer-value ¶

Initargs

:integer-value

Slot: symbol-value ¶

Package

common-lisp.

Initargs

:symbol-value

Slot: enum-name ¶

Initargs

:enum-name

Condition: bad-magic-value ¶

Package

lisp-binary.

Source

binary-1.lisp.

Direct superclasses

simple-error.

Direct slots

Slot: bad-value ¶

Initargs

:bad-value

Slot: required-value ¶

Initargs

:required-value

Condition: input-string-too-long ¶

Package

lisp-binary.

Source

binary-1.lisp.

Direct superclasses

simple-error.

Direct slots

Slot: input-string ¶

Initargs

:input-string

Condition: no-destructuring-match ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Direct superclasses

warning.

---

5.1.8 Classes

Class: bit-stream ¶

Package

lisp-binary/integer.

Source

simple-bit-stream.lisp.

Direct superclasses

• fundamental-binary-stream.
• fundamental-input-stream.
• fundamental-output-stream.

Direct methods

• call-with-file-position.
• close.
• read-bytes.
• stream-element-type.
• (setf stream-file-position).
• stream-file-position.
• stream-finish-output.
• stream-force-output.
• stream-read-byte.
• stream-read-sequence.
• stream-write-byte.
• stream-write-sequence.
• write-bytes.

Direct slots

Slot: element-bits ¶

Package

simple-bit-stream.

Type

fixnum

Initform

8

Initargs

:element-bits

Slot: real-stream ¶

Package

simple-bit-stream.

Type

stream

Initargs

:real-stream

Slot: last-byte ¶

Package

simple-bit-stream.

Type

unsigned-byte

Initform

0

Slot: last-op ¶

Package

simple-bit-stream.

Type

symbol

Slot: bits-left ¶

Package

simple-bit-stream.

Type

integer

Initform

0

Slot: byte-order ¶

Package

simple-bit-stream.

Type

keyword

Initform

:little-endian

Initargs

:byte-order

Class: pointer ¶

Package

lisp-binary.

Source

binary-1.lisp.

Direct methods

• (setf pointer-base-pointer).
• pointer-base-pointer.
• (setf pointer-offset).
• pointer-offset.
• (setf pointer-stream).
• pointer-stream.
• (setf pointer-type).
• pointer-type.

Direct slots

Slot: offset ¶

Type

integer

Initform

0

Initargs

:offset

Readers

pointer-offset.

Writers

(setf pointer-offset).

Slot: type ¶

Package

common-lisp.

Type

symbol

Initargs

:type

Readers

pointer-type.

Writers

(setf pointer-type).

Slot: base-pointer ¶

Type

keyword

Initform

:beginning

Initargs

:base-pointer

Readers

pointer-base-pointer.

Writers

(setf pointer-base-pointer).

Slot: stream ¶

Package

common-lisp.

Type

stream

Initform

*standard-input*

Initargs

:stream

Readers

pointer-stream.

Writers

(setf pointer-stream).

Class: reverse-stream ¶

Package

reverse-stream.

Source

reverse-stream.lisp.

Direct superclasses

fundamental-binary-stream.

Direct methods

• close.
• (setf stream-file-position).
• stream-file-position.
• stream-finish-output.
• stream-force-output.
• stream-read-byte.
• stream-read-sequence.
• stream-write-byte.
• stream-write-sequence.

Direct slots

Slot: element-bits ¶

Type

fixnum

Initform

8

Initargs

:element-bits

Slot: lookup-table ¶

Initargs

:lookup-table

Slot: real-stream ¶

Type

stream

Initargs

:real-stream

---

5.2.1 Special variables

Special Variable: *8-bit-lookup-table* ¶

Package

reverse-stream.

Source

reverse-stream.lisp.

Special Variable: *always-produce-byte-count* ¶

These functions are known to always produce a byte count, so DEFBINARY doesn’t have to generate code to verify that they did.

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *base-pointer-tags* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *debug* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *denormals* ¶

Package

lisp-binary/float.

Source

float.lisp.

Special Variable: *enum-definitions* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *format-table* ¶

Package

lisp-binary/float.

Source

float.lisp.

Special Variable: *ignore-eval-type-bitstream-issue* ¶

If a DEFBINARY struct contains a field of type (EVAL ...),
then the macro cannot statically determine whether the struct can
be read without using a BIT-STREAM. If this is set to NIL, then
a condition is raised every time an (EVAL ...) type is encountered,
with restarts available to tell the macro whether a bitstream is
required for that particular field.

Typically, the error would reach EMACS, and the programmer can then
pick a restart from the menu.

However, this doesn’t work if you’re using COMPILE-FILE, because COMPILE-FILE
catches exceptions, so you don’t see the error until it has already been
caught, so you will not be presented with the restarts that I have set up.

For most programs, just ignoring the issue is good enough. Setting this to T (the default) causes the expander to ignore this problem and not raise a condition.

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *ignore-on-write* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *known-defbinary-types* ¶

An alist whose keys are the names of DEFBINARY structs and whose values are the field-descriptions of those structs. Needed by TYPE-SIZE

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *last-f* ¶

Package

lisp-binary.

Source

binary-2.lisp.

Special Variable: *outer-stream-file-position* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *queued-pointers* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *type-docstrings* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *type-expanders* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *type-info-objects* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: *virtual-types* ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: debug-data ¶

Package

lisp-binary.

Source

binary-1.lisp.

Special Variable: defbinary-type ¶

Package

lisp-binary.

Source

binary-1.lisp.

---

5.2.2 Macros

Macro: acond (&rest cases) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: decode-float-bits/arithmetic-macro (integer &key format result-type) ¶

Package

lisp-binary/float.

Source

float.lisp.

Macro: define-lisp-binary-type (type-info-var lambda-list &body body) ¶

Defines a LISP-BINARY type. The TYPE-INFO-VAR will be bound to a DEFBINARY-TYPE
object that describes the field. The LAMBDA-LIST will be structurally matched against
the :TYPE parameter specified in the DEFBINARY form. The BODY may begin with the keyword
:WHERE followed by a form. If present, this form acts as a further condition for considering
the LAMBDA-LIST to match the :TYPE parameter.

The BODY is expected to return 3 values:

1. The Lisp type that should be used to represent the instance of this LISP-BINARY type described
by the LAMBDA-LIST.
2. A form that reads an instance of the data described by the LAMBDA-LIST from a stream whose name
will be bound to STREAM-SYMBOL.
3. A form that writes an instance of the data from a variable whose name will be bound to NAME, into
a stream whose name is bound to STREAM-SYMBOL.

The slots of the DEFBINARY-TYPE object provide extra information, and will be bound in the BODY using WITH-SLOTS. These slots are described below:

NAME - The name of the variable to be defined. The WRITER-FORM will be evaluated in a context
where the NAME is bound to the object being written.
TYPE - The type specifier. It’s the same value that will have been matched against the LAMBDA-LIST.

BYTE-ORDER - :LITTLE-ENDIAN or :BIG-ENDIAN.
TERMINATOR - A SIMPLE-ARRAY that will be matched against the input to determine the end of a string.
If the TYPE is itself a SIMPLE-ARRAY, TERMINATOR can be a function, which will be passed
each element read. (TODO: Actually implement that function part)
READER - A user-specified function that overrides the reader that this function would otherwise generate.
WRITER - A user-specified writer function that overrides the default writer.
STREAM-SYMBOL - The name that will be given to the input and output stream.

PREVIOUS-DEFS-SYMBOL - A symbol that will be bound to a list of LET bindings at runtime. In the event of
an EVAL type, code is generated that will splice the LET bindings found here
into a runtime-constructed LET form that will then be EVAL’d.
BYTE-COUNT-NAME - The name of the variable that will be bound to the number of bytes read or written so far. ALIGN - The alignment boundary
ELEMENT-ALIGN - The alignment boundary for individual elements in an array.
BIND-INDEX-TO - In array reads and writes, may specify a variable to bind the loop index to.
Or it can be NIL.

Package

lisp-binary.

Source

binary-1.lisp.

Macro: define-virtual-type (name lambda-list reader writer lisp-type &key estimated-total-bits stream-required can-be-in-bit-field) ¶

Define a new Virtual Type.

A Virtual Type is a rule that tells the LISP-BINARY how to read a particular kind of
value from a stream, and how to write it back. The result of reading a Virtually-Typed object
can be an object of any Lisp type. Which Lisp type the Virtual Type corresponds to must
be specified in the LISP-TYPE argument.

The same LISP-TYPE can be produced by many different Virtual Types. As a result, the LISP-BINARY library must always be told which type it is reading or writing. This is usually done at compile-time through the DEFBINARY macro.

The READER and WRITER must be functions.

The READER accepts a STREAM argument and returns two values:

1. The fully-processed value that was read.
2. The number of bytes that were read from the STREAM. If the STREAM is a BIT-STREAM,
then the number of bytes can be fractional, to indicate how much was read down to
the bit. 1/8 of a byte = 1 bit.

The WRITER accepts the lambda list (OBJ STREAM), where OBJ is the value to be written. It
returns the number of bytes that were written.

Package

lisp-binary.

Source

binary-1.lisp.

Macro: encode-float-bits/arithmetic-macro (fraction format) ¶

Package

lisp-binary/float.

Source

float.lisp.

Macro: let-values/stupid* (bindings &body body) ¶

A naive implementation of LET-VALUES*. Each binding must bind a multiple-value expression to a list of variables, and will expand to a nested MULTIPLE-VALUE-BIND expression.

Package

lisp-binary-utils.

Source

utils.lisp.

Macro: make-reader-let-def (f) ¶

Package

lisp-binary.

Source

binary-2.lisp.

Macro: popbit (place) ¶

Package

lisp-binary/float.

Source

float.lisp.

Macro: read-bytes-with-partial/macro (stream* bits byte-order &key adjustable) ¶

Package

simple-bit-stream.

Source

simple-bit-stream.lisp.

Macro: read-octets-to-string (read-form &rest options) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Macro: read/write-binary-type (read-or-write type stream &key value byte-order align element-align) ¶

Package

lisp-binary.

Source

binary-1.lisp.

Macro: tif (expr if-t if-nil) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: tlabels (labels &body body) ¶

Package

lisp-binary/integer.

Source

integer.lisp.

Macro: with-letf-bindings ((temp-var place-var value-var temp-binding place-binding) &body body) ¶

Package

lisp-binary-utils.

Source

utils.lisp.

---