iostruct 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0376aab4653f3f1fb656d82f679346bd1d04c6d8f80e17540a4a7fbb3bc470d7
-  data.tar.gz: 211894d68015bc52658e8e818296a42c115bdeda8cfa2cb6525cadb1e9554e9b
+  metadata.gz: a36ab3a3a2de5e2cb4f94175231aa664be8cee2c5361d83cc2f62def71f2b067
+  data.tar.gz: 2604c514757df2287d4652c0929ebfc09b1d54cd281599b6e7f52fd2d7f270d8
 SHA512:
-  metadata.gz: 79edc6088c3258506085cf22aee37e75386bab8309c478786ec3022f3895f34a4b05490640bca22db56b78242b500d7030d3fc6b141a24aa0f9cfc1681baef7d
-  data.tar.gz: 36ddc86813c0c0fc92874025fbe37f755a8f1cef22533949b101428b50ca2a0369aae9beddfe99a4b00d71c0db5985ec4f89b5beddefcc262ea6c91dfd2787b7
+  metadata.gz: e99bb3cdd28c0f1283332470cf1e88aca1c425d79545a28d448bde831630e272dca6a5eda4d88ea869482e21c9d7e2adf80d61ee62661fa4d2a09420bad82f36
+  data.tar.gz: 4bf4896671e0a04675210468855b5efa5ec0df22378ac4bad1bef3a193080be8f908fc571bdcc3325c1dc4b7d5d50c10dd98ac213376a5f1d4ed396fdd85c247

data/.rubocop.yml

@@ -0,0 +1,68 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
+
+AllCops:
+  NewCops: enable
+
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+
+Layout/LineLength:
+  Max: 140
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: false
+
+Layout/SpaceInsideParens:
+  Enabled: false
+
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/BlockLength:
+  Max: 50
+
+Metrics/MethodLength:
+  Max: 55
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 18
+
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/CHANGELOG.md

@@ -1,3 +1,47 @@
+# 0.6.0
+
+- added alternative hash-based struct definition with C type names:
+
+   ```ruby
+   Point = IOStruct.new(
+     struct_name: 'Point',
+     fields: {
+       x: 'int',
+       y: :int,
+       z: { type: :int, offset: 0x10 },  # explicit offset
+     }
+   )
+
+   # supports nested structs
+   Rect = IOStruct.new(fields: { topLeft: Point, bottomRight: Point })
+
+   # supports arrays
+   IOStruct.new(fields: { values: { type: 'int', count: 10 } })
+   ```
+
+- added `pack` support for nested structs and arrays:
+
+   ```ruby
+   r = Rect.read(data)
+   r.pack  # now works!
+   ```
+
+- added `to_table` method with decimal formatting (`:inspect => :dec`)
+- added `get_type_size` helper method
+- deprecated `inspect_name_override` in favor of `struct_name`
+- fixed `to_table` handling of unknown field types
+- fixed `_BYTE` type alias (was incorrectly mapped to both signed and unsigned)
+- fixed operator precedence bug in `format_integer` methods
+
+# 0.5.0
+
+ - added `inspect_name_override` constructor param, useful for dynamic declarations:
+
+    ```ruby
+    IOStruct.new("NN").new.inspect                                 # "<#<Class:0x000000011c45fa20> f0=nil f4=nil>"
+    IOStruct.new("NN", inspect_name_override: "Point").new.inspect # "<Point f0=nil f4=nil>"
+    ```
+
 # 0.4.0
 
  - added `size` class method that returns SIZE constant

data/Gemfile

@@ -1,4 +1,13 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in iostruct.gemspec
 gemspec
+
+group :development, :test do
+  gem 'rspec', require: false
+  gem 'rubocop', require: false
+  gem 'rubocop-rake', require: false
+  gem 'rubocop-rspec', require: false
+end

data/Gemfile.lock

@@ -1,28 +1,65 @@
 PATH
   remote: .
   specs:
