ffi-bitfield 0.0.10 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a7ec1a2c9da825cb036e42ad7b0e3745704e5bb9fba89394993c3043da9e521
-  data.tar.gz: 10d2ecd8efcb3312228d684b0e15ccc32654de39dc4399065267ad5866e2d0cb
+  metadata.gz: fe9149d50ec1010a72da77b760d5c9f110688a2fae95fa51fd8df155ea6f85f7
+  data.tar.gz: 6f2e4d91b7386406e89512d8a3a352c5e40a39a554ca128b70fc6c4573984dd6
 SHA512:
-  metadata.gz: 688c1d48d37dc1d9f619af9da8ee5d8ac5546d8b6dcab618db5df90d603c73a4c80aac58dfc91b385da9f4e8ea90f2442e47d73441564f5e75e579d7b2636b4c
-  data.tar.gz: 230ed815df33fe597fdf4fa9dc61afd6b69fa625de30826cb795db58aeebeb31ffecf68ebceed6b764450169dee91949ea86006ee4238d6e058e93ad84ed0b9d
+  metadata.gz: 18912f59cc0434df26e14b211b275478c89fe2a96852728a6213ffb134e7d5a83d698d274a3258f17735c38dc7c38ef2b9dde4a62f23d6a0903b1b356be72e1d
+  data.tar.gz: c5cda72742bdf29f27f24512d7d3263c6700ffcfc19cff4a7d4e8687cd44f60a7f7ad4a03b4939f6a55bd30a606e3e93a63cc41dccbe52b1b24ecb62901ef59e

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 kojix2
+Copyright (c) 2021-present kojix2
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/ffi-bitfield.svg)](https://badge.fury.io/rb/ffi-bitfield)
 [![test](https://github.com/kojix2/ffi-bitfield/actions/workflows/ci.yml/badge.svg)](https://github.com/kojix2/ffi-bitfield/actions/workflows/ci.yml)
+[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Fffi-bitfield%2Flines)](https://tokei.kojix2.net/github/kojix2/ffi-bitfield)
 
 Bit field for [Ruby-FFI](https://github.com/ffi/ffi)
 
@@ -15,8 +16,8 @@ gem install ffi-bitfield
 
 Classes
 
-* class BitStruct < FFI::Struct
-* class ManagedBitStruct < FFI::ManagedStruct
+- class BitStruct < FFI::Struct
+- class ManagedBitStruct < FFI::ManagedStruct
 
 Loading
 
@@ -70,6 +71,35 @@ s[:y] = 1
 p s[:a] # 64
 ```
 
+### Typed Bit Fields
+
+You can use the `bit_fields_typed` method to define bit fields with type information. This method accepts a hash where keys are field names and values are arrays containing `[width, type]`. For boolean fields (width of 1 with `:bool` type), it automatically generates a `?` helper method:
+
+```ruby
+class AccessFlags < FFI::BitStruct
+  layout \
+    :flags, :uint8
+
+  bit_fields_typed :flags,
+    revoked: [1, :bool],       # Creates revoked? method
+    expired: [1, :bool],       # Creates expired? method
+    some_string: [4, :string],
+    reserved: [2, :int]
+end
+
+flags = AccessFlags.new
+flags[:revoked] = 1
+flags[:expired] = 0
+
+p flags.revoked?  # => true
+p flags.expired?  # => false
+
+flags[:expired] = 1
+p flags.expired?  # => true
+```
+
+The `?` methods are only generated for fields that are 1 bit wide and have type `:bool`. Other field types can be used for documentation purposes and future functionality.
+
 ### Inspecting Bit Fields
 
 You can use the `bit_field_members` method to get a hash of bit fields grouped by parent field:
@@ -128,7 +158,7 @@ bundle install
 bundle exec rake test
 ```
 
-* [ffi-bitfield - read/write bit fields with Ruby-FFI](https://dev.to/kojix2/ffi-bitfield-g4h)
+- [ffi-bitfield - read/write bit fields with Ruby-FFI](https://dev.to/kojix2/ffi-bitfield-g4h)
 
 ## Contributing
 

data/lib/ffi/bit_field/class_methods.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FFI
   module BitField
     # ClassMethods provides methods for defining bit field layouts.
@@ -147,9 +145,13 @@ module FFI
           member_names << name.to_sym
           widths << width.to_i
         end
-        starts = widths.inject([0]) do |result, width|
-          result << (result.last + width)
-        end
+
+        # Prevent redefining bit fields on the same parent field
+        ensure_parent_not_defined(parent_name)
+
+        # Validate total width against parent size
+        validate_total_width(parent_name, widths)
+        starts = bit_start_offsets(widths)
         member_names.zip(starts, widths).each do |name, start, width|
           @bit_field_hash_table[name] = [parent_name, start, width]
         end
@@ -157,6 +159,97 @@ module FFI
         parent_name
       end
       alias bit_field bit_fields
+
+      # Defines typed bit fields within a parent field using hash syntax.
+      #
+      # @param [Symbol] parent_name The name of the parent field
+      # @param [Hash] field_definitions A hash where keys are field names and values are arrays [width, type]
+      # @return [Symbol] parent_name The name of the parent field
+      #
+      # @example Define typed bit fields with automatic boolean helpers
+      #   bit_fields_typed :flags,
+      #     revoked: [1, :bool],      # Creates revoked? methods
+      #     expired: [1, :bool],      # Creates expired? methods
+      #     some_string: [4, :string] # Creates some_string method
+      #
+      # @note For fields with width 1 and type :bool, a "?" helper method is automatically created
+      # @note The total bit width should not exceed the size of the parent field.
+      def bit_fields_typed(parent_name, field_definitions)
+        @bit_field_hash_table = {} unless instance_variable_defined?(:@bit_field_hash_table)
+        @bit_field_type_table = {} unless instance_variable_defined?(:@bit_field_type_table)
+
+        parent_name = parent_name.to_sym
+        member_names = []
+        widths = []
+        types = []
+
+        field_definitions.each do |name, definition|
+          width, type = definition
+          member_names << name.to_sym
+          widths << width.to_i
+          types << type.to_sym
+        end
+
+        # Prevent redefining bit fields on the same parent field
+        ensure_parent_not_defined(parent_name)
+
+        # Validate total width against parent size
+        validate_total_width(parent_name, widths)
+
+        starts = bit_start_offsets(widths)
+
+        member_names.zip(starts, widths, types).each do |name, start, width, type|
+          @bit_field_hash_table[name] = [parent_name, start, width]
+          @bit_field_type_table[name] = type
+
+          # Generate "?" method for boolean fields with width 1
+          next unless width == 1 && type == :bool
+
+          define_method(:"#{name}?") do
+            self[name] == 1
+          end
+        end
+
+        parent_name
+      end
+
+      private
+
+      # Return cumulative start positions for given widths
+      # e.g., [3, 4, 1] => [0, 3, 7]
+      def bit_start_offsets(widths)
+        starts = []
+        sum = 0
+        widths.each do |w|
+          starts << sum
+          sum += w
+        end
+        starts
+      end
+
+      # Raise if the same parent already has bit fields
+      def ensure_parent_not_defined(parent_name)
+        return unless @bit_field_hash_table&.any? { |_n, info| info[0] == parent_name }
+
+        raise ArgumentError, "bit_fields for :#{parent_name} already defined"
+      end
+
+      # Return parent field size in bits (nil if unknown)
+      def parent_size_bits(parent_name)
+        field = layout[parent_name] # nil if not found
+        return nil unless field&.respond_to?(:type)
+
+        field.type.size * 8
+      end
+
+      # Raise if total width exceeds parent size
+      def validate_total_width(parent_name, widths)
+        size = parent_size_bits(parent_name)
+        return unless size
+
+        total = widths.sum
+        raise ArgumentError, "Bit width #{total} exceeds :#{parent_name} size (#{size} bits)" if total > size
+      end
     end
   end
 end

data/lib/ffi/bit_field/instance_methods.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FFI
   module BitField
     # InstanceMethods provides methods for reading and writing bit field values.
@@ -42,7 +40,7 @@ module FFI
         parent_name, start, width = member_value_info(member_name)
         if parent_name
           value = get_member_value(parent_name)
-          (value >> start) & ((1 << width) - 1)
+          (value >> start) & max_value_for_width(width)
         else
           get_member_value(member_name)
         end
@@ -63,20 +61,20 @@ module FFI
       # @example Writing a negative value (bit-flipped)
       #   struct[:field] = -1  # Sets all bits to 1
       def []=(member_name, value)
-        # Ensure value is an Integer
-        raise TypeError, "Value must be an Integer, got #{value.class}" unless value.is_a?(Integer)
-
         # 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
 
+        # Ensure value is an Integer (only for bit fields)
+        raise TypeError, "Value must be an Integer, got #{value.class}" unless value.is_a?(Integer)
+
         # Extract bit field information
         parent_name, start, width = field_info
 
         # Calculate max value for this bit width
-        max_value = (1 << width) - 1
+        max_value = max_value_for_width(width)
 
         # Handle negative values by bit-flipping
         if value.negative?
@@ -105,20 +103,46 @@ module FFI
 
         # 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)
+        mask = create_bitmask(width, start)
+        new_value = (parent_value & ~mask) | ((value & max_value_for_width(width)) << start)
 
         set_member_value(parent_name, new_value)
       end
 
       private
 
+      # Calculates the maximum value that can be stored in the given bit width.
+      # For example: 3 bits can store 0b000 to 0b111, so max is 7
+      #
+      # @param [Integer] width The number of bits
+      # @return [Integer] The maximum value
+      # @example
+      #   max_value_for_width(3)  # => 7 (0b111)
+      #   max_value_for_width(4)  # => 15 (0b1111)
+      def max_value_for_width(width)
+        (1 << width) - 1
+      end
+
+      # Creates a bitmask for extracting or setting bits at a specific position.
+      # For example: width=3, start=2 creates 0b11100 (mask for bits 2,3,4)
+      #
+      # @param [Integer] width The number of bits in the mask
+      # @param [Integer] start The starting bit position (0-indexed from right)
+      # @return [Integer] The bitmask
+      # @example
+      #   create_bitmask(3, 2)  # => 28 (0b11100)
+      #   create_bitmask(2, 0)  # => 3 (0b11)
+      def create_bitmask(width, start)
+        max_value_for_width(width) << start
+      end
+
       # 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]
+        hash_table = self.class.instance_variable_get(:@bit_field_hash_table)
+        hash_table&.[](member_name)
       end
     end
   end

data/lib/ffi/bit_field/version.rb

@@ -1,8 +1,6 @@
-# frozen_string_literal: true
-
 module FFI
   module BitField
     # Current version of the ffi-bitfield gem.
-    VERSION = '0.0.10'
+    VERSION = '0.1.0'
   end
 end

data/lib/ffi/bit_field.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require_relative 'bit_field/version'
 require_relative 'bit_struct'
 require_relative 'managed_bit_struct'

data/lib/ffi/bit_struct.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'ffi'
 require_relative 'bit_field/version'
 require_relative 'bit_field/class_methods'

data/lib/ffi/managed_bit_struct.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'ffi'
 require_relative 'bit_field/version'
 require_relative 'bit_field/class_methods'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ffi-bitfield
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.0
 platform: ruby
 authors:
 - kojix2
 bindir: bin
 cert_chain: []
-date: 2025-04-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -23,7 +23,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: bit fields for Ruby-FFI
+description: Provides bit field support for FFI::Struct and FFI::ManagedStruct
 email:
 - 2xijok@gmail.com
 executables: []
@@ -56,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
-summary: bit fields for Ruby-FFI
+summary: Bit fields for Ruby-FFI
 test_files: []