Binary data parser helper with an ASN.1 parser
1.0.0 released

BinData - Parsing Binary Data in Crystal Lang

BinData provides a declarative way to read and write structured binary data.

This means the programmer specifies what the format of the binary data is, and BinData works out how to read and write data in this format. It is an easier (and more readable) alternative.

Build Status


Firstly, it's recommended that you specify the datas endian.

class Header < BinData
  endian big

Then you can specify the structures fields. There are a few different field types:

  1. Core types
    • uint8, int128 which would accept UInt8 and Int128 values respectively
  2. Custom types
  3. Bit Fields
    • These are a group of fields who values are defined by the number of bits used to represent their value
    • The total number of bits in a bit field must be divisible by 8
  4. Groups
    • These are embedded BinData class with access to the parent fields
    • Useful when a group of fields are related or optional
  5. Enums and Bool


  enum Inputs

  class Packet < BinData
    endian big

    # Default sets the value at initialisation.
    uint8 :start, default: 0xFF_u8

    # Value procs assign these values before writing to an IO, overwriting any
    # existing value
    uint16 :size, value: ->{ text.bytesize + 1 }

    # String fields without a length use `\0` null byte termination
    # Length is being calculated by the size field above
    string :text, length: ->{ size - 1 }

    # Bit fields should only be used when one or more fields are not byte aligned
    # The sum of the bits in a bit field must be divisible by 8
    bit_field do
      # a bits value can be between 1 and 128 bits long
      bits 5, :reserved

      # Bool values are a single bit
      bool :set_input, default: false

      # This enum is represented by 2 bits
      enum_bits 2, input : Inputs = Inputs::HDMI2

    # isolated namespace
    group :extended, onlyif: ->{ start == 0xFF } do
      uint8 :start, default: 0xFF_u8

      # Supports custom objects as long as they implement `from_io`
      custom header : ExtHeader =

The object above can then be accessed like any other object

  pack = io.read_bytes(Packet)
  pack.size # => 12
  pack.text # => "hello world"
  pack.input # => Inputs::HDMI
  pack.set_input # => true
  pack.extended.start # => 255
  github: spider-gazelle/bindata
  version: ~> 1.0.0
Crystal none

Dependencies 0

Development Dependencies 1

  • ameba
    {'github' => 'veelenga/ameba'}
Last synced .
search fire star recently