-    iostruct (0.3.0)
+    iostruct (0.6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.5.1)
-    rake (13.2.1)
-    rspec (3.13.0)
+    ast (2.4.3)
+    diff-lcs (1.6.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.8.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.0)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.1)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
+    rspec-support (3.13.6)
+    rubocop (1.84.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
+  arm64-darwin-24
   ruby
 
 DEPENDENCIES
@@ -30,6 +67,9 @@ DEPENDENCIES
   iostruct!
   rake
   rspec
+  rubocop
+  rubocop-rake
+  rubocop-rspec
 
 BUNDLED WITH
-   2.5.6
+   2.6.9

data/README.md

@@ -1,24 +1,261 @@
-# Iostruct
+# IOStruct
 
-TODO: Write a gem description
+A Ruby Struct that can read/write itself from/to IO-like objects. Perfect for parsing binary file formats, network protocols, and other structured binary data.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'iostruct'
+```ruby
+gem 'iostruct'
+```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install iostruct
+```bash
+$ gem install iostruct
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic Usage with Pack Format
+
+Define structs using Ruby's [pack/unpack format strings](https://ruby-doc.org/core/String.html#method-i-unpack):
+
+```ruby
+require 'iostruct'
+
+# Define a struct with two 32-bit unsigned integers
+Point = IOStruct.new('LL', :x, :y)
+
+# Read from binary data
+data = [100, 200].pack('LL')
+point = Point.read(data)
+point.x  # => 100
+point.y  # => 200
+
+# Write back to binary
+point.pack  # => "\x64\x00\x00\x00\xC8\x00\x00\x00"
+```
+
+### Hash-Based Definition with C Types
+
+For more readable code, define structs using C-style type names:
+
+```ruby
+Point = IOStruct.new(
+  struct_name: 'Point',
+  fields: {
+    x: 'int',
+    y: 'int',
+    z: 'int',
+  }
+)
+
+point = Point.read(binary_data)
+point.inspect  # => "<Point x=0x64 y=0xc8 z=0x0>"
+```
+
+#### Supported C Types
+
+| Type | Aliases | Size |
+|------|---------|------|
+| `uint8_t` | `unsigned char`, `_BYTE` | 1 |
+| `uint16_t` | `unsigned short` | 2 |
+| `uint32_t` | `unsigned int`, `unsigned` | 4 |
+| `uint64_t` | `unsigned long long` | 8 |
+| `int8_t` | `char`, `signed char` | 1 |
+| `int16_t` | `short`, `signed short` | 2 |
+| `int32_t` | `int`, `signed int`, `signed` | 4 |
+| `int64_t` | `long long`, `signed long long` | 8 |
+| `float` | | 4 |
+| `double` | | 8 |
+
+### Reading from IO or String
+
+```ruby
+Header = IOStruct.new('L S S', :magic, :version, :flags)
+
+# Read from a File
+File.open('binary_file', 'rb') do |f|
+  header = Header.read(f)
+  puts header.magic
+end
+
+# Read from a String
+header = Header.read("\x7fELF\x01\x00\x00\x00")
+
+# Track file position with __offset
+io = StringIO.new(data)
+record = MyStruct.read(io)
+record.__offset  # => position where the record was read from
+```
+
+### Explicit Field Offsets
+
+Specify exact byte offsets for fields (useful for structs with padding or gaps):
+
+```ruby
+MyStruct = IOStruct.new(
+  fields: {
+    magic: 'uint32_t',
+    flags: { type: 'uint16_t', offset: 0x10 },  # starts at byte 16
+    data:  { type: 'uint32_t', offset: 0x20 },  # starts at byte 32
+  }
+)
+```
+
+### Arrays
+
+Define fixed-size arrays within structs:
+
+```ruby
+Matrix = IOStruct.new(
+  fields: {
+    rows: 'int',
+    cols: 'int',
+    data: { type: 'float', count: 16 },  # 16-element float array
+  }
+)
+
+m = Matrix.read(binary_data)
+m.data  # => [1.0, 2.0, 3.0, ...]
+m.pack  # serializes back to binary
+```
+
+### Nested Structs
+
+Compose complex structures from simpler ones:
+
+```ruby
+Point = IOStruct.new(fields: { x: 'int', y: 'int' })
+
+Rect = IOStruct.new(
+  struct_name: 'Rect',
+  fields: {
+    top_left: Point,
+    bottom_right: Point,
+  }
+)
+
+rect = Rect.read([0, 0, 100, 100].pack('i*'))
+rect.top_left.x       # => 0
+rect.bottom_right.x   # => 100
+rect.pack             # serializes entire structure including nested structs
+```
+
+### Inspect Modes
+
+Choose between hexadecimal (default) or decimal display:
+
+```ruby
+# Hex display (default)
+HexStruct = IOStruct.new('L L', :a, :b, inspect: :hex)
+HexStruct.new(a: 255, b: 256).inspect
+# => "<struct a=0xff b=0x100>"
+
+# Decimal display
+DecStruct = IOStruct.new('L L', :a, :b, inspect: :dec)
+DecStruct.new(a: 255, b: 256).inspect
+# => "#<struct DecStruct a=255, b=256>"
+
+# Table format for aligned output
+struct.to_table
+# => "<struct a=  ff b= 100>"
+```
+
+### Auto-Generated Field Names
+
+If you don't specify field names, they're generated based on byte offset:
+
+```ruby
+s = IOStruct.new('C S L')
+s.members  # => [:f0, :f1, :f3]  (offsets 0, 1, 3)
+```
+
+### Field Renaming
+
+Rename auto-generated or explicit field names:
+
+```ruby
+# Rename auto-generated names
+IOStruct.new('C S L', f0: :byte_val, f3: :long_val)
+
+# Rename explicit names
+IOStruct.new('C S L', :a, :b, :c, a: :first, c: :last)
+```
+
+## API Reference
+
+### Class Methods
+
+| Method | Description |
+|--------|-------------|
+| `IOStruct.new(fmt, *names, **options)` | Create a new struct class with pack format |
+| `IOStruct.new(fields:, **options)` | Create a new struct class with hash definition |
+| `IOStruct.get_type_size(typename)` | Get byte size for a C type name |
+| `MyStruct.read(io_or_string)` | Read and parse binary data |
+| `MyStruct.size` | Return struct size in bytes |
+| `MyStruct::SIZE` | Struct size constant |
+| `MyStruct::FORMAT` | Pack format string |
+| `MyStruct::FIELDS` | Hash of field names to FieldInfo |
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `#pack` | Serialize to binary string |
+| `#empty?` | True if all fields are zero/nil/empty |
+| `#to_table` | Formatted string with aligned values |
+| `#__offset` | File position where struct was read (nil if from string) |
+
+### Constructor Options
+
+| Option | Description |
+|--------|-------------|
+| `struct_name:` | Custom name for inspect output |
+| `inspect:` | `:hex` (default) or `:dec` for display format |
+| `size:` | Override calculated struct size |
+| `fields:` | Hash defining fields (for hash-based definition) |
+
+## Examples
+
+### Parsing a BMP File Header
+
+```ruby
+BMPHeader = IOStruct.new(
+  struct_name: 'BMPHeader',
+  fields: {
+    magic:      { type: 'uint16_t' },
+    file_size:  { type: 'uint32_t' },
+    reserved:   { type: 'uint32_t' },
+    data_offset: { type: 'uint32_t' },
+  }
+)
+
+File.open('image.bmp', 'rb') do |f|
+  header = BMPHeader.read(f)
+  puts "File size: #{header.file_size} bytes"
+  puts "Pixel data starts at: #{header.data_offset}"
+end
+```
+
+### Network Protocol Packet
+
+```ruby
+Packet = IOStruct.new('n n N', :src_port, :dst_port, :sequence,
+  struct_name: 'TCPHeader'
+)
+
+# Big-endian format for network byte order
+packet = Packet.read(socket.read(8))
+```
 
 ## Contributing
 
@@ -27,3 +264,7 @@ TODO: Write usage instructions here
 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
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt) for details.

data/Rakefile

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
 
 desc "run specs"
 RSpec::Core::RakeTask.new
 
-task :default => :spec
+task default: :spec

data/iostruct.gemspec

@@ -1,5 +1,7 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+require 'English'
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'iostruct/version'
 
@@ -9,16 +11,13 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors  = ["Andrey \"Zed\" Zaikin"]
-  s.date     = "2013-01-08"
   s.email    = "zed.0xff@gmail.com"
-  s.files    = `git ls-files`.split($/)
+  s.files    = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   s.homepage = "http://github.com/zed-0xff/iostruct"
   s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
   s.summary  = "A Struct that can read/write itself from/to IO-like objects"
 
-  s.add_development_dependency "bundler"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "rspec"
-end
+  s.require_paths = ["lib"]
 
+  s.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/iostruct/hash_fmt.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module IOStruct
+  module HashFmt
+    KNOWN_FIELD_TYPES_REVERSED = {
+      'C' => ['uint8_t',  'unsigned char', '_BYTE'],
+      'S' => ['uint16_t', 'unsigned short'],
+      'I' => ['uint32_t', 'unsigned', 'unsigned int'],
+      'L' => ['unsigned long'],
+      'Q' => ['uint64_t', 'unsigned long long'],
+
+      'c' => ['int8_t',  'char', 'signed char'],
+      's' => ['int16_t', 'short', 'signed short'],
+      'i' => ['int32_t', 'int', 'signed', 'signed int'],
+      'l' => ['long',    'signed long'],
+      'q' => ['int64_t', 'long long', 'signed long long'],
+
+      'd' => ['double'],
+      'f' => ['float'],
+    }.freeze
+
+    KNOWN_FIELD_TYPES = KNOWN_FIELD_TYPES_REVERSED.map { |t, a| a.map { |v| [v, t] } }.flatten.each_slice(2).to_h
+
+    # for external use
+    def get_type_size(typename)
+      type_code = KNOWN_FIELD_TYPES[typename.to_s]
+      f_size, = PackFmt::FMTSPEC[type_code]
+      f_size
+    end
+
+    private
+
+    def parse_hash_format(fields:, size: nil, name: nil)
+      struct_name = name
+      offset = 0
+      names = []
+      fmt_arr = []
+      finfos = fields.map do |f_name, type|
+        f_offset = offset
+        f_count = 1
+        klass = f_fmt = type_code = nil
+
+        if type.is_a?(Hash)
+          f_offset = type.fetch(:offset, offset)
+          if f_offset > offset
+            fmt_arr << "x#{f_offset - offset}"
+          elsif f_offset < offset
+            raise "#{struct_name}: field #{f_name.inspect} overlaps previous field"
+          end
+          f_count = type.fetch(:count, f_count)
+          type = type[:type]
+        end
+
+        case type
+        when String
+          # noop
+        when Symbol
+          type = type.to_s
+        when Class
+          klass = type
+          f_size = klass.size
+          f_fmt = klass
+          type_code = "a#{f_size}"
+        else
+          raise "#{f_name}: unexpected field desc type #{type.class}"
+        end
+
+        unless type_code
+          type_code = KNOWN_FIELD_TYPES[type]
+          raise "#{f_name}: unknown field type #{type.inspect}" unless type_code
+
+          f_size, klass = PackFmt::FMTSPEC[type_code] || raise("Unknown field type code #{type_code.inspect}")
+        end
+
+        if f_count != 1
+          f_fmt = "#{type_code}#{f_count}"
+          f_size *= f_count
+          type_code = "a#{f_size}"
+        end
+
+        offset = f_offset + f_size
+        fmt_arr << type_code
+        names << f_name
+
+        FieldInfo.new(klass, f_size, f_offset, f_count, f_fmt)
+      end
+      raise "#{struct_name}: actual struct size #{offset} is greater than forced size #{size}: #{fields.inspect}" if size && offset > size
+
+      [fmt_arr.join, names, finfos, size || offset]
+    end
+  end
+end