iostruct 0.4.0 → 0.6.0

data/lib/iostruct/pack_fmt.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module IOStruct
+  module PackFmt
+    # https://apidock.com/ruby/String/unpack
+    FMTSPEC = {
+      'C' => [1, Integer ], # 8-bit unsigned                 (uint8_t, unsigned char)
+      'S' => [2, Integer ], # 16-bit unsigned, native endian (uint16_t)
+      'I' => [4, Integer ], # 32-bit unsigned, native endian (uint32_t, unsigned int)
+      'L' => [4, Integer ], # 32-bit unsigned, native endian (unsigned long)
+      'Q' => [8, Integer ], # 64-bit unsigned, native endian (uint64_t)
+
+      'c' => [1, Integer ], # 8-bit signed                 (int8_t, signed char)
+      's' => [2, Integer ], # 16-bit signed, native endian (int16_t)
+      'i' => [4, Integer ], # 32-bit signed, native endian (int32_t, int)
+      'l' => [4, Integer ], # 32-bit signed, native endian (long)
+      'q' => [8, Integer ], # 64-bit signed, native endian (int64_t)
+
+      'n' => [2, Integer ], # 16-bit unsigned, network (big-endian) byte order
+      'N' => [4, Integer ], # 32-bit unsigned, network (big-endian) byte order
+      'v' => [2, Integer ], # 16-bit unsigned, VAX (little-endian) byte order
+      'V' => [4, Integer ], # 32-bit unsigned, VAX (little-endian) byte order
+
+      'A' => [1, String  ], # arbitrary binary string (remove trailing nulls and ASCII spaces)
+      'a' => [1, String  ], # arbitrary binary string
+      'Z' => [1, String  ], # arbitrary binary string (remove trailing nulls)
+      'H' => [1, String  ], # hex string (high nibble first)
+      'h' => [1, String  ], # hex string (low nibble first)
+
+      'D' => [8, Float   ], # double-precision, native format
+      'd' => [8, Float   ],
+      'F' => [4, Float   ], # single-precision, native format
+      'f' => [4, Float   ],
+      'E' => [8, Float   ], # double-precision, little-endian byte order
+      'e' => [4, Float   ], # single-precision, little-endian byte order
+      'G' => [8, Float   ], # double-precision, network (big-endian) byte order
+      'g' => [4, Float   ], # single-precision, network (big-endian) byte order
+
+      'x' => [1, nil     ], # skip forward one byte
+    }.freeze
+
+    private
+
+    def parse_pack_format(fmt, _names)
+      offset = 0
+      fields = []
+      fmt.scan(/([a-z])(\d*)/i).map do |type, len|
+        size, klass = FMTSPEC[type] || raise("Unknown field type #{type.inspect}")
+        len = len.empty? ? 1 : len.to_i
+        case type
+        when 'A', 'a', 'x', 'Z'
+          fields << FieldInfo.new(klass, size * len, offset) if klass
+          offset += len
+        when 'H', 'h'
+          # XXX ruby's String#unpack length for hex strings is in characters, not bytes, i.e. "x".unpack("H2") => ["78"]
+          fields << FieldInfo.new(klass, size * len / 2, offset) if klass
+          offset += len / 2
+        else
+          len.times do |_i|
+            fields << FieldInfo.new(klass, size, offset)
+            offset += size
+          end
+        end
+      end
+      [fields, offset]
+    end
+  end
+end

data/lib/iostruct/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IOStruct
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/iostruct.rb

@@ -1,99 +1,63 @@
 # frozen_string_literal: true
 
-module IOStruct
+require_relative 'iostruct/pack_fmt'
+require_relative 'iostruct/hash_fmt'
 
