ffi-bitfield 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50775cc156bce79d4d20153303484ba80d19d23707d5413ea2557676260e8b38
-  data.tar.gz: 941e057d7cd548da1fd133f81143e573d7795c060d7678334c74cd1ed7cdaa31
+  metadata.gz: 7a7ec1a2c9da825cb036e42ad7b0e3745704e5bb9fba89394993c3043da9e521
+  data.tar.gz: 10d2ecd8efcb3312228d684b0e15ccc32654de39dc4399065267ad5866e2d0cb
 SHA512:
-  metadata.gz: 7329ad0a6bf66f580af0fdbbc3219774a53e7624a78e8e3891562150444282c0b2aae26b5eb4382edf8f67e27e66224aaf32592757f6e813105ab432a5e646a5
-  data.tar.gz: 3e4bb498d57114b6f9ccaf140d5789239609ff402f3be888d419fefa66957547659f1d5ab8577439f9fb98ad89fa6d56869f30a985b04486bc9bc90799c9b82a
+  metadata.gz: 688c1d48d37dc1d9f619af9da8ee5d8ac5546d8b6dcab618db5df90d603c73a4c80aac58dfc91b385da9f4e8ea90f2442e47d73441564f5e75e579d7b2636b4c
+  data.tar.gz: 230ed815df33fe597fdf4fa9dc61afd6b69fa625de30826cb795db58aeebeb31ffecf68ebceed6b764450169dee91949ea86006ee4238d6e058e93ad84ed0b9d

data/README.md

@@ -70,6 +70,42 @@ s[:y] = 1
 p s[:a] # 64
 ```
 
+### Inspecting Bit Fields
+
+You can use the `bit_field_members` method to get a hash of bit fields grouped by parent field:
+
+```ruby
+class Flags < FFI::BitStruct
+  layout \
+    :value, :uint8
+
+  bit_fields :value,
+    :read,    1,
+    :write,   1,
+    :execute, 1,
+    :unused,  5
+end
+
+p Flags.bit_field_members
+# => {:value=>[:read, :write, :execute, :unused]}
+```
+
+For more detailed information, you can use the `bit_field_layout` method:
+
+```ruby
+p Flags.bit_field_layout
+# => {
+#      :value => {
+#        :read    => { :start => 0, :width => 1 },
+#        :write   => { :start => 1, :width => 1 },
+#        :execute => { :start => 2, :width => 1 },
+#        :unused  => { :start => 3, :width => 5 }
+#      }
+#    }
+```
+
+These methods are useful for custom pretty printing or introspection of your bit struct classes.
+
 ### Loading
 
 ```ruby

