bistro 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3005111ea2c6d80cebb2b9fbb18942b70b8c90d6c785bb1b54a65db01e978fa
+  data.tar.gz: 62fdd3216e53989c4fcb18b1a8a38c3399b44c2daac249c9cabfcafd4d907415
+SHA512:
+  metadata.gz: e656723aae47b109c66804e0ec03838193c464b3a4d0377f7691f8ea02f0c783fbfc5e4ad04fcda4bdab88a8012d23f242f25ac688ecab8e86c84406b6a51fd8
+  data.tar.gz: ae09a95c27537d26b0bfcfa6c418e72cbe95c358ef0e3d10976924ecb0d2c8894341060887427c97fad8b3abcd7b3765bf77f9449a859b11e2a8902090c69761

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Dev Null Productions <devnullproductions@gmail.com>
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Bistro
+
+Bistro is a class for dealing with BInary STRuctured data.  It simplifies
+expressing what the binary structure looks like, with the ability to name the
+parts.  Given this definition, it is easy to encode/decode the binary structure
+from/to a Hash.
+
+## Example Usage
+
+As an example, we will show reading and writing a .gif header.  This example is
+also in spec/gif_spec.rb.
+
+### Create the structure definition
+
+```ruby
+gif_header = Bistro.new([
+  "a3", :magic,
+  "a3", :version,
+  "S",  :width,
+  "S",  :height,
+  "a",  :flags,
+  "C",  :bg_color_index,
+  "C",  :pixel_aspect_ratio
+])
+```
+
+### Read the header
+
+```ruby
+header_size = gif_header.size
+header = File.open("test.gif", "rb") { |f| f.read(header_size) }
+gif_header.decode(header)
+
+=> {
+  :magic              => "GIF",
+  :version            => "89a",
+  :width              => 16,
+  :height             => 16,
+  :flags              => "\x80",
+  :bg_color_index     => 0,
+  :pixel_aspect_ratio => 0
+}
+```
+
+### Write the header
+
+```ruby
+header = gif_header.encode({
+  :magic              => "GIF",
+  :version            => "89a",
+  :width              => 16,
+  :height             => 16,
+  :flags              => "\x80",
+  :bg_color_index     => 0,
+  :pixel_aspect_ratio => 0
+})
+File.open("test.gif", "wb") { |f| f.write(header) }
+
+=> "GIF89a\x10\x00\x10\x00\x80\x00\x00"
+```
+
+## Note about bit and nibble formats
+
+Bistro supports bit formats and nibble formats, however note that the
+underlying Ruby methods, [pack](http://ruby-doc.org/core-2.2.0/Array.html#method-i-pack)
+and [unpack](http://ruby-doc.org/core-2.2.0/String.html#method-i-unpack), support
+less than 8 bits by reading an entire byte, even if all of the bits are not used.
+
+For example,
+
+```ruby
+s = "\xFF\x00"       # binary: 1111111100000000
+s.unpack("b8b8")     # => ["11111111", "00000000"]
+s.unpack("b4b4b4b4") # => ["1111", "0000", "", ""]
+```
+
+One might expect that the latter would read 4 bits, then the next 4 bits, etc,
+yielding `["1111", "1111", "0000", "0000"]`, but that is not the case.  Instead,
+the first b4 reads a full byte's worth, then discards the unused 4 bits, and the
+same happens for the next b4.  The third and fourth b4 have nothing left to read,
+and so just return empty strings.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bistro'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bistro
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/bistro.rb

@@ -0,0 +1,229 @@
+require "bistro/version"
+require "enumerator"
+
+class Bistro
+  SIZES = {
+    'A'   => 1,   # String with trailing NULs and spaces removed
+    'a'   => 1,   # String
+    'B'   => 1,   # Extract bits from each character (MSB first)
+    'b'   => 1,   # Extract bits from each character (LSB first)
+    'C'   => 1,   # Extract a character as an unsigned integer
+    'c'   => 1,   # Extract a character as a    signed integer
+    'E'   => nil, # Treat sizeof(double) characters as a double in little-endian byte order
+    'e'   => nil, # Treat sizeof(float)  characters as a float  in little-endian byte order
+    'G'   => nil, # Treat sizeof(double) characters as a double in network       byte order
+    'g'   => nil, # Treat sizeof(float)  characters as a float  in network       byte order
+    'H'   => 1,   # Extract hex nibbles from each character (most  significant first)
+    'h'   => 1,   # Extract hex nibbles from each character (least significant first)
+    'I'   => 4,   # Treat sizeof(int) successive characters as an unsigned native integer
+    'i'   => 4,   # Treat sizeof(int) successive characters as a    signed native integer
+    'L'   => 4,   # Treat 4 successive characters as an unsigned native long integer
+    'l'   => 4,   # Treat 4 successive characters as a    signed native long integer
+    'M'   => 1,   # Extract a quoted printable string
+    'm'   => 1,   # Extract a Base64 encoded string
+    'N'   => 4,   # Treat 4 characters as an unsigned long  in network byte order
+    'n'   => 2,   # Treat 2 characters as an unsigned short in network byte order
+    'P'   => nil, # Treat sizeof(char *) characters as a pointer, and return len characters from the referenced location
+    'p'   => nil, # Treat sizeof(char *) characters as a pointer to a null-terminated string
+    'Q'   => 8,   # Treat 8 characters as an unsigned quad word (64 bits)
+    'q'   => 8,   # Treat 8 characters as a    signed quad word (64 bits)
+    'S'   => 2,   # Treat 2 successive characters as an unsigned short in native byte order
+    's'   => 2,   # Treat 2 successive characters as a    signed short in native byte order
+    'U'   => nil, # Extract UTF-8 characters as unsigned integers
+    'u'   => nil, # Extract a UU-encoded string
+    'V'   => 4,   # Treat 4 characters as an unsigned long  in little-endian byte order
+    'v'   => 2,   # Treat 2 characters as an unsigned short in little-endian byte order
+    'w'   => nil, # BER-compressed integer
+    'X'   => -1,  # Skip backward one character
+    'x'   => 1,   # Skip forward  one character
+    'Z'   => 1,   # String with trailing NULs removed
+  }
+
+  STRING_FORMATS   = %w(A a B b H h M m u)
+  BIT_FORMATS      = %w(B b)
+  NIBBLE_FORMATS   = %w(H h)
+  ENDIAN_FORMATS   = %w(I i L l Q q S s)
+  ENDIAN_MODIFIERS = %w(> <)
+  MODIFIERS        = ENDIAN_MODIFIERS
+
+  def initialize(definition = nil)
+    self.definition = definition unless definition.nil?
+  end
+
+  def definition
+    @definition
+  end
+
+  def definition=(value)
+    if value.kind_of?(self.class)
+      @definition = value.definition.dup
+    else
+      value = value.to_a.map(&:reverse).flatten if value.kind_of?(Hash)
+      value = Array(value)
+      self.class.validate_definition(value)
+      @definition = value
+    end
+    @size = @decode_format = @decode_name = nil
+  end
+
+  def size
+    @size ||= self.class.get_size(@definition)
+  end
+
+  def decode(data, num = 1)
+    values = self.decode_to_array(data, num)
+    return self.decoded_array_to_hash!(values) if num == 1
+
+    result = []
+    num.times { result << self.decoded_array_to_hash!(values) }
+    return result
+  end
+
+  def decode_to_array(data, num = 1)
+    raise ArgumentError, "data cannot be nil" if data.nil?
+    @decode_format, @decode_names = self.class.prep_decode(@definition) if @decode_format.nil?
+    format = (num == 1) ? @decode_format : @decode_format * num
+    return data.unpack(format)
+  end
+
+  def decoded_array_to_hash!(array)
+    hash = {}
+    @decode_names.each do |k|
+      v = array.shift
+      next if k.nil?
+      hash[k] = v
+    end
+    return hash
+  end
+
+  def encode(hash)
+    return encode_hash(hash) unless hash.kind_of?(Array)
+
+    data = ""
+    hash.each { |h| data << self.encode_hash(h) }
+    return data
+  end
+
+  def encode_hash(hash)
+    data = ""
+    @definition.each_slice(2) do |format, name|
+      raise "member not found: #{name}" unless name.nil? || hash.has_key?(name)
+      value = unless name.nil?
+        hash[name]
+      else
+        STRING_FORMATS.include?(format[0, 1]) ? '0' : 0
+      end
+      data << [value].pack(format)
+    end
+    return data
+  end
+
+  def ==(other)
+    self.definition == other.definition
+  end
+
+  def each(&block)
+    self.definition.each_slice(2, &block)
+  end
+
+  #
+  # Methods to handle the old style of calling
+  #
+
+  @@structs_by_definition = {}
+
+  def self.clear_structs_by_definition_cache
+    @@structs_by_definition.clear
+  end
+
+  def self.sizeof(definition)
+    struct_by_definition(definition).size
+  end
+
+  def self.decode(data, definition)
+    struct_by_definition(definition).decode(data)
+  end
+
+  def self.encode(hash, definition)
+    struct_by_definition(definition).encode(hash)
+  end
+
+  private
+
+  def self.struct_by_definition(definition)
+    @@structs_by_definition[definition] ||= definition.kind_of?(self) ? definition : self.new(definition)
+  end
+
+  def self.validate_definition(definition)
+    raise "definition must be an array of format/name pairs" if definition.empty? || definition.length % 2 != 0
+    definition.each_slice(2) do |format, _|
+      type, count = format[0, 1], format[1..-1]
+      modifier, modcount = count[0, 1], count[1..-1]
+      validate_definition_entry_type(type)
+      if valid_definition_entry_modifier?(modifier)
+        validate_definition_endian_modifier(modifier, type)
+        validate_definition_entry_count(modcount)
+      else
+        validate_definition_entry_count(count)
+      end
+    end
+  end
+
+  def self.validate_definition_entry_type(type)
+    raise "unrecognized format: #{type}" unless SIZES.has_key?(type)
+    raise "unsupported format: #{type}" if SIZES[type].nil?
+    return true
+  end
+
+  def self.validate_definition_entry_count(count)
+    return true if count.empty? || count == '*'
+
+    begin
+      count = Integer(count)
+    rescue
+      raise "unsupported count: #{count}"
+    end
+    raise "unsupported count: #{count}" if count < 0
+  end
+
+  def self.valid_definition_entry_modifier?(modifier)
+    MODIFIERS.include? modifier
+  end
+
+  def self.validate_definition_endian_modifier(modifier, type)
+    if ENDIAN_MODIFIERS.include? modifier
+      raise "unsupported type attribute #{type} for endian modifier #{modifier}" unless ENDIAN_FORMATS.include? type
+      return true
+    end
+    false
+  end
+
+  def self.get_size(definition)
+    size = 0
+    definition.each_slice(2) do |format, _|
+      type, count        = format[0, 1], format[1..-1]
+      modifier, modcount = count[0, 1], count[1..-1]
+      count = modcount if valid_definition_entry_modifier?(modifier)
+      count = count.empty? ? 1 : count.to_i
+      size +=
+        if BIT_FORMATS.include?(type)
+          (count / 8.0).ceil
+        elsif NIBBLE_FORMATS.include?(type)
+          (count / 2.0).ceil
+        else
+          count * SIZES[type]
+        end
+    end
+    size
+  end
+
+  def self.prep_decode(definition)
+    formats = ""
+    names = []
+    definition.each_slice(2) do |format, name|
+      formats << format
+      names << name
+    end
+    return formats, names
+  end
+end

data/lib/bistro/version.rb

@@ -0,0 +1,3 @@
+class Bistro
+  VERSION = "2.1.0"
+end

data/spec/bistro_spec.rb

@@ -0,0 +1,133 @@
+describe Bistro do
+  STRUCT_DEF = [
+    'Q',  :quad,
+    'L',  'long',
+    'S',  :short,
+    'C',  nil,
+    'b5', :binary,
+    'a0', 'none',
+    'a',  nil,
+    'a2', 'bc',
+  ]
+  STRUCT_DEF_SIZE = 19
+
+  STRUCT_DEF_HASH = {
+    :quad   => 'Q',
+    'long'  => 'L',
+    :short  => 'S',
+    nil     => 'C',
+    :binary => 'b5',
+    'none'  => 'a0',
+    :unused => 'a',
+    'bc'    => 'a2',
+  }
+
+  STRUCT_DEF_ASTERISK = ['a*', :word]
+  STRUCT_DEF_ASTERISK_SIZE = 0 # '*' is ignored
+
+  STRUCT_DEF_UNRECOGNIZED_FORMAT   = ['D', nil]
+  STRUCT_DEF_UNSUPPORTED_FORMAT    = ['U', nil]
+  STRUCT_DEF_UNSUPPORTED_COUNT_NEG = ['a-1', nil]
+  STRUCT_DEF_UNSUPPORTED_COUNT_INV = ['aX', nil]
+
+  STRUCT_ENCODED_STR  = "\000\111\222\333\444\555\666\777\000\111\222\333\000\111\000\0320BC".force_encoding("ASCII-8BIT")
+  STRUCT_DECODED_HASH = {
+    :quad   => 18_426_034_930_503_010_560,
+    "long"  => 3_683_797_248,
+    :short  => 18_688,
+    :binary => "01011",
+    "bc"    => "BC",
+    "none"  => ""
+  }
+  STRUCT_DECODED_HASH2 = STRUCT_DECODED_HASH.merge(:unused => "0")
+
+  it('.new') { expect { Bistro.new }.not_to raise_error }
+  it('.new with definition') { expect { Bistro.new(STRUCT_DEF) }.not_to raise_error }
+  it('.new with definition with *') { expect { Bistro.new(STRUCT_DEF_ASTERISK) }.not_to raise_error }
+  it('.new with Hash defintion') { expect { Bistro.new(STRUCT_DEF_HASH) }.not_to raise_error }
+  it '.new with another Bistro' do
+    s = Bistro.new(STRUCT_DEF)
+    s2 = Bistro.new(s)
+    expect(s2).to eq(s)
+    expect(s2).not_to equal(s)
+  end
+
+  it('.new with unrecognized format')        { expect { Bistro.new(STRUCT_DEF_UNRECOGNIZED_FORMAT) }.to   raise_error(RuntimeError) }
+  it('.new with unsupported format')         { expect { Bistro.new(STRUCT_DEF_UNSUPPORTED_FORMAT) }.to    raise_error(RuntimeError) }
+  it('.new with unsupported negative count') { expect { Bistro.new(STRUCT_DEF_UNSUPPORTED_COUNT_NEG) }.to raise_error(RuntimeError) }
+  it('.new with unsupported invalid count')  { expect { Bistro.new(STRUCT_DEF_UNSUPPORTED_COUNT_INV) }.to raise_error(RuntimeError) }
+
+  it('#definition=') { expect { Bistro.new.definition = STRUCT_DEF }.not_to raise_error }
+  it('#definition= with definition with *') { expect { Bistro.new.definition = STRUCT_DEF_ASTERISK }.not_to raise_error }
+  it('#definition= with Hash defintion') { expect { Bistro.new.definition = STRUCT_DEF_HASH }.not_to raise_error }
+
+  it('#definition= with unrecognized format')        { expect { Bistro.new.definition = STRUCT_DEF_UNRECOGNIZED_FORMAT }.to   raise_error(RuntimeError) }
+  it('#definition= with unsupported format')         { expect { Bistro.new.definition = STRUCT_DEF_UNSUPPORTED_FORMAT }.to    raise_error(RuntimeError) }
+  it('#definition= with unsupported negative count') { expect { Bistro.new.definition = STRUCT_DEF_UNSUPPORTED_COUNT_NEG }.to raise_error(RuntimeError) }
+  it('#definition= with unsupported invalid count')  { expect { Bistro.new.definition = STRUCT_DEF_UNSUPPORTED_COUNT_INV }.to raise_error(RuntimeError) }
+
+  it('#size') { expect(Bistro.new(STRUCT_DEF).size).to eq(STRUCT_DEF_SIZE) }
+  it('#size with definition with *') { expect(Bistro.new(STRUCT_DEF_ASTERISK).size).to eq(STRUCT_DEF_ASTERISK_SIZE) }
+
+  it '#decode' do
+    expect(Bistro.new(STRUCT_DEF).decode(STRUCT_ENCODED_STR)).to eq(STRUCT_DECODED_HASH)
+  end
+
+  it '#decode with definition with *' do
+    expect(Bistro.new(STRUCT_DEF_ASTERISK).decode("Testing")).to eq(:word => "Testing")
+  end
+
+  it '#decode with Hash defintion' do
+    expect(Bistro.new(STRUCT_DEF_HASH).decode(STRUCT_ENCODED_STR)).to eq(STRUCT_DECODED_HASH2)
+  end
+
+  it '#decode against multiple records' do
+    expect(Bistro.new(STRUCT_DEF).decode(STRUCT_ENCODED_STR * 10, 10)).to eq([STRUCT_DECODED_HASH] * 10)
+  end
+
+  it '#encode' do
+    expect(Bistro.new(STRUCT_DEF).encode(STRUCT_DECODED_HASH)).to eq(STRUCT_ENCODED_STR.force_encoding("ASCII-8BIT"))
+  end
+
+  it '#encode with definition with *' do
+    expect(Bistro.new(STRUCT_DEF_ASTERISK).encode(:word => "Testing")).to eq("Testing")
+  end
+
+  it '#encode against multiple records' do
+    s = Bistro.new(STRUCT_DEF).encode([STRUCT_DECODED_HASH] * 10)
+    expect(s).to eq(STRUCT_ENCODED_STR.force_encoding("ASCII-8BIT") * 10)
+  end
+
+  it '#== against another Bistro' do
+    expect(Bistro.new(STRUCT_DEF)).to     eq(Bistro.new(STRUCT_DEF))
+    expect(Bistro.new(STRUCT_DEF)).not_to eq(Bistro.new(STRUCT_DEF_ASTERISK))
+  end
+
+  it '#each will iterate over definition' do
+    dup_def = []
+    Bistro.new(STRUCT_DEF).each { |field, name| dup_def << field << name }
+    expect(dup_def).to eq(STRUCT_DEF)
+  end
+
+  context "old style methods" do
+    after(:each) { Bistro.clear_structs_by_definition_cache }
+
+    it '#sizeof' do
+      expect(Bistro.sizeof(STRUCT_DEF)).to eq(STRUCT_DEF_SIZE)
+      # Do it twice for consistency reasons
+      expect(Bistro.sizeof(STRUCT_DEF)).to eq(STRUCT_DEF_SIZE)
+    end
+
+    it '#decode' do
+      expect(Bistro.decode(STRUCT_ENCODED_STR, STRUCT_DEF)).to eq(STRUCT_DECODED_HASH)
+      # Do it twice for consistency reasons
+      expect(Bistro.decode(STRUCT_ENCODED_STR, STRUCT_DEF)).to eq(STRUCT_DECODED_HASH)
+    end
+
+    it '#encode' do
+      expect(Bistro.encode(STRUCT_DECODED_HASH, STRUCT_DEF)).to eq(STRUCT_ENCODED_STR.force_encoding("ASCII-8BIT"))
+      # Do it twice for consistency reasons
+      expect(Bistro.encode(STRUCT_DECODED_HASH, STRUCT_DEF)).to eq(STRUCT_ENCODED_STR.force_encoding("ASCII-8BIT"))
+    end
+  end
+end

data/spec/endian_spec.rb

@@ -0,0 +1,203 @@
+describe Bistro do
+  BIG_STRUCT_DEF = [
+    'Q>', :quad,
+    'L>', 'long',
+    'S>', :short,
+    'C',  nil,
+    'b5', :binary,
+    'a0', 'none',
+    'a',  nil,
+    'a2', 'bc',
+  ]
+  BIG_STRUCT_DEF_SIZE                         = 19
+
+  BIG_E_QUAD_STRUCT_DEF                       = ['Q>2',  :quad]
+  BIG_E_QUAD_DEF_SIZE                         = 16
+
+  BIG_STRUCT_DEF_STAR                         = ['i>*', :word]
+  BIG_STRUCT_DEF_STAR_SIZE                    = 0 # '*' is ignored
+
+  BIG_STRUCT_DEF_UNRECOG_ENDIAN_FMT           = ['Y>', nil]
+  BIG_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE = ['A>', nil]
+  BIG_STRUCT_DEF_INVALID_ENDIAN_MODIFIER      = ['Q_', nil]
+
+  LIL_STRUCT_DEF = [
+    'Q<', :quad,
+    'L<', 'long',
+    'S<', :short,
+    'C',  nil,
+    'b5', :binary,
+    'a0', 'none',
+    'a',  nil,
+    'a2', 'bc',
+  ]
+  LIL_STRUCT_DEF_SIZE                         = 19
+
+  LIL_E_QUAD_STRUCT_DEF                       = ['Q<2',  :quad]
+  LIL_E_QUAD_DEF_SIZE                         = 16
+
+  LIL_STRUCT_DEF_STAR                         = ['i<*', :word]
+  LIL_STRUCT_DEF_STAR_SIZE                    = 0 # '*' is ignored
+
+  LIL_STRUCT_DEF_UNRECOG_ENDIAN_FMT           = ['Y<', nil]
+  LIL_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE = ['A<', nil]
+
+  END_STRUCT_ENCODED_STR         = "\000\111\222\333\444\555\666\777\000\111\222\333\000\111\000\0320BC"
+
+  LIL_ENDIAN_STRUCT_DECODED_HASH =
+    {
+      :quad   => 18_426_034_930_503_010_560,
+      "long"  => 3_683_797_248,
+      :short  => 18_688,
+      :binary => "01011",
+      "none"  => "",
+      "bc"    => "BC",
+    }
+
+  BIG_ENDIAN_STRUCT_DECODED_HASH =
+    {
+      :quad   => 20_709_143_206_541_055,
+      "long"  => 4_821_723,
+      :short  => 73,
+      :binary => "01011",
+      "none"  => "",
+      "bc"    => "BC"
+    }
+
+  it('.new') { expect { Bistro.new }.not_to raise_error }
+  it('.new with big definition') { expect { Bistro.new(BIG_STRUCT_DEF) }.not_to raise_error }
+  it('.new with little definition') { expect { Bistro.new(LIL_STRUCT_DEF) }.not_to raise_error }
+  it('.new with big definition with *') { expect { Bistro.new(BIG_STRUCT_DEF_STAR) }.not_to raise_error }
+  it('.new with little definition with *') { expect { Bistro.new(LIL_STRUCT_DEF_STAR) }.not_to raise_error }
+  it '.new with another big endian Bistro' do
+    s = Bistro.new(BIG_STRUCT_DEF)
+    s2 = Bistro.new(s)
+    expect(s2).to eq(s)
+    expect(s2).not_to equal(s)
+  end
+
+  it '.new with another little endian Bistro' do
+    s = Bistro.new(LIL_STRUCT_DEF)
+    s2 = Bistro.new(s)
+    expect(s2).to eq(s)
+    expect(s2).not_to equal(s)
+  end
+
+  it '.new big endian Bistro with a little endian one' do
+    s = Bistro.new(BIG_STRUCT_DEF)
+    s2 = Bistro.new(LIL_STRUCT_DEF)
+    expect(s2).not_to eq(s)
+    expect(s2).not_to equal(s)
+  end
+
+  it('.new with unrecognized big e format') do
+    expect { Bistro.new(BIG_STRUCT_DEF_UNRECOG_ENDIAN_FMT) }
+      .to raise_error(RuntimeError)
+  end
+
+  it('.new with unsupported big e attribute') do
+    expect { Bistro.new(BIG_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE) }
+      .to raise_error(RuntimeError)
+  end
+
+  it('.new with invalid endian modifier') do
+    expect { Bistro.new(BIG_STRUCT_DEF_INVALID_ENDIAN_MODIFIER) }
+      .to raise_error(RuntimeError)
+  end
+
+  it('.new with unrecognized little e format') do
+    expect { Bistro.new(LIL_STRUCT_DEF_UNRECOG_ENDIAN_FMT) }
+      .to raise_error(RuntimeError)
+  end
+
+  it('.new with unsupported little e attribute') do
+    expect { Bistro.new(LIL_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE) }
+      .to raise_error(RuntimeError)
+  end
+
+  it('#definition= with definition with *') do
+    expect { Bistro.new.definition = BIG_STRUCT_DEF_STAR }
+      .not_to raise_error
+  end
+
+  it('#definition= with unrecognized big e format') do
+    expect { Bistro.new.definition = BIG_STRUCT_DEF_UNRECOG_ENDIAN_FMT }
+      .to raise_error(RuntimeError)
+  end
+  it('#definition= with unsupported big e attribute') do
+    expect { Bistro.new.definition = BIG_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE }
+      .to raise_error(RuntimeError)
+  end
+  it('#definition= with unrecognized little e format') do
+    expect { Bistro.new.definition = LIL_STRUCT_DEF_UNRECOG_ENDIAN_FMT }
+      .to raise_error(RuntimeError)
+  end
+  it('#definition= with unsupported little e attribute') do
+    expect { Bistro.new.definition = LIL_STRUCT_DEF_UNSUPPORTED_ENDIAN_ATTRIBUTE }
+      .to raise_error(RuntimeError)
+  end
+
+  it('#size') { expect(Bistro.new(BIG_STRUCT_DEF).size).to eq(BIG_STRUCT_DEF_SIZE) }
+  it('#size') { expect(Bistro.new(LIL_STRUCT_DEF).size).to eq(LIL_STRUCT_DEF_SIZE) }
+  it('#size with definition with *') { expect(Bistro.new(BIG_STRUCT_DEF_STAR).size).to eq(BIG_STRUCT_DEF_STAR_SIZE) }
+  it('#size with definition with *') { expect(Bistro.new(LIL_STRUCT_DEF_STAR).size).to eq(LIL_STRUCT_DEF_STAR_SIZE) }
+
+  it '#decode with different endian definitions' do
+    expect(Bistro.new(BIG_STRUCT_DEF).decode(END_STRUCT_ENCODED_STR))
+      .not_to equal(Bistro.new(LIL_STRUCT_DEF).decode(END_STRUCT_ENCODED_STR))
+  end
+  it '#encode with different endian definitions' do
+    big    = Bistro.new(BIG_STRUCT_DEF).encode(BIG_ENDIAN_STRUCT_DECODED_HASH)
+    little = Bistro.new(LIL_STRUCT_DEF).encode(LIL_ENDIAN_STRUCT_DECODED_HASH)
+    expect(big).not_to equal(little)
+  end
+
+  it '#decode little endian struct' do
+    expect(Bistro.new(LIL_STRUCT_DEF).decode(END_STRUCT_ENCODED_STR)).to eq(LIL_ENDIAN_STRUCT_DECODED_HASH)
+  end
+  it '#decode big endian struct' do
+    expect(Bistro.new(BIG_STRUCT_DEF).decode(END_STRUCT_ENCODED_STR)).to eq(BIG_ENDIAN_STRUCT_DECODED_HASH)
+  end
+
+  it '#== against another little endian Bistro' do
+    expect(Bistro.new(LIL_STRUCT_DEF)).to     eq(Bistro.new(LIL_STRUCT_DEF))
+  end
+  it '#== big endian against another little endian Bistro' do
+    expect(Bistro.new(BIG_STRUCT_DEF)).not_to eq(Bistro.new(LIL_STRUCT_DEF))
+  end
+  it '#== against another big endian Bistro' do
+    expect(Bistro.new(BIG_STRUCT_DEF)).to     eq(Bistro.new(BIG_STRUCT_DEF))
+  end
+
+  it '#each will iterate over definition' do
+    dup_def = []
+    Bistro.new(BIG_STRUCT_DEF).each { |field, name| dup_def << field << name }
+    expect(dup_def).to eq(BIG_STRUCT_DEF)
+  end
+
+  it '#each will iterate over definition' do
+    dup_def = []
+    Bistro.new(LIL_STRUCT_DEF).each { |field, name| dup_def << field << name }
+    expect(dup_def).to eq(LIL_STRUCT_DEF)
+  end
+
+  context "old style methods" do
+    after(:each) { Bistro.clear_structs_by_definition_cache }
+
+    it '#sizeof' do
+      expect(Bistro.sizeof(BIG_STRUCT_DEF)).to eq(BIG_STRUCT_DEF_SIZE)
+    end
+    # Do it twice for consistency reasons
+    it '#sizeof' do
+      expect(Bistro.sizeof(BIG_STRUCT_DEF)).to eq(BIG_STRUCT_DEF_SIZE)
+    end
+
+    it '#sizeof' do
+      expect(Bistro.sizeof(LIL_STRUCT_DEF)).to eq(LIL_STRUCT_DEF_SIZE)
+    end
+    # Do it twice for consistency reasons
+    it '#sizeof' do
+      expect(Bistro.sizeof(LIL_STRUCT_DEF)).to eq(LIL_STRUCT_DEF_SIZE)
+    end
+  end
+end

data/spec/gif_spec.rb

@@ -0,0 +1,44 @@
+describe Bistro do
+  let(:gif_header) do
+    Bistro.new([
+      "a3", :magic,
+      "a3", :version,
+      "S",  :width,
+      "S",  :height,
+      "a",  :flags,
+      "C",  :bg_color_index,
+      "C",  :pixel_aspect_ratio
+    ])
+  end
+
+  it "read a gif header" do
+    filename = File.join(File.dirname(__FILE__), %w(data test.gif))
+    decoded_header_hash = {
+      :magic              => "GIF",
+      :version            => "89a",
+      :width              => 16,
+      :height             => 16,
+      :flags              => "\x80",
+      :bg_color_index     => 0,
+      :pixel_aspect_ratio => 0,
+    }
+    encoded_header = gif_header.encode(decoded_header_hash)
+    header_size = gif_header.size
+    header = File.open(filename, "rb") { |f| f.read(header_size) }
+    expect(encoded_header).to eq(header)
+  end
+
+  it "write a gif header" do
+    header = gif_header.encode(
+      :magic              => "GIF",
+      :version            => "89a",
+      :width              => 16,
+      :height             => 16,
+      :flags              => "\x80",
+      :bg_color_index     => 0,
+      :pixel_aspect_ratio => 0
+    )
+
+    expect(header).to eq("GIF89a\x10\x00\x10\x00\x80\x00\x00".force_encoding("ASCII-8BIT"))
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,79 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause this
+# file to always be loaded, without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, make a
+# separate helper file that requires this one and then use it only in the specs
+# that actually need it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  # config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+    expectations.syntax = :expect
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+    mocks.syntax = :expect
+
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended.
+    mocks.verify_partial_doubles = true
+  end
+end
+
+require 'bistro'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: bistro
+version: !ruby/object:Gem::Version
+  version: 2.1.0
+platform: ruby
+authors:
+- Dev Null Productions
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-04-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Bistro is a class for dealing with BInary STRuctured data
+email:
+- devnullproductions@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- lib/bistro.rb
+- lib/bistro/version.rb
+- spec/bistro_spec.rb
+- spec/data/test.gif
+- spec/endian_spec.rb
+- spec/gif_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/DevNullProd/bistro
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Bistro is a class for dealing with BInary STRuctured data.
+test_files:
+- spec/bistro_spec.rb
+- spec/data/test.gif
+- spec/endian_spec.rb
+- spec/gif_spec.rb
+- spec/spec_helper.rb
+- ".rspec"