ffi-bitfield 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e82e912397a405df792824503984be18325c6c22b76307a0fc9d7fe65c5a95f
-  data.tar.gz: a3bbf7a5ecdcba6e4627c80e9a108788e281fc18f9d4abededf5d47833b0783d
+  metadata.gz: da1a5728a9f03382d8de48da89ad38e95ddec9e493288b5f5954fc0eeed34f24
+  data.tar.gz: f14ac752955f7a13a0753099cb85b46ff6e7d8bb20f559baea397ad6fa10375d
 SHA512:
-  metadata.gz: 76c80c9d0444042ad7ca1b8c28b084562c84b9ac843f0f23a3253444fefee3f4a959da752395d4fa43fc663aab4b1854bb5bd3e21b2550fca2b5c4cc8560ad4a
-  data.tar.gz: 33b72012820da5d15fcf1f753cd2a1203c3bd467b0d4596b429e7c46ba485bee91d45424142c4411996545054eb8f3bd368d53fa477cf7bde330c680689a9276
+  metadata.gz: 94d9b4e73951519a5f3af827ee4d3131891cf0586f7c01f1a7e83057fcbd27580e3edf61cc5176190ed9fc86feb73e392b122c5c7ea75ba93333609d9bc5bfe1
+  data.tar.gz: 1c652488233f533fb78e2724cb9070e81dd5cf8915e241676f7c60b8e8ecfb4de1c4fb651daf0e2f993d340fbc3a343c9ad4acd9dbebaa08308981f7af9e77c9

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
@@ -99,7 +135,7 @@ bundle exec rake test
 Your feedback is important.
 
 ffi-bitfield is a library under development, so even small improvements like typofix are welcome! Please feel free to send us your pull requests.
-Bug reports and pull requests are welcome on GitHub at https://github.com/kojix2/bitstruct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kojix2/ffi-bitfield.
 
     Do you need commit rights to my repository?
     Do you want to get admin rights and take over the project?

data/lib/ffi/bit_field/layout.rb

@@ -2,10 +2,90 @@
 
 module FFI
   module BitField
-    # Layout provides the `bit_fields` method for registering field members.
+    # Layout provides methods for defining bit field layouts.
+    # This module is extended by BitStruct and ManagedBitStruct classes.
     module Layout
-      # @param [Array] layout_args
-      # @return [Symbol] parent_name
+      # 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
+
+      # 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,

data/lib/ffi/bit_field/property.rb

@@ -2,36 +2,95 @@
 
 module FFI
   module BitField
-    # Properties provides methods to read and write bit fields.
+    # Property provides methods for reading and writing bit field values.
+    # This module is included in BitStruct and ManagedBitStruct classes.
     module Property
-      # @param [Symbol] member_name
-      # @return [Integer] value
+      # Reads a value from a bit field or regular field.
+      #
+      # @param [Symbol] member_name The name of the field to read
+      # @return [Integer] The value of the field
+      #
+      # @example Reading a bit field
+      #   struct[:flag1]  # => 1
       def [](member_name)
         parent_name, start, width = member_value_info(member_name)
         if parent_name
           value = get_member_value(parent_name)
-          value[start, width]
+          (value >> start) & ((1 << width) - 1)
         else
           get_member_value(member_name)
         end
       end
 
+      # Writes a value to a bit field or regular field.
+      #
+      # @param [Symbol] member_name The name of the field to write
+      # @param [Integer] value The value to write
+      # @return [Integer] The written value
+      # @raise [ArgumentError] If the value is too large for the bit field
+      # @raise [ArgumentError] If the value is too small (negative) for the bit field
+      # @raise [ArgumentError] If the member name is not a valid bit field
+      # @raise [TypeError] If the value is not an Integer
+      #
+      # @example Writing to a bit field
+      #   struct[:flag1] = 1
+      # @example Writing a negative value (bit-flipped)
+      #   struct[:field] = -1  # Sets all bits to 1
       def []=(member_name, value)
-        parent_name, start, width = member_value_info(member_name)
-        if parent_name
-          raise ArgumentError, "Value #{value} is larger than bit_length: #{width}" if value.bit_length > width
+        # Ensure value is an Integer
+        raise TypeError, "Value must be an Integer, got #{value.class}" unless value.is_a?(Integer)
 