data/lib/ffi/bit_field/class_methods.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module FFI
+  module BitField
+    # ClassMethods provides methods for defining bit field layouts.
+    # This module is extended by BitStruct and ManagedBitStruct classes.
+    module ClassMethods
+      # Returns a hash of bit fields grouped by parent field.
+      #
+      # @return [Hash] A hash where keys are parent field names and values are arrays of bit field names
+      #
+      # @example Get bit field members in a struct
+      #   class Flags < FFI::BitStruct
+      #     layout \
+      #       :value, :uint8
+      #
+      #     bit_fields :value,
+      #       :read,    1,
+      #       :write,   1,
+      #       :execute, 1,
+      #       :unused,  5
+      #   end
+      #
+      #   Flags.bit_field_members  # => {:value => [:read, :write, :execute, :unused]}
+      def bit_field_members
+        return {} unless instance_variable_defined?(:@bit_field_hash_table)
+
+        result = {}
+        @bit_field_hash_table.each do |field_name, info|
+          parent_name = info[0]
+          result[parent_name] ||= []
+          result[parent_name] << field_name
+        end
+        result
+      end
+
+      # Returns a hash of bit fields with detailed layout information.
+      #
+      # @return [Hash] A hash where keys are parent field names and values are hashes of bit field details
+      #
+      # @example Get detailed bit field layout in a struct
+      #   class Flags < FFI::BitStruct
+      #     layout \
+      #       :value, :uint8
+      #
+      #     bit_fields :value,
+      #       :read,    1,
+      #       :write,   1,
+      #       :execute, 1,
+      #       :unused,  5
+      #   end
+      #
+      #   Flags.bit_field_layout
+      #   # => {
+      #   #      :value => {
+      #   #        :read    => { :start => 0, :width => 1 },
+      #   #        :write   => { :start => 1, :width => 1 },
+      #   #        :execute => { :start => 2, :width => 1 },
+      #   #        :unused  => { :start => 3, :width => 5 }
+      #   #      }
+      #   #    }
+      def bit_field_layout
+        return {} unless instance_variable_defined?(:@bit_field_hash_table)
+
+        result = {}
+        @bit_field_hash_table.each do |field_name, info|
+          parent_name, start, width = info
+          result[parent_name] ||= {}
+          result[parent_name][field_name] = { start: start, width: width }
+        end
+        result
+      end
+
+      # Returns a hash of bit fields with their bit offsets, grouped by parent field.
+      #
+      # @return [Hash] A hash where keys are parent field names and values are arrays of [bit_field_name, bit_offset] pairs
+      #
+      # @example Get bit field offsets in a struct
+      #   class Flags < FFI::BitStruct
+      #     layout \
+      #       :value, :uint8
+      #
+      #     bit_fields :value,
+      #       :read,    1,
+      #       :write,   1,
+      #       :execute, 1,
+      #       :unused,  5
+      #   end
+      #
+      #   Flags.bit_field_offsets
+      #   # => {
+      #   #      :value => [[:read, 0], [:write, 1], [:execute, 2], [:unused, 3]]
+      #   #    }
+      def bit_field_offsets
+        return {} unless instance_variable_defined?(:@bit_field_hash_table)
+
+        result = {}
+
+        # Get byte offsets of parent fields
+        field_offsets = offsets.to_h
+
+        # Process each bit field
+        @bit_field_hash_table.each do |field_name, info|
+          parent_name, start, _width = info
+
+          # Get byte offset of parent field
+          parent_offset = field_offsets[parent_name]
+          next unless parent_offset
+
+          # Convert byte offset to bit offset and add bit field's start position
+          bit_offset = parent_offset * 8 + start
+
+          # Add to result
+          result[parent_name] ||= []
+          result[parent_name] << [field_name, bit_offset]
+        end
+
+        # Return result
+        result
+      end
+
+      # Defines bit fields within a parent field.
+      #
+      # @param [Array] layout_args An array where the first element is the parent field name,
+      #   followed by alternating field name and bit width pairs
+      # @return [Symbol] parent_name The name of the parent field
+      #
+      # @example Define bit fields in an 8-bit integer
+      #   bit_fields :flags,
+      #     :read,    1,  # 1 bit for read permission
+      #     :write,   1,  # 1 bit for write permission
+      #     :execute, 1,  # 1 bit for execute permission
+      #     :unused,  5   # 5 unused bits
+      #
+      # @note The total bit width should not exceed the size of the parent field.
+      #   For example, a :uint8 field can hold at most 8 bits.
+      def bit_fields(*layout_args)
+        # The reason for using class instance variable here instead of class variable
+        # is not because class instance variables are clean,
+        # but because sub-class of FFI::Struct cannot be inherited again.
+        @bit_field_hash_table = {} unless instance_variable_defined?(:@bit_field_hash_table)
+
+        parent_name = layout_args.shift.to_sym
+        member_names = []
+        widths = []
+        layout_args.each_slice(2) do |name, width|
+          member_names << name.to_sym
+          widths << width.to_i
+        end
+        starts = widths.inject([0]) do |result, width|
+          result << (result.last + width)
+        end
+        member_names.zip(starts, widths).each do |name, start, width|
+          @bit_field_hash_table[name] = [parent_name, start, width]
+        end
+
+        parent_name
+      end
+      alias bit_field bit_fields
+    end
+  end
+end

data/lib/ffi/bit_field/{property.rb → instance_methods.rb}

@@ -2,9 +2,35 @@
 
 module FFI
   module BitField
-    # Property provides methods for reading and writing bit field values.
+    # InstanceMethods provides methods for reading and writing bit field values.
     # This module is included in BitStruct and ManagedBitStruct classes.
-    module Property
+    module InstanceMethods
+      # Returns a hash of bit fields grouped by parent field.
+      # Instance method version of the class method with the same name.
+      #
+      # @return [Hash] A hash where keys are parent field names and values are arrays of bit field names
+      #
+      # @example Get bit field members in a struct instance
+      #   flags = Flags.new
+      #   flags.bit_field_members  # => {:value => [:read, :write, :execute, :unused]}
+      def bit_field_members
+        self.class.bit_field_members
+      end
+
+      # Returns a hash of bit fields with their bit offsets, grouped by parent field.
+      #
+      # @return [Hash] A hash where keys are parent field names and values are arrays of [bit_field_name, bit_offset] pairs
+      #
+      # @example Get bit field offsets in a struct instance
+      #   flags = Flags.new
+      #   flags.bit_field_offsets
+      #   # => {
+      #   #      :value => [[:read, 0], [:write, 1], [:execute, 2], [:unused, 3]]
+      #   #    }
+      def bit_field_offsets
+        self.class.bit_field_offsets
+      end
+
       # Reads a value from a bit field or regular field.
       #
       # @param [Symbol] member_name The name of the field to read

data/lib/ffi/bit_field/version.rb

@@ -3,6 +3,6 @@
 module FFI
   module BitField
     # Current version of the ffi-bitfield gem.
-    VERSION = '0.0.8'
+    VERSION = '0.0.10'
   end
 end

data/lib/ffi/bit_struct.rb

@@ -2,8 +2,8 @@
 
 require 'ffi'
 require_relative 'bit_field/version'
-require_relative 'bit_field/layout'
-require_relative 'bit_field/property'
+require_relative 'bit_field/class_methods'
+require_relative 'bit_field/instance_methods'
 
 module FFI
   # Subclass of FFI::Struct that supports bit fields.
@@ -29,13 +29,13 @@ module FFI
     # [] is defined in FFI::Struct
     alias get_member_value []
     alias set_member_value []=
-    extend BitField::Layout
-    # The Property module included in the FFI::ManagedBitStruct class is
+    extend BitField::ClassMethods
+    # The InstanceMethods module included in the FFI::ManagedBitStruct class is
     # * behind the FFI::ManagedBitStruct class, but is
     # * in FRONT of the FFI::Struct class.
     # `MStruct.ancestors`
-    # # => [MStruct, FFI::ManagedBitStruct, FFI::BitField::Property, FFI::ManagedStruct, FFI::Struct...]
+    # # => [MStruct, FFI::ManagedBitStruct, FFI::BitField::InstanceMethods, FFI::ManagedStruct, FFI::Struct...]
     # So you do not need to use `prepend` instead of `include`.
-    include BitField::Property
+    include BitField::InstanceMethods
   end
 end

data/lib/ffi/managed_bit_struct.rb

@@ -2,8 +2,8 @@
 
 require 'ffi'
 require_relative 'bit_field/version'
-require_relative 'bit_field/layout'
-require_relative 'bit_field/property'
+require_relative 'bit_field/class_methods'
+require_relative 'bit_field/instance_methods'
 
 module FFI
   # Subclass of FFI::ManagedStruct that supports bit fields.
@@ -32,13 +32,13 @@ module FFI
     # [] is defined in FFI::Struct
     alias get_member_value []
     alias set_member_value []=
-    extend BitField::Layout
-    # The Property module included in the FFI::BitStruct class is
+    extend BitField::ClassMethods
+    # The InstanceMethods module included in the FFI::BitStruct class is
     # * behind the FFI::BitStruct class, but is
     # * in FRONT of the FFI::Struct class.
     # `YourStruct.ancestors`
-    # # => [YourStruct, FFI::BitStruct, FFI::BitField::Property, FFI::Struct...]
+    # # => [YourStruct, FFI::BitStruct, FFI::BitField::InstanceMethods, FFI::Struct...]
     # So you do not need to use `prepend` instead of `include`.
-    include BitField::Property
+    include BitField::InstanceMethods
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ffi-bitfield
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.10
 platform: ruby
 authors:
 - kojix2
 bindir: bin
 cert_chain: []
-date: 2025-03-21 00:00:00.000000000 Z
+date: 2025-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -33,8 +33,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/ffi/bit_field.rb
-- lib/ffi/bit_field/layout.rb
-- lib/ffi/bit_field/property.rb
+- lib/ffi/bit_field/class_methods.rb
+- lib/ffi/bit_field/instance_methods.rb
 - lib/ffi/bit_field/version.rb
 - lib/ffi/bit_struct.rb
 - lib/ffi/managed_bit_struct.rb

data/lib/ffi/bit_field/layout.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module FFI
-  module BitField
-    # Layout provides methods for defining bit field layouts.
-    # This module is extended by BitStruct and ManagedBitStruct classes.
-    module Layout
-      # Defines bit fields within a parent field.
-      #
-      # @param [Array] layout_args An array where the first element is the parent field name,
-      #   followed by alternating field name and bit width pairs
-      # @return [Symbol] parent_name The name of the parent field
-      #
-      # @example Define bit fields in an 8-bit integer
-      #   bit_fields :flags,
-      #     :read,    1,  # 1 bit for read permission
-      #     :write,   1,  # 1 bit for write permission
-      #     :execute, 1,  # 1 bit for execute permission
-      #     :unused,  5   # 5 unused bits
-      #
-      # @note The total bit width should not exceed the size of the parent field.
-      #   For example, a :uint8 field can hold at most 8 bits.
-      def bit_fields(*layout_args)
-        # The reason for using class instance variable here instead of class variable
-        # is not because class instance variables are clean,
-        # but because sub-class of FFI::Struct cannot be inherited again.
-        @bit_field_hash_table = {} unless instance_variable_defined?(:@bit_field_hash_table)
-
-        parent_name = layout_args.shift.to_sym
-        member_names = []
-        widths = []
-        layout_args.each_slice(2) do |name, width|
-          member_names << name.to_sym
-          widths << width.to_i
-        end
-        starts = widths.inject([0]) do |result, width|
-          result << (result.last + width)
-        end
-        member_names.zip(starts, widths).each do |name, start, width|
-          @bit_field_hash_table[name] = [parent_name, start, width]
-        end
-
-        parent_name
-      end
-      alias bit_field bit_fields
-    end
-  end
-end