-  # https://apidock.com/ruby/String/unpack
-  FMTSPEC = {
-    'C' => [1, Integer ], # 8-bit unsigned (unsigned char)
-    'S' => [2, Integer ], # 16-bit unsigned, native endian (uint16_t)
-    'I' => [4, Integer ], # 32-bit unsigned, native endian (uint32_t)
-    'L' => [4, Integer ], # 32-bit unsigned, native endian (uint32_t)
-    'Q' => [8, Integer ], # 64-bit unsigned, native endian (uint64_t)
-
-    'c' => [1, Integer ], # 8-bit signed (signed char)
-    's' => [2, Integer ], # 16-bit signed, native endian (int16_t)
-    'i' => [4, Integer ], # 32-bit signed, native endian (int32_t)
-    'l' => [4, Integer ], # 32-bit signed, native endian (int32_t)
-    'q' => [8, Integer ], # 64-bit signed, native endian (int64_t)
-
-    'n' => [2, Integer ], # 16-bit unsigned, network (big-endian) byte order
-    'N' => [4, Integer ], # 32-bit unsigned, network (big-endian) byte order
-    'v' => [2, Integer ], # 16-bit unsigned, VAX (little-endian) byte order
-    'V' => [4, Integer ], # 32-bit unsigned, VAX (little-endian) byte order
-
-    'A' => [1, String  ], # arbitrary binary string (remove trailing nulls and ASCII spaces)
-    'a' => [1, String  ], # arbitrary binary string
-    'Z' => [1, String  ], # arbitrary binary string (remove trailing nulls)
-    'H' => [1, String  ], # hex string (high nibble first)
-    'h' => [1, String  ], # hex string (low nibble first)
-
-    'D' => [8, Float   ], # double-precision, native format
-    'd' => [8, Float   ],
-    'F' => [4, Float   ], # single-precision, native format
-    'f' => [4, Float   ],
-    'E' => [8, Float   ], # double-precision, little-endian byte order
-    'e' => [4, Float   ], # single-precision, little-endian byte order
-    'G' => [8, Float   ], # double-precision, network (big-endian) byte order
-    'g' => [4, Float   ], # single-precision, network (big-endian) byte order
-
-    'x' => [1, nil     ], # skip forward one byte
-  }.freeze
-
-  FieldInfo = Struct.new :type, :size, :offset
-
-  def self.new fmt, *names, inspect: :hex, **renames
-    fields, size = parse_format(fmt, names)
-    names = auto_names(fields, size) if names.empty?
-    names.map!{ |n| renames[n] || n } if renames.any?
-
-    Struct.new( *names ).tap do |x|
-      x.const_set 'FIELDS', names.zip(fields).to_h
-      x.const_set 'FORMAT', fmt
-      x.const_set 'SIZE',  size
-      x.extend ClassMethods
-      x.include InstanceMethods
-      x.include HexInspect if inspect == :hex
+module IOStruct
+  extend PackFmt
+  extend HashFmt
+
+  # rubocop:disable Lint/StructNewOverride
+  FieldInfo = Struct.new :type, :size, :offset, :count, :fmt
+  # rubocop:enable Lint/StructNewOverride
+
+  def self.new fmt = nil, *names, inspect: :hex, inspect_name_override: nil, struct_name: nil, **kwargs
+    struct_name ||= inspect_name_override # XXX inspect_name_override is deprecated
+    if fmt
+      renames = kwargs
+      finfos, size = parse_pack_format(fmt, names)
+      names = auto_names(finfos, size) if names.empty?
+      names.map! { |n| renames[n] || n } if renames.any?
+    elsif kwargs[:fields]
+      fmt, names, finfos, size = parse_hash_format(name: struct_name, **kwargs)
+    else
+      raise "IOStruct: no fmt and no :fields specified"
     end
-  end # self.new
 
-  def self.parse_format(fmt, names)
-    offset = 0
-    fields = []
-    fmt.scan(/([a-z])(\d*)/i).map do |type,len|
-      size, klass = FMTSPEC[type] || raise("Unknown field type #{type.inspect}")
-      len = len.empty? ? 1 : len.to_i
-      case type
-      when 'A', 'a', 'x', 'Z'
-        fields << FieldInfo.new(klass, size*len, offset) if klass
-        offset += len
-      when 'H', 'h'
-        # XXX ruby's String#unpack length for hex strings is in characters, not bytes, i.e. "x".unpack("H2") => ["78"]
-        fields << FieldInfo.new(klass, size*len/2, offset) if klass
-        offset += len/2
+    # if first argument to Struct.new() is a string - it creates a named struct in the Struct:: namespace
+    # convert all just for the case
+    names = names.map(&:to_sym)
+
+    Struct.new( *names ) do
+      const_set 'FIELDS', names.zip(finfos).to_h
+      const_set 'FORMAT', fmt
+      const_set 'SIZE', size
+      extend ClassMethods
+      include InstanceMethods
+      include NestedInstanceMethods if finfos.any?(&:fmt)
+      if inspect == :hex
+        include HexInspect
       else
-        len.times do |i|
-          fields << FieldInfo.new(klass, size, offset)
-          offset += size
-        end
+        include DecInspect
       end
+      define_singleton_method(:to_s) { struct_name } if struct_name
+      define_singleton_method(:name) { struct_name } if struct_name
     end
-    [fields, offset]
-  end
+  end # self.new
 
-  def self.auto_names fields, size
+  def self.auto_names(fields, _size)
     names = []
     offset = 0
     fields.each do |f|
       names << sprintf("f%x", offset).to_sym
       offset += f.size
     end
-    #raise "size mismatch: #{size} != #{offset}" if size != offset
     names
   end
 
   module ClassMethods
     # src can be IO or String, or anything that responds to :read or :unpack
-    def read src, size = nil
+    def read(src, size = nil)
       pos = nil
       size ||= const_get 'SIZE'
       data =
@@ -105,10 +69,11 @@ module IOStruct
         else
           raise "[?] don't know how to read from #{src.inspect}"
         end
-#      if data.size < size
-#        $stderr.puts "[!] #{self.to_s} want #{size} bytes, got #{data.size}"
-#      end
-      new(*data.unpack(const_get('FORMAT'))).tap{ |x| x.__offset = pos }
+      new(*data.unpack(const_get('FORMAT'))).tap { |x| x.__offset = pos }
+    end
+
+    def name
+      'struct'
     end
 
     def size
@@ -124,7 +89,7 @@ module IOStruct
     end
 
     def empty?
-      to_a.all?{ |t| t == 0 || t.nil? || t.to_s.tr("\x00","").empty? }
+      to_a.all? { |t| t == 0 || t.nil? || t.to_s.tr("\x00", "").empty? }
     end
 
     # allow initializing individual struct members by name, like:
@@ -135,7 +100,7 @@ module IOStruct
     def initialize *args
       if args.size == 1 && args.first.is_a?(Hash)
         super()
-        args.first.each do |k,v|
+        args.first.each do |k, v|
           send "#{k}=", v
         end
       else
@@ -144,35 +109,94 @@ module IOStruct
     end
   end # InstanceMethods
 
-  module HexInspect
-    def to_s
-      "<#{self.class.to_s} " + to_h.map do |k, v|
-        if v.is_a?(Integer) && v > 9
-          "#{k}=0x%x" % v
-        else
-          "#{k}=#{v.inspect}"
+  # initialize nested structures / arrays
+  module NestedInstanceMethods
+    def initialize *args
+      super
+      self.class::FIELDS.each do |k, v|
+        next unless v.fmt
+
+        if (value = self[k])
+          self[k] = v.fmt.is_a?(String) ? value.unpack(v.fmt) : v.fmt.read(value)
         end
-      end.join(' ') + ">"
+      end
+    end
+
+    def pack
+      values = self.class::FIELDS.map do |k, v|
+        value = self[k]
+        next value unless v&.fmt && value
+
+        # Reverse the unpacking done in initialize
+        v.fmt.is_a?(String) ? value.pack(v.fmt) : value.pack
+      end
+      values.pack self.class.const_get('FORMAT')
     end
+  end
+
+  module InspectBase
+    INT_MASKS = { 1 => 0xff, 2 => 0xffff, 4 => 0xffffffff, 8 => 0xffffffffffffffff }.freeze
 
+    # rubocop:disable Lint/DuplicateBranch
     def to_table
-      @fmtstr_tbl = "<#{self.class.to_s} " + self.class.const_get('FIELDS').map do |name, f|
-        fmt =
-          case 
+      values = to_a
+      "<#{self.class.name} " + self.class::FIELDS.map.with_index do |el, idx|
+        v = values[idx]
+        fname, f = el
+
+        "#{fname}=" +
+          case
+          when f.nil? # unknown field type
+            v.inspect
           when f.type == Integer
-            "%#{f.size*2}x"
+            v ||= 0 # avoid "`sprintf': can't convert nil into Integer" error
+            format_integer(v, f.size, fname)
           when f.type == Float
-            "%8.3f"
+            v ||= 0 # avoid "`sprintf': can't convert nil into Float" error
+            "%8.3f" % v
           else
-            "%s"
+            v.inspect
           end
-        "#{name}=#{fmt}"
       end.join(' ') + ">"
-      sprintf @fmtstr_tbl, *to_a.map{ |v| v.is_a?(String) ? v.inspect : (v||0) } # "||0" to avoid "`sprintf': can't convert nil into Integer" error
+    end
+    # rubocop:enable Lint/DuplicateBranch
+  end
+
+  module DecInspect
+    include InspectBase
+
+    DEC_FMTS = { 1 => "%4d", 2 => "%6d", 4 => "%11d", 8 => "%20d" }.freeze
+
+    def format_integer(value, size, fname)
+      fmt = DEC_FMTS[size] || raise("Unsupported Integer size #{size} for field #{fname}")
+      fmt % value
+    end
+  end
+
+  module HexInspect
+    include InspectBase
+
+    HEX_FMTS = { 1 => "%2x", 2 => "%4x", 4 => "%8x", 8 => "%16x" }.freeze
+
+    def to_s
+      "<#{self.class.name} " + to_h.map do |k, v|
+        if v.is_a?(Integer) && v > 9
+          "#{k}=0x%x" % v
+        else
+          "#{k}=#{v.inspect}"
+        end
+      end.join(' ') + ">"
     end
 
     def inspect
       to_s
     end
+
+    # display as unsigned, because signed %x looks ugly: "..f" for -1
+    def format_integer(value, size, fname)
+      fmt  = HEX_FMTS[size]  || raise("Unsupported Integer size #{size} for field #{fname}")
+      mask = INT_MASKS[size] || raise("Unsupported Integer size #{size} for field #{fname}")
+      fmt % (value & mask)
+    end
   end
 end # IOStruct

data/spec/.rubocop.yml

@@ -0,0 +1,27 @@
+inherit_from: ../.rubocop.yml
+
+
+Layout/SpaceInsideParens:
+  Enabled: false
+
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/ExampleWording:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false

data/spec/hash_fmt_spec.rb

@@ -0,0 +1,215 @@
+require 'spec_helper'
+require 'stringio'
+
+describe IOStruct do
+  describe ".get_type_size" do
+    it "returns size for known types" do
+      expect(described_class.get_type_size('int')).to eq 4
+      expect(described_class.get_type_size('char')).to eq 1
+      expect(described_class.get_type_size('short')).to eq 2
+      expect(described_class.get_type_size('long long')).to eq 8
+      expect(described_class.get_type_size('double')).to eq 8
+      expect(described_class.get_type_size('float')).to eq 4
+    end
+
+    it "works with symbol input" do
+      expect(described_class.get_type_size(:int)).to eq 4
+    end
+
+    it "returns nil for unknown types" do
+      expect(described_class.get_type_size('unknown')).to be_nil
+    end
+  end
+
+  describe "hash format ctor" do
+    it "works" do
+      klass = described_class.new(
+        fields: {
+          x: "int",
+          y: :int,
+          z: { type: :int },
+        },
+        struct_name: 'Point'
+      )
+      expect(klass.new.inspect).to match(/<Point x=nil y=nil z=nil>/)
+      expect(klass.size).to eq(12)
+      expect(klass::SIZE).to eq(12)
+    end
+
+    it "respects :name" do
+      klass = described_class.new(
+        fields: {
+          x: "int",
+          y: :int,
+          z: { type: :int },
+        },
+        struct_name: 'Point'
+      )
+      expect(klass.new.inspect).to match(/<Point x=nil y=nil z=nil>/)
+    end
+
+    it "respects :offset" do
+      klass = described_class.new(
+        struct_name: 'Point',
+        fields: {
+          x: "int",
+          y: :int,
+          z: { type: :int, offset: 0x10 },
+        }
+      )
+      expect(klass.new.inspect).to match(/<Point x=nil y=nil z=nil>/)
+      expect(klass.size).to eq(0x14)
+
+      obj = klass.read((0..0x20).to_a.pack('i*'))
+      expect(obj.x).to eq(0)
+      expect(obj.y).to eq(1)
+      expect(obj.z).to eq(4)
+    end
+
+    context 'when two fields have same offset' do
+      it 'fails' do
+        expect do
+          described_class.new(
+            struct_name: 'Point',
+            fields: {
+              x: { type: :int, offset: 0 },
+              y: { type: :char, offset: 0 },
+            }
+          )
+        end.to raise_error(RuntimeError)
+      end
+    end
+
+    it "can override size" do
+      klass = described_class.new(
+        fields: {
+          x: "int",
+          y: :int,
+          z: { type: 'int' },
+        },
+        size: 0x100
+      )
+      expect(klass.size).to eq(0x100)
+    end
+
+    it "supports arrays" do
+      klass = described_class.new(
+        fields: {
+          x: "int",
+          a: { type: 'int', count: 3 },
+          y: :int,
+        },
+      )
+      expect(klass.size).to eq(4 * 5)
+
+      v = klass.read([1, 2, 3, 4, 5, 6, 7].pack('i*'))
+
+      expect(v.x).to eq(1)
+      expect(v.a).to eq([2, 3, 4])
+      expect(v.y).to eq(5)
+    end
+
+    it "supports nesting" do
+      point = described_class.new( fields: { x: "int", y: :int } )
+      rect = described_class.new(
+        struct_name: 'Rect',
+        fields: {
+          topLeft: point,
+          bottomRight: point,
+        }
+      )
+      expect(rect.size).to eq(16)
+
+      r = rect.read([10, 20, 100, 200].pack('i*'))
+      expect(r.topLeft).to be_instance_of(point)
+      expect(r.bottomRight).to be_instance_of(point)
+      expect(r.topLeft.x).to eq(10)
+      expect(r.topLeft.y).to eq(20)
+      expect(r.bottomRight.x).to eq(100)
+      expect(r.bottomRight.y).to eq(200)
+    end
+
+    it "packs nested structs" do
+      point = described_class.new(fields: { x: "int", y: :int })
+      rect = described_class.new(fields: { topLeft: point, bottomRight: point })
+
+      r = rect.read([10, 20, 100, 200].pack('i*'))
+      packed = r.pack
+      reparsed = rect.read(packed)
+
+      expect(reparsed.topLeft.x).to eq 10
+      expect(reparsed.topLeft.y).to eq 20
+      expect(reparsed.bottomRight.x).to eq 100
+      expect(reparsed.bottomRight.y).to eq 200
+    end
+
+    it "packs arrays" do
+      klass = described_class.new(
+        fields: {
+          x: "int",
+          a: { type: 'int', count: 3 },
+          y: :int,
+        }
+      )
+
+      v = klass.read([1, 2, 3, 4, 5].pack('i*'))
+      packed = v.pack
+      reparsed = klass.read(packed)
+
+      expect(reparsed.x).to eq 1
+      expect(reparsed.a).to eq [2, 3, 4]
+      expect(reparsed.y).to eq 5
+    end
+
+    context "error handling" do
+      it "raises on unknown field type" do
+        expect do
+          described_class.new(fields: { x: "unknown_type" })
+        end.to raise_error(/unknown field type/)
+      end
+
+      it "raises on invalid type format" do
+        expect do
+          described_class.new(fields: { x: 12345 })
+        end.to raise_error(/unexpected field desc type/)
+      end
+
+      it "raises when forced size is smaller than actual" do
+        expect do
+          described_class.new(
+            fields: { x: "int", y: "int", z: "int" },
+            size: 4
+          )
+        end.to raise_error(/actual struct size .* is greater than forced size/)
+      end
+    end
+
+    context "C type aliases" do
+      it "supports uint types" do
+        klass = described_class.new(fields: {
+                                      a: 'uint8_t',
+                                      b: 'uint16_t',
+                                      c: 'uint32_t',
+                                      d: 'uint64_t'
+                                    })
+        expect(klass.size).to eq(1 + 2 + 4 + 8)
+      end
+
+      it "supports int types" do
+        klass = described_class.new(fields: {
+                                      a: 'int8_t',
+                                      b: 'int16_t',
+                                      c: 'int32_t',
+                                      d: 'int64_t'
+                                    })
+        expect(klass.size).to eq(1 + 2 + 4 + 8)
+      end
+
+      it "supports _BYTE type" do
+        klass = described_class.new(fields: { a: '_BYTE' })
+        expect(klass.size).to eq 1
+        expect(klass.read("\xff").a).to eq 255 # unsigned
+      end
+    end
+  end
+end