-          parent_value = get_member_value(parent_name)
-          new_value = (((1 << width) - 1 << start) & parent_value ^ parent_value) |
-                      (value << start)
-          set_member_value(parent_name, new_value)
-        else
-          set_member_value(member_name, value)
+        # Get bit field information
+        field_info = member_value_info(member_name)
+
+        # If not a bit field, delegate to regular field setter
+        return set_member_value(member_name, value) unless field_info
+
+        # Extract bit field information
+        parent_name, start, width = field_info
+
+        # Calculate max value for this bit width
+        max_value = (1 << width) - 1
+
+        # Handle negative values by bit-flipping
+        if value.negative?
+          # For negative values, we interpret them as bit-flipped positive values
+          # For example, with 4 bits, -1 becomes 1111 (15), -2 becomes 1110 (14), etc.
+
+          # Check if the negative value is within range
+          # For bit-flipping, valid range is -(2^n) to -1
+          min_value = -(1 << width)
+          if value < min_value
+            raise ArgumentError, "Value #{value} is too small for bit_length: #{width}, minimum is #{min_value}"
+          end
+
+          # Convert negative value to bit-flipped positive value
+          # -1 -> 15, -2 -> 14, etc.
+          value = max_value + value + 1
+
+          # Sanity check after conversion
+          if value.negative? || value > max_value
+            raise ArgumentError, "Internal error: converted value #{value} is out of range for bit_length: #{width}"
+          end
+        elsif value > max_value
+          # For positive values, check if they fit in the bit width
+          raise ArgumentError, "Value #{value} is too large for bit_length: #{width}, maximum is #{max_value}"
         end
+
+        # Update the parent field with the new bit field value
+        parent_value = get_member_value(parent_name)
+        mask = ((1 << width) - 1) << start
+        new_value = (parent_value & ~mask) | ((value & ((1 << width) - 1)) << start)
+
+        set_member_value(parent_name, new_value)
       end
 
       private
 
+      # Gets information about a bit field member.
+      #
+      # @param [Symbol] member_name The name of the bit field
+      # @return [Array, nil] An array containing [parent_name, start_bit, width] or nil if not a bit field
       def member_value_info(member_name)
         self.class.instance_variable_get(:@bit_field_hash_table)[member_name]
       end

data/lib/ffi/bit_field/version.rb

@@ -2,6 +2,7 @@
 
 module FFI
   module BitField
-    VERSION = '0.0.7'
+    # Current version of the ffi-bitfield gem.
+    VERSION = '0.0.9'
   end
 end

data/lib/ffi/bit_field.rb

@@ -4,8 +4,26 @@ require_relative 'bit_field/version'
 require_relative 'bit_struct'
 require_relative 'managed_bit_struct'
 
+# Foreign Function Interface module for Ruby.
+# This is the main namespace for the Ruby-FFI library.
 module FFI
-  # This module is just a namespace.
+  # BitField provides bit field functionality for Ruby-FFI.
+  # It allows defining, reading, and writing bit fields within FFI structs.
+  #
+  # @example Basic usage
+  #   class MyStruct < FFI::BitStruct
+  #     layout \
+  #       :flags, :uint8
+  #
+  #     bit_fields :flags,
+  #       :flag1, 1,
+  #       :flag2, 1,
+  #       :value, 6
+  #   end
+  #
+  #   struct = MyStruct.new
+  #   struct[:flag1] = 1
+  #   struct[:value] = 42
   module BitField
   end
 end

data/lib/ffi/bit_struct.rb

@@ -6,7 +6,25 @@ require_relative 'bit_field/layout'
 require_relative 'bit_field/property'
 
 module FFI
-  # Subclass of FFI::Struct that support bit fields.
+  # Subclass of FFI::Struct that supports bit fields.
+  # Allows defining and accessing individual bits within integer fields.
+  #
+  # @example Define a struct with bit fields
+  #   class Flags < FFI::BitStruct
+  #     layout \
+  #       :value, :uint8
+  #
+  #     bit_fields :value,
+  #       :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
+  #   end
+  #
+  #   flags = Flags.new
+  #   flags[:read] = 1
+  #   flags[:write] = 1
+  #   puts flags[:value]  # => 3
   class BitStruct < Struct
     # [] is defined in FFI::Struct
     alias get_member_value []

data/lib/ffi/managed_bit_struct.rb

@@ -6,7 +6,28 @@ require_relative 'bit_field/layout'
 require_relative 'bit_field/property'
 
 module FFI
-  # Subclass of FFI::ManagedStruct that support bit fields.
+  # Subclass of FFI::ManagedStruct that supports bit fields.
+  # Combines memory management with bit field functionality.
+  #
+  # Use this class when you need automatic memory management for your structs
+  # with bit fields. You must implement the self.release method to handle
+  # memory cleanup.
+  #
+  # @example Define a managed struct with bit fields
+  #   class ManagedFlags < FFI::ManagedBitStruct
+  #     layout \
+  #       :value, :uint8
+  #
+  #     bit_fields :value,
+  #       :read,    1,
+  #       :write,   1,
+  #       :execute, 1,
+  #       :unused,  5
+  #
+  #     def self.release(ptr)
+  #       # Custom memory cleanup code
+  #     end
+  #   end
   class ManagedBitStruct < ManagedStruct
     # [] is defined in FFI::Struct
     alias get_member_value []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffi-bitfield
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.9
 platform: ruby
 authors:
 - kojix2
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-16 00:00:00.000000000 Z
+date: 2025-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -43,7 +43,7 @@ homepage: https://github.com/kojix2/ffi-bitfield
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,8 +58,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: bit fields for Ruby-FFI
 test_files: []