description.text

BINARY-TYPES is a Common Lisp system for reading and writing binary files.  Binary-types provides macros that are used to declare the mapping between lisp objects and most binary (i.e. octet-based) representations.  Binary-types is *not* helpful in reading files with variable bit-length code-words, such as most compressed file formats. It will basically only work with file-formats based on 8-bit bytes (octets).


Objectives

Support most kinds of binary types including:

 * Signed and unsigned integers of any octet-size, big-endian or
   little-endian. Maps to lisp integers.

 * Enumerated types based on any integer type. Maps to lisp symbols.

 * Complex bit-field types based on any integer type. Sub-fields can
   be numeric, enumerated, or bit-flags. Maps to lisp lists of symbols
   and integers.

 * Fixed-length and null-terminated strings. Maps to lisp strings.

 * Compound records of other binary types. Maps to lisp `DEFCLASS`
   classes or, when you prefer, `DEFSTRUCT` structs.

 * Vectors and arrays of integers and floats.

 * 32 and 64 bit IEEE-754 floats map to lisp `single-float` and `double-float`.



History

BINARY-TYPES was developed over the years 1999-2003 by Frode Vatvedt Fjeld <frodef@acm.org> whilst working at the Department of Computer Science, University of Tromsø, Norway. It later served as the basis for [Chapter 24: Parsing Binary Files](https://gigamonkeys.com/book/practical-parsing-binary-files) of the book [Practical Common Lisp](https://gigamonkeys.com/book/) by Peter Seibel.  That chapter makes a good technical reference for the system, and you should read it if you want to extend BINARY-TYPES.

Frode's version was sufficiently well done that the system went largely unchanged since except for some local additions for [slitch](https://github.com/sharplispers/slitch/tree/master) a low-level networking library in 2003 and then again in a [fork by Olof-Joachim Frahm](https://github.com/Ferada/binary-types/commits/master/) in 2013 that added 256 bit integers.

This repository began in 2024 and adds support for 32/64 bit IEEE-754 floats, binary arrays/vectors, improved documentation and refactored the repository/ASDF system.