https://github.com/Shinmera/binary-structures

A library for reading, writing, and representing structures from binary storage
https://github.com/Shinmera/binary-structures

Last synced: 3 months ago
JSON representation

A library for reading, writing, and representing structures from binary storage

• Host: GitHub
• URL: https://github.com/Shinmera/binary-structures
• Owner: Shinmera
• License: zlib
• Created: 2023-04-17T19:00:11.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-01-02T01:48:27.000Z (11 months ago)
• Last Synced: 2024-05-02T01:48:25.110Z (7 months ago)
• Language: Common Lisp
• Homepage: https://shinmera.github.io/binary-structures/
• Size: 74.2 KB
• Stars: 16
• Watchers: 3
• Forks: 1
• Open Issues: 7
• Metadata Files:
  • Readme: README.mess
  • License: LICENSE

Awesome Lists containing this project

README

        
# About binary-structures

This is yet another library implementing a compiler to make parsing binary files or structures easier. It generates reader and writer functions to translate from streams, octet vectors, and memory pointers directly, and has an extensible protocol to allow implementing other storage backends as well.

## How To

The primary entry point is via ``define-io-structure``. It'll define the structure type, io-type, and the parsing functions for you in one go. Here's an example that shows off most capabilities:

:: common lisp

(define-io-structure rgb

  (r uint8)

  (g uint8)

  (b uint8))

(define-io-structure rgba

  (:include rgb)

  (a uint8))

(define-io-structure image

  "IMG"

  (version uint8)

  (width uint32)

  (height uint32)

  (pixel-type (case uint8

                (1 'uint8)

                (2 'rgb)

                (3 'rgba)))

  (data (vector (case (slot pixel-type)

                  (uint8 uint8)

                  (rgb rgb)

                  (rgba rgba))

                (* (slot width) (slot height)))))

::

From there you should have a ``read-image`` and ``write-image`` function, as well as the ``image`` structure and accessors to deal with the data.

## Standard Types

The following type names are defined and available in the ``org.shirakumo.binary-structures.types`` package:

- ``uint8``

- ``uint16``

- ``uint32``

- ``uint64``

- ``uint128``

- ``sint8``

- ``sint16``

- ``sint32``

- ``sint64``

- ``sint128``

- ``float16``

- ``float32``

- ``float64``

- ``float128``

- ``uint8-be``

- ``uint16-be``

- ``uint32-be``

- ``uint64-be``

- ``uint128-be``

- ``sint8-be``

- ``sint16-be``

- ``sint32-be``

- ``sint64-be``

- ``sint128-be``

- ``float16-be``

- ``float32-be``

- ``float64-be``

- ``float128-be``

- ``utf8-string``

- ``utf16-string``

- ``utf32-string``

- ``latin1-string``

- ``(string [SIZE] [ENCODING])``

  See ``io-string``

- ``(integer [SIZE] [SIGNEDNESS] [ORDER])``

  See ``io-integer``

- ``(float [SIZE])``

  See ``io-float``

- ``(vector ELEMENT-TYPE [ELEMENT-COUNT] [ELEMENT-OFFSET])``

  See ``io-vector``

- ``(case VALUE-TYPE CASE...)``

  See ``io-case``

- ``(typecase FORM CASE...)``

  See ``io-typecase``

## Limitations

This library is best suited towards files with a clear, fixed layout that grows sequentially from the beginning. Formats like ZIP that need to be scanned from the end cannot be decoded. There's also no way to restructure data after it has been parsed, so you may need additional wrapper functions or a secondary translation step to create a truly convenient view of the data. Finally, all data must be octet-aligned.