BitStruct

Class for packed binary data stored in ruby Strings. BitStruct accessors, generated from user declared fields, use pack/unpack to treat substrings as fields with a specified portable format.

Field types include

• signed and unsigned integer (1..16 bits, or 24, 32, 40, 48… bits)
• numeric fields (signed, unsigned, float) can be designated as any of the following endians: little, big, native, network (default)
• fixed point, with arbitrary scale factor
• fixed length character array
• null-terminated character array for printable text
• octets (hex and decimal representation options; useful for IP and MAC addrs)
• float
• nested BitStruct
• free-form "rest" field (e.g., for the variable-size payload of a packet)

Installation

  ruby install.rb config
  ruby install.rb setup
  ruby install.rb install

Uses

BitStruct is useful for defining packets used in network protocols. This is especially useful for raw IP—see examples/ping-recv.rb. All multibyte numeric fields are stored in network order (though this could be different for user-defined field classes).

BitStruct is most efficient when your data is primarily treated as a binary string, and only secondarily treated as a data structure. (For instance, you are routing packets from one socket to another, possibly looking at one or two fields as it passes through or munging some headers.) If accessor operations are a bottleneck, a better approach is to define a class that wraps an array and uses pack/unpack when the object needs to behave like a binary string.

Recent Changes:

bit-struct 0.9

• Added examples/field-ripper.rb.
• Added BitStruct#field_by_name.
• Added more warnings about nested field accessors returning a copy of the nested data.
• Added "pad" fields. See documentation in pad-field.rb and examples/pad.rb.
• The #initial_value method now yields the value to a block, if given.
• A BitStruct class is only closed when an instance is created. (After this point no fields can be added.) Formerly, a class was closed when any method requested the total length of the structure. This change makes it easier to add groups of fields modularly, each with their own initial_value block.
• Added examples/modular-def.rb to explain how to factor a BitStruct definition into modules.

bit-struct 0.8

• Signed fields can now (like unsigned fields) be any multiple of 8 bits, and are accessed as fixnums or bignums, as needed.
• It’s easier to subclass BitStruct::OctetField. BitStruct::HexOctetField is now implemented in this way, just by defining three constants and two trivial class methods.

bit-struct 0.7

• BitStruct.describe now takes an option hash, and the :expand=>true option causes nested fields to be expanded in the description.
• Unsigned integer fields can now be any multiple of 8 bytes: 8, 16, 24, 32, 40, … (Fields of 1..15 bits in length are of course still supported.)
• Added the :endian => :little option to signed integer, unsigned integer, and float fields. The full set of endian options is now [:little, :big, :network, :native]. The default is always :network.
• Option names may be strings or symbols. Values that can be symbols can also be strings.
• Added examples/bignum.rb.
• Added support for the YAML in ruby 1.8.2 (the YAML in 1.8.4 was already supported).