bin_struct 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df710325cf6aa4414fc997d77033b8bea34d4dc80e571ceb184462b2aa047eb3
-  data.tar.gz: aa372402e27bc5b254b7e4e82cb7d9b2178823c84adc3c1bda17bba7806ff05e
+  metadata.gz: aeb290e624ce4004c20cfaf40fc60ae43938c80eab8fd1df1e8aa908a75e26cf
+  data.tar.gz: 8cb5dd0abdce7421b8269a4d35c14886f57cc6440a50c924b0937e5b30fe20ce
 SHA512:
-  metadata.gz: 6ef8207d1fc62509bda66a0caa779ec2b6b95e2a7805fb10199423bcf1300a7f05dd5c5b595f33f8b6605b93277e485a5a18f80a83b7c6954339eea0541f6073
-  data.tar.gz: b47f00bd2497c5330eeb6a01721b3cbd4a305d624e6df7dce2fd13b8f996c61e287ab92df393ea0fcb67fece0396497354220e9a56cb50bf617fa0d9b3ccdaff
+  metadata.gz: ecf6acc2f5c406556598212d22ad6257d22ed646c1128a145cff1730dc537bb7acfd40903f211aad28b11fa30c11324a98b98ecebb70ad7b84ea991bcf181f25
+  data.tar.gz: 1dcfbb20a54f7c08d2794e0e8391b70c633d65f6ccbc41c372e46c77da6fb036fbfa9d1548462030b86603e3e41b132019da70b3c2d603f7f21116bdc842ec14

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.4.0 - 2025-02-13
+
+### Added
+
+- Add `Struct#attribute?` to check existence of an attribute.
+- Add `AbstractTLV.derive` to derive a new subclass from a concrete TLV class.
+
+### Fixed
+
+- Update and fix Yard documentation.
+
+## 0.3.0 - 2024-12-02
+
+### Added
+
+- `BitAddr` class is added. This class is used as a `Structable` type to handle bitfield attributes.
+- Add `Struct.define_bit_attr`, `.define_bit_attr_before` and `.define_bit_attr_before` to define bitfield attributes.
+
+### Changed
+
+- `Struct.define_bit_attr_on` is removed in favor of `Struct.define_bit_attr`. Bitfield attributes are now first class attributes, and no more an onverlay on `Int`.
+
 ## 0.2.1 - 2024-11-25
 
 ### Added

data/README.md

@@ -19,6 +19,89 @@ Or add it to a Gemfile:
 gem 'bin_struct'
 ```
 
+## Usage
+
+### Create a struct
+
+To create a BinStruct, create a new class inheriting from `BinStruct::Struct`. Then, defines struct attributes using `.define_attr`. `.define_bit_attr` may also be used to define bit field attributes.
+
+```ruby
+require 'bin_struct'
+
+class IPHeader < BinStruct::Struct
+  # Define a bir field, defaulting to 0x45, and splitted in 2 sub-fields: version and ihl,
+  # 4-bit size each
+  define_bit_attr :u8, default: 0x45, version: 4, ihl: 4
+  # Define a 8-bit unsigned integer named tos
+  #  1st argument: a symbol to define attribute name
+  #  2nd argument: a class to define attribute type. May be a type provided by BinStruct,
+  #                or a user-defined class inheriting from one of these classes
+  #  others arguments: options. Here, :default defines a default value for the attribute.
+  define_attr :tos, BinStruct::Int8, default: 0
+  # Define a 16-bit unsigned integer named length. Default to 20.
+  define_attr :length, BinStruct::Int16, default: 20
+  # Define a 16-bir unsigned integer named id. It is initialized with a random number
+  define_attr :id, BinStruct::Int16, default: ->(_) { rand(65_535) }
+  # Define a bit field composed of 4 subfields of 1, 1, 1 and 13 bit, respectively
+  define_bit_attr :frag, flag_rsv: 1, flag_df: 1, flag_mf: 1, fragment_offset: 13
+  # Define TTL field, a 8-bit unsigned integer, default to 64
+  define_attr :ttl, BinStruct::Int8, default: 64
+  # Define protocol field (8-bit unsigned integer)
+  define_attr :protocol, BinStruct::Int8
+  # Define checksum field (16-bit unsigned integer), default to 0
+  define_attr :checksum, BinStruct::Int16, default: 0
+  # Source and destination addresses, defined as array of 4 8-bit unsigned integers
+  define_attr :src, BinStruct::ArrayOfInt8, length_from: -> { 4 }
+  define_attr :dst, BinStruct::ArrayOfInt8, length_from: -> { 4 }
+end
+```
+
+### Parse a binary string
+
+```ruby
+# Initialize struct from a binary string
+ip = IPHeader.new.read("\x45\x00\x00\x14\x43\x21\x00\x00\x40\x01\x00\x00\x7f\x00\x00\x01\x7f\x00\x00\x01".b)
+
+# Access some fields
+p ip.version     #=> 4
+p ip.ihl         #=> 5
+p ip.id.to_s(16) #=> "4321"
+p ip.protocol    #=> 1
+p ip.src.map { |byte| byte.to_i }.join('.') #=> "127.0.0.1"
+```
+
+```text
+> p IPHeader.new.read("\x45\x00\x00\x14\x43\x21\x00\x00\x40\x01\x00\x00\x7f\x00\x00\x01\x7f\x00\x00\x01")
+-- IPHeader -----------------------------------------------------------
+          BitAttr8               u8: 69               (0x45)
+                                     version:4 ihl:5
+              Int8              tos: 0                (0x00)
+             Int16           length: 20               (0x0014)
+             Int16               id: 17185            (0x4321)
+         BitAttr16             frag: 0                (0x0000)
+                                     flag_rsv:0 flag_df:0 flag_mf:0 fragment_offset:0
+              Int8              ttl: 64               (0x40)
+              Int8         protocol: 1                (0x01)
+             Int16         checksum: 0                (0x0000)
+       ArrayOfInt8              src: 127,0,0,1
+       ArrayOfInt8              dst: 127,0,0,1
+
+```
+
+### Generate a binary string
+
+```ruby
+# Create a new struct with some fields initialized
+ip = IPHeader.new(tos: 42, id: 0x1234)
+
+# Initialize fields after creation
+ip.src = [192, 168, 1, 1]
+ip.dst = [192, 168, 1, 2]
+
+# Generate binary string
+ip.to_s
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/bin_struct/abstract_tlv.rb

@@ -13,7 +13,7 @@ module BinStruct
   #
   # ===Usage
   # To simply define a new TLV class, do:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create
+  #   MyTLV = BinStruct::AbstractTLV.create
   #   MyTLV.define_type_enum 'one' => 1, 'two' => 2
   # This will define a new +MyTLV+ class, subclass of {AbstractTLV}. This class will
   # define 3 attributes:
@@ -32,9 +32,9 @@ module BinStruct
   #
   # ===Advanced usage
   # Each attribute's type may be changed at generating TLV class:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
-  #                                                length_class: PacketGen::Types::Int16,
-  #                                                value_class: PacketGen::Header::IP::Addr)
+  #   MyTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16,
+  #                                         length_class: BinStruct::Int16,
+  #                                         value_class: PacketGen::Header::IP::Addr)
   #   tlv = MyTLV.new(type: 1, value: '1.2.3.4')
   #   tlv.type        #=> 1
   #   tlv.length      #=> 4
@@ -43,9 +43,9 @@ module BinStruct
   #
   # Some aliases may also be defined. For example, to create a TLV type
   # whose +type+ attribute should be named +code+:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
-  #                                                length_class: PacketGen::Types::Int16,
-  #                                                aliases: { code: :type })
+  #   MyTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16,
+  #                                         length_class: BinStruct::Int16,
+  #                                         aliases: { code: :type })
   #   tlv = MyTLV.new(code: 1, value: 'abcd')
   #   tlv.code        #=> 1
   #   tlv.type        #=> 1
@@ -77,11 +77,12 @@ module BinStruct
       #   in the desired order.
       # @param [::String] attr_in_length give attributes to compute length on.
       # @return [Class]
+      # @raise [Error] Called on {AbstractTLV} subclass
       def create(type_class: Int8Enum, length_class: Int8, value_class: String,
                  aliases: {}, attr_order: 'TLV', attr_in_length: 'V')
         unless equal?(AbstractTLV)
           raise Error,
-                '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV'
+                '.create cannot be called on a subclass of BinStruct::AbstractTLV'
         end
 
         klass = Class.new(self)
@@ -91,7 +92,7 @@ module BinStruct
         check_attr_in_length(attr_in_length)
         check_attr_order(attr_order)
         generate_attributes(klass, attr_order, type_class, length_class, value_class)
-
+        generate_aliases_for(klass, aliases)
         aliases.each do |al, orig|
           klass.instance_eval do
             alias_method al, orig if klass.method_defined?(orig)
@@ -103,6 +104,50 @@ module BinStruct
       end
       # rubocop:enable Metrics/ParameterLists
 
+      # On inheritage, copy aliases and attr_in_length
+      # @param [Class] klass inheriting class
+      # @return [void]
+      # @since 0.4.0
+      # @author LemonTree55
+      def inherited(klass)
+        super
+
+        aliases = @aliases.clone
+        attr_in_length = @attr_in_length.clone
+
+        klass.class_eval do
+          @aliases = aliases
+          @attr_in_length = attr_in_length
+        end
+      end
+
+      # Derive a new TLV class from an existing one
+      # @param [Class,nil] type_class New class to use for +type+. Unchanged if +nil+.
+      # @param [Class,nil] length_class New class to use for +length+. Unchanged if +nil+.
+      # @param [Class,nil] value_class New class to use for +value+. Unchanged if +nil+.
+      # @return [Class]
+      # @raise [Error] Called on {AbstractTLV} class
+      # @since 0.4.0
+      # @author LemonTree55
+      # @example
+      #   # TLV with type and length on 16 bits, value is a BinStruct::String
+      #   FirstTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16, length_class: BinStruct::Int16)
+      #   # TLV with same type and length classes than FirstTLV, but value is an array of Int8
+      #   SecondTLV = FirstTLV.derive(value_class: BinStruct::ArrayOfInt8)
+      def derive(type_class: nil, length_class: nil, value_class: nil, aliases: {})
+        raise Error, ".derive cannot be called on #{name}" if equal?(AbstractTLV)
+
+        klass = Class.new(self)
+        klass.aliases.merge!(aliases)
+        generate_aliases_for(klass, aliases)
+
+        klass.attr_defs[:type].type = type_class unless type_class.nil?
+        klass.attr_defs[:length].type = length_class unless length_class.nil?
+        klass.attr_defs[:value].type = value_class unless value_class.nil?
+
+        klass
+      end
+
       # @!attribute type
       #   @abstract
       #   Type attribute for real TLV class
@@ -168,6 +213,15 @@ module BinStruct
           end
         end
       end
+
+      def generate_aliases_for(klass, aliases)
+        aliases.each do |al, orig|
+          klass.instance_eval do
+            alias_method al, orig if klass.method_defined?(orig)
+            alias_method :"#{al}=", :"#{orig}=" if klass.method_defined?(:"#{orig}=")
+          end
+        end
+      end
     end
 
     # @!attribute type

data/lib/bin_struct/array.rb

@@ -9,7 +9,7 @@
 require 'forwardable'
 
 module BinStruct
-  # @abstract Base class to define set of {Struct} subclasses.
+  # @abstract Base class to define set of {Structable} subclasses.
   #
   # This class mimics regular Ruby Array, but it is {Structable} and responds to {LengthFrom}.
   #
@@ -44,10 +44,11 @@ module BinStruct
     # @!method clear
     #   Clear array.
     #   @return [void]
+    #   @see #clear!
     # @!method each
     #   Calls the given block once for each element in self, passing that
-    #   element as a parameter. Returns the array itself.
-    #   @return [::Array]
+    #   element as a parameter. Returns the array itself, or an enumerator if no block is given.
+    #   @return [::Array, Enumerator]
     # @method empty?
     #   Return +true+ if contains no element.
     #   @return [Boolean]
@@ -112,6 +113,7 @@ module BinStruct
 
     # Clear array. Reset associated counter, if any.
     # @return [void]
+    # @see #clear
     def clear!
       @array.clear
       @counter&.from_human(0)
@@ -137,7 +139,8 @@ module BinStruct
 
     # @abstract depend on private method +#record_from_hash+ which should be
     #   declared by subclasses.
-    # Add an object to this array. Do not update associated counter.
+    # Add an object to this array. Do not update associated counter. If associated must be incremented, use
+    # {#<<}
     # @param [Object] obj type depends on subclass
     # @return [self]
     # @see #<<
@@ -154,9 +157,11 @@ module BinStruct
 
     # @abstract depend on private method +#record_from_hash+ which should be
     #   declared by subclasses.
-    # Add an object to this array, and increment associated counter, if any
+    # Add an object to this array, and increment associated counter, if any. If associated counter must not be
+    # incremented, use {#push}.
     # @param [Object] obj type depends on subclass
     # @return [self]
+    # @see #push
     def <<(obj)
       push(obj)
       @counter&.from_human(@counter.to_i + 1)

data/lib/bin_struct/bit_attr.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+# This file is part of BinStruct
+# see https://github.com/lemontree55/bin_struct for more informations
+# Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
+# This program is published under MIT license.
+require 'digest'
+
+module BinStruct
+  # Define a bitfield attribute to embed in a {Struct}.
+  #
+  #  class MyStruct < BinStruct::Struct
+  #    # Create a 32-bit bitfield attribute, with fields a (16 bits), b and c (4 bits each) and d (8 bits).
+  #    # a is the leftmost field in bitfield, and d the rightmost one.
+  #    define_attr :int32, BinStruct::BitAttr.create(width: 32, a: 16, b: 4, c: 4, d:8)
+  #  end
+  # @since 0.3.0
+  # @abstract Subclasses must de derived using {.create}.
+  # @author LemonTree55
+  class BitAttr
+    include Structable
+
+    # @return [Integer] width in bits of bit attribute
+    attr_reader :width
+    # @return [::Array[Symbol]]
+    attr_reader :bit_methods
+
+    # @private
+    Parameters = Struct.new(:width, :fields, :int)
+
+    class << self
+      @cache = {}
+
+      # @private
+      # @return [Parameters]
+      attr_reader :parameters
+
+      # Create a new {BitAttr} subclass with specified parameters
+      # @param [Integer] width size of bitfields in bits. Must be a size of an {Int} (8, 16, 24, 32 or 64 bits).
+      # @param [:big,:little,:native] endian endianess of bit attribute as an integer
+      # @param [Hash{Symbol=>Integer}] fields hash associating field names with their size. Total size MUST be equal
+      #    to +width+.
+      # @return [Class]
+      # @raise [ArgumentError] raise if:
+      #    * width is not a size of one of {Int} subclasses,
+      #    * sum of bitfield sizes is not equal to +width+
+      def create(width:, endian: :big, **fields)
+        raise ArgumentError, 'with must be 8, 16, 24, 32 or 64' unless [8, 16, 24, 32, 64].include?(width)
+
+        hsh = compute_hash(width, endian, fields)
+        cached = cache[hsh]
+        return cached if cached
+
+        total_size = fields.reduce(0) { |acc, ary| acc + ary.last }
+        raise ArgumentError, "sum of bitfield sizes is not equal to #{width}" unless total_size == width
+
+        cache[hsh] = Class.new(self) do
+          int_klass = BinStruct.const_get("Int#{width}")
+          @parameters = Parameters.new(width, fields, int_klass.new(endian: endian)).freeze
+        end
+      end
+
+      private
+
+      # @return [Hash{::String=>Class}]
+      def cache
+        return @cache if defined? @cache
+
+        @cache = {}
+      end
+
+      # @param [::Array] params
+      # @return [::String]
+      def compute_hash(*params)
+        Digest::MD5.digest(Marshal.dump(params))
+      end
+    end
+
+    # Initialize bit attribute
+    # @param [Hash{Symbol=>Integer}] opts initialization values for fields, where keys are field names and values are
+    #     initialization values
+    # @return [self]
+    # @raise [NotImplementedError] raised when called on {BitAttr} class
+    def initialize(opts = {})
+      parameters = self.class.parameters
+      raise NotImplementedError, "#initialize may only be called on subclass of #{self.class}" if parameters.nil?
+
+      @width = parameters.width
+      @fields = parameters.fields
+      @int = parameters.int.dup
+      @data = {}
+      @bit_methods = []
+
+      parameters.fields.each do |name, size|
+        @data[name] = opts[name] || 0
+        define_methods(name, size)
+      end
+      @bit_methods.freeze
+    end
+
+    # Get type name
+    # @return [::String]
+    def type_name
+      return @type_name if defined? @type_name
+
+      endian_suffix = case @int.endian
+                      when :big then ''
+                      when :little then 'le'
+                      when :native then 'n'
+                      end
+      @type_name = "BitAttr#{@width}#{endian_suffix}"
+    end
+
+    # Populate bit attribute from +str+
+    # @param [#to_s,nil] str
+    # @return [self]
+    def read(str)
+      return self if str.nil?
+
+      @int.read(str)
+      compute_data(@int.to_i)
+    end
+
+    # Give integer associated to this attribute
+    # @return [Integer]
+    def to_i
+      v = 0
+      @fields.each do |name, size|
+        v <<= size
+        v |= @data[name]
+      end
+
+      v
+    end
+    alias to_human to_i
+
+    # Return binary string
+    # @return [::String]
+    def to_s
+      @int.value = to_i
+      @int.to_s
+    end
+
+    # Set fields from associated integer
+    # @param [#to_i] value
+    # @return [self]
+    def from_human(value)
+      compute_data(value.to_i)
+    end
+
+    def format_inspect
+      str = @int.format_inspect << "\n"
+      str << @data.map { |name, value| "#{name}:#{value}" }.join(' ')
+    end
+
+    private
+
+    # @param [Integer] value
+    # @return [self]
+    def compute_data(value)
+      @fields.reverse_each do |name, size|
+        @data[name] = value & ((2**size) - 1)
+        value >>= size
+      end
+
+      self
+    end
+
+    # @param [Symbol] name
+    # @return [void]
+    def define_methods(name, size)
+      instance_eval "def #{name}; @data[#{name.inspect}]; end\n", __FILE__, __LINE__ # def name; data[:name]; end
+      bit_methods << name
+      bit_methods << :"#{name}="
+
+      # rubocop:disable Style/DocumentDynamicEvalDefinition
+      if size == 1
+        instance_eval "def #{name}?; @data[#{name.inspect}] != 0; end\n", __FILE__, __LINE__
+        instance_eval "def #{name}=(val); v = case val when TrueClass; 1 when FalseClass; 0 else val end; " \
+                      "@data[#{name.inspect}] = v; end", __FILE__, __LINE__ - 1
+        bit_methods << :"#{name}?"
+      else
+        instance_eval "def #{name}=(val); @data[#{name.inspect}] = val; end", __FILE__, __LINE__
+      end
+      # rubocop:enable Style/DocumentDynamicEvalDefinition
+    end
+  end
+end

data/lib/bin_struct/cstring.rb

@@ -76,14 +76,14 @@ module BinStruct
 
     # @param [Hash] options
     # @option options [Integer] :static_length set a static length for this string
-    # @option options [::String] :value string value (default to +''+)
+    # @option options [::String] :value string value (default to +""+)
     def initialize(options = {})
       register_internal_string(options[:value] || +'')
       @static_length = options[:static_length]
     end
 
     # Populate self from binary string
-    # @param [::String] str
+    # @param [#to_s] str
     # @return [self]
     def read(str)
       s = str.to_s

data/lib/bin_struct/enum.rb

@@ -13,19 +13,20 @@ module BinStruct
   # and named values.
   #
   # == Simple example
-  #  enum = Int8Enum.new('low' => 0, 'medium' => 1, 'high' => 2})
+  #   enum = Int8Enum.new('low' => 0, 'medium' => 1, 'high' => 2})
   # In this example, +enum+ is a 8-bit attribute which may take one
   # among three values: +low+, +medium+ or +high+:
-  #  enum.value = 'high'
-  #  enum.value              # => 2
-  #  enum.value = 1
-  #  enum.value              # => 1
-  #  enum.to_human           # => "medium"
-  # Setting an unknown value will raise an exception:
-  #  enum.value = 4          # => raise!
-  #  enum.value = 'unknown'  # => raise!
-  # But {#read} will not raise when reading an outbound value. This
+  #   enum.value = 'high'
+  #   enum.value              # => 2
+  #   enum.value = 1
+  #   enum.value              # => 1
+  #   enum.to_human           # => "medium"
+  # Setting an unknown name will raise an exception:
+  #   enum.value = 'unknown'  # => raise!
+  # But {#read} and {#value=} will not raise when reading/setting an out-of-bound integer. This
   # to enable decoding (or forging) of bad packets.
+  #   enum.read("\x05".b).value # => 5
+  #   enum.value = 4            # => 4
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class Enum < Int

data/lib/bin_struct/int.rb

@@ -55,7 +55,7 @@ module BinStruct
 
     # @abstract
     # @return [::String]
-    # @raise [Error] This is an abstrat method and must be redefined
+    # @raise [Error] This is an abstract method and must be redefined
     def to_s
       raise Error, 'BinStruct::Int#to_s is abstract' unless defined? @packstr
 

data/lib/bin_struct/int_string.rb

@@ -9,6 +9,13 @@
 module BinStruct
   # Provides a class for creating strings preceeded by their length as an {Int}.
   # By default, a null string will have one byte length (length byte set to 0).
+  # == Examples
+  #   # IntString with 8-bit length
+  #   is8 = BinStruct::IntString.new(value: "abcd")
+  #   is8.to_s   # => "\x04abcd"
+  #   # IntString with 16-bit length
+  #   is16 = BinStruct::IntString.new(length_type: BinStruct::Int16le, value: "abcd")
+  #   is16.to_s  # => "\x04\x00abcd"
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class IntString
@@ -61,7 +68,7 @@ module BinStruct
     # @return [::String]
     def string=(str)
       @length.value = str.to_s.size
-      @string = str.to_s
+      @string.read(str)
     end
 
     # Get binary string
@@ -82,7 +89,7 @@ module BinStruct
     # Get human readable string
     # @return [::String]
     def to_human
-      @string
+      @string.to_s
     end
 
     # Set length from internal string length

data/lib/bin_struct/string.rb

@@ -32,7 +32,7 @@ module BinStruct
     # @option options [Int,Proc] :length_from object or proc from which
     #   takes length when reading
     # @option options [Integer] :static_length set a static length for this string
-    # @option options [::String] :value string value (default to +''+)
+    # @option options [::String] :value string value (default to +""+)
     def initialize(options = {})
       register_internal_string(options[:value] || +'')
       initialize_length_from(options)
@@ -47,7 +47,7 @@ module BinStruct
     end
 
     # Populate String from a binary String. Limit length using {LengthFrom} or {#static_length}, if one is set.
-    # @param [::String] str
+    # @param [::String,nil] str
     # @return [self]
     def read(str)
       s = read_with_length_from(str)
@@ -87,7 +87,7 @@ module BinStruct
       self
     end
 
-    # Generate binary string
+    # Generate "binary" string
     # @return [::String]
     def to_s
       @string

data/lib/bin_struct/struct.rb

@@ -81,25 +81,23 @@ module BinStruct
   #   define_attr :opt1, BinStruct::Int16, optional: ->(h) { h.type == 42 }
   #
   # == Generating bit attributes
-  # {.define_bit_attr_on} creates bit attributes on a previously declared integer
-  # attribute. For example, +frag+ attribute in IP header:
-  #   define_attr :frag, BinStruct::Int16, default: 0
-  #   define_bit_attr_on :frag, :flag_rsv, :flag_df, :flag_mf, :fragment_offset, 13
+  # {.define_bit_attr} creates a bit attribute. For example, +frag+ attribute in IP header:
+  #   define_bit_attr :frag, flag_rsv: 1, flag_df: 1, flag_mf: 1, fragment_offset: 13
   #
   # This example generates methods:
   # * +#frag+ and +#frag=+ to access +frag+ attribute as a 16-bit integer,
   # * +#flag_rsv?+, +#flag_rsv=+, +#flag_df?+, +#flag_df=+, +#flag_mf?+ and +#flag_mf=+
   #   to access Boolean RSV, MF and DF flags from +frag+ attribute,
+  # * +#flag_rsv+, +#flag_df+ and +#flag_mf# to read RSV, MF and DF flags as Integer,
   # * +#fragment_offset+ and +#fragment_offset=+ to access 13-bit integer fragment
   #   offset subattribute from +frag+ attribute.
   #
   # == Creating a new Struct class from another one
   # Some methods may help in this case:
-  # * {.define_attr_before} to define a new attribute before an existing one,
-  # * {.define_attr_after} to define a new attribute after an existing onr,
-  # * {.remove_attribute} to remove an existing attribute,
-  # * {.uptade_fied} to change options of an attribute (but not its type),
-  # * {.remove_bit_attrs_on} to remove bit attribute definition.
+  # * {.define_attr_before} and {.define_bit_attr_before} to define a new attribute before an existing one,
+  # * {.define_attr_after} and {.define_bit_attr_after} to define a new attribute after an existing onr,
+  # * {.remove_attr} to remove an existing attribute,
+  # * {.uptade_attr} to change options of an attribute (but not its type),
   #
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
@@ -121,7 +119,7 @@ module BinStruct
       # @return [Hash]
       attr_reader :attr_defs
       # Get bit attribute defintions for this class
-      # @return [Hash]
+      # @return [Hash{Symbol=>Array[Symbol]}]
       attr_reader :bit_attrs
 
       # On inheritage, create +@attr_defs+ class variable
@@ -198,11 +196,7 @@ module BinStruct
         define_attr name, type, options
         return if other.nil?
 
-        attributes.delete name
-        idx = attributes.index(other)
-        raise ArgumentError, "unknown #{other} attribute" if idx.nil?
-
-        attributes[idx, 0] = name
+        move_attr(name, before: other)
       end
 
       # Define an attribute, after another one
@@ -217,11 +211,7 @@ module BinStruct
         define_attr name, type, options
         return if other.nil?
 
-        attributes.delete name
-        idx = attributes.index(other)
-        raise ArgumentError, "unknown #{other} attribute" if idx.nil?
-
-        attributes[idx + 1, 0] = name
+        move_attr(name, after: other)
       end
 
       # Remove a previously defined attribute
@@ -229,9 +219,12 @@ module BinStruct
       # @return [void]
       def remove_attr(name)
         attributes.delete(name)
-        @attr_defs.delete(name)
+        attr_def = attr_defs.delete(name)
         undef_method name if method_defined?(name)
         undef_method :"#{name}=" if method_defined?(:"#{name}=")
+        return unless bit_attrs[name]
+
+        attr_def.type.new.bit_methods.each { |meth| undef_method(meth) }
       end
 
       # Update a previously defined attribute
@@ -250,64 +243,95 @@ module BinStruct
         attr_defs[name].options.merge!(options)
       end
 
-      # Define a bit attribute on given attribute
+      # Define a bit attribute
       #   class MyHeader < BinStruct::Struct
-      #     define_attr :flags, BinStruct::Int16
-      #     # define a bit attribute on :flag attribute
+      #     # define a 16-bit attribute named :flag
       #     # flag1, flag2 and flag3 are 1-bit attributes
-      #     # type and stype are 3-bit attributes. reserved is a 6-bit attribute
-      #     define_bit_attributes_on :flags, :flag1, :flag2, :flag3, :type, 3, :stype, 3, :reserved, 7
+      #     # type and stype are 3-bit attributes. reserved is a 7-bit attribute
+      #     define_bit_attr :flags, flag1: 1, flag2: 1, flag3: 1, type: 3, stype: 3, reserved: 7
       #   end
-      # A bit attribute of size 1 bit defines 2 methods:
-      # * +#attr+ which returns a Boolean,
-      # * +#attr=+ which takes and returns a Boolean.
-      # A bit attribute of more bits defines 2 methods:
+      # A bit attribute of size 1 bit defines 3 methods:
+      # * +#attr+ which returns an Integer,
+      # * +#attr?+ which returns a Boolean,
+      # * +#attr=+ which accepts an Integer or a Boolean.
+      # A bit attribute of more bits defines only 2 methods:
       # * +#attr+ which returns an Integer,
-      # * +#attr=+ which takes and returns an Integer.
-      # @param [Symbol] attr attribute name (attribute should be a {BinStruct::Int}
-      #   subclass)
-      # @param [Array] args list of bit attribute names. Name may be followed
-      #   by bit size. If no size is given, 1 bit is assumed.
-      # @raise [ArgumentError] unknown +attr+
+      # * +#attr=+ which takes an Integer.
+      # @param [Symbol] attr attribute name
+      # @param [:big,:little,:native] endian endianess of Integer
+      # @param [Integer] default default value for whole attribute
+      # @param [Hash{Symbol=>Integer}] fields Hash defining fields. Keys are field names, values are field sizes.
       # @return [void]
-      def define_bit_attrs_on(attr, *args)
-        check_existence_of(attr)
-
-        type = attr_defs[attr].type
-        raise TypeError, "#{attr} is not a BinStruct::Int" unless type < Int
-
-        total_size = type.new.nbits
-        idx = total_size - 1
+      # @since 0.3.0
+      def define_bit_attr(attr, endian: :big, default: 0, **fields)
+        width = fields.reduce(0) { |acc, ary| acc + ary.last }
+        bit_attr_klass = BitAttr.create(width: width, endian: endian, **fields)
+        define_attr(attr, bit_attr_klass, default: default)
+        fields.each_key { |field| register_bit_attr_field(attr, field) }
+        bit_attr_klass.new.bit_methods.each do |meth|
+          if meth.to_s.end_with?('=')
+            define_method(meth) { |value| self[attr].send(meth, value) }
+          else
+            define_method(meth) { self[attr].send(meth) }
+          end
+        end
+      end
 
-        until args.empty?
-          arg = args.shift
-          next unless arg.is_a? Symbol
+      # Define a bit attribute, before another attribute
+      # @param [Symbol,nil] other attribute name to create a new one before.
+      #    If +nil+, new attribute is appended.
+      # @param [Symbol] name attribute name to create
+      # @param [:big,:little,:native] endian endianess of Integer
+      # @param [Hash{Symbol=>Integer}] fields Hash defining fields. Keys are field names, values are field sizes.
+      # @return [void]
+      # @since 0.3.0
+      # @see .define_bit_attr
+      def define_bit_attr_before(other, name, endian: :big, **fields)
+        define_bit_attr(name, endian: endian, **fields)
+        return if other.nil?
 
-          size = size_from(args)
+        move_attr(name, before: other)
+      end
 
-          unless attr == :_
-            add_bit_methods(attr, arg, size, total_size, idx)
-            register_bit_attr_size(attr, arg, size)
-          end
+      # Define a bit attribute after another attribute
+      # @param [Symbol,nil] other attribute name to create a new one after.
+      #    If +nil+, new attribute is appended.
+      # @param [Symbol] name attribute name to create
+      # @param [:big,:little,:native] endian endianess of Integer
+      # @param [Hash{Symbol=>Integer}] fields Hash defining fields. Keys are field names, values are field sizes.
+      # @return [void]
+      # @since 0.3.0
+      # @see .define_bit_attr
+      def define_bit_attr_after(other, name, endian: :big, **fields)
+        define_bit_attr(name, endian: endian, **fields)
+        return if other.nil?
 
-          idx -= size
-        end
+        move_attr(name, after: other)
       end
 
-      # Remove all bit attributes defined on +attr+
-      # @param [Symbol] attr attribute defining bit attributes
+      private
+
+      # @param [Symbol] name
+      # @param [Symbol,nil] before
+      # @param [Symbol,nil] after
       # @return [void]
-      def remove_bit_attrs_on(attr)
-        bits = bit_attrs.delete(attr)
-        return if bits.nil?
+      # @raise [ArgumentError] Both +before+ and +after+ are nil, or both are set.
+      def move_attr(name, before: nil, after: nil)
+        move_check_destination(before, after)
 
-        bits.each do |bit, size|
-          undef_method :"#{bit}="
-          undef_method(size == 1 ? "#{bit}?" : bit)
-        end
+        other = before || after
+        attributes.delete(name)
+        idx = attributes.index(other)
+        raise ArgumentError, "unknown #{other} attribute" if idx.nil?
+
+        idx += 1 unless after.nil?
+        attributes[idx, 0] = name
       end
 
-      private
+      def move_check_destination(before, after)
+        raise ArgumentError 'one of before: and after: arguments MUST be set' if before.nil? && after.nil?
+        raise ArgumentError 'only one of before and after argument MUST be set' if !before.nil? && !after.nil?
+      end
 
       def add_methods(name, type)
         define = []
@@ -328,73 +352,15 @@ module BinStruct
         class_eval define.join("\n")
       end
 
-      def add_bit_methods(attr, name, size, total_size, idx)
-        shift = idx - (size - 1)
-
-        if size == 1
-          add_single_bit_methods(attr, name, size, total_size, shift)
-        else
-          add_multibit_methods(attr, name, size, total_size, shift)
-        end
-      end
-
-      def compute_mask(size, shift)
-        ((2**size) - 1) << shift
-      end
-
-      def compute_clear_mask(total_size, mask)
-        ((2**total_size) - 1) & (~mask & ((2**total_size) - 1))
-      end
-
-      def add_single_bit_methods(attr, name, size, total_size, shift)
-        mask = compute_mask(size, shift)
-        clear_mask = compute_clear_mask(total_size, mask)
-
-        class_eval <<-METHODS, __FILE__, __LINE__ + 1
-          def #{name}?                                                  # def bit?
-            val = (self[:#{attr}].to_i & #{mask}) >> #{shift}           #   val = (self[:attr}].to_i & 1}) >> 1
-            val != 0                                                    #   val != 0
-          end                                                           # end
-          def #{name}=(v)                                               # def bit=(v)
-            val = v ? 1 : 0                                             #   val = v ? 1 : 0
-            self[:#{attr}].value = self[:#{attr}].to_i & #{clear_mask}  #   self[:attr].value = self[:attr].to_i & 0xfffd
-            self[:#{attr}].value |= val << #{shift}                     #   self[:attr].value |= val << 1
-          end                                                           # end
-        METHODS
-      end
-
-      def add_multibit_methods(attr, name, size, total_size, shift)
-        mask = compute_mask(size, shift)
-        clear_mask = compute_clear_mask(total_size, mask)
-
-        class_eval <<-METHODS, __FILE__, __LINE__ + 1
-          def #{name}                                                   # def multibit
-            (self[:#{attr}].to_i & #{mask}) >> #{shift}                 #   (self[:attr].to_i & 6) >> 1
-          end                                                           # end
-          def #{name}=(v)                                               # def multibit=(v)
-            self[:#{attr}].value = self[:#{attr}].to_i & #{clear_mask}  #   self[:attr].value = self[:attr].to_i & 0xfff9
-            self[:#{attr}].value |= (v & #{(2**size) - 1}) << #{shift}    #   self[:attr].value |= (v & 3) << 1
-          end                                                           # end
-        METHODS
-      end
-
-      def register_bit_attr_size(attr, name, size)
-        bit_attrs[attr] = {} if bit_attrs[attr].nil?
-        bit_attrs[attr][name] = size
+      def register_bit_attr_field(attr, field)
+        bit_attrs[attr] ||= []
+        bit_attrs[attr] << field
       end
 
       def attr_defs_property_from(attr, property, options)
         attr_defs[attr].send(:"#{property}=", options.delete(property)) if options.key?(property)
       end
 
-      def size_from(args)
-        if args.first.is_a? Integer
-          args.shift
-        else
-          1
-        end
-      end
-
       def check_existence_of(attr)
         raise ArgumentError, "unknown #{attr} attribute for #{self}" unless attr_defs.key?(attr)
       end
@@ -402,7 +368,7 @@ module BinStruct
 
     # Create a new Struct object
     # @param [Hash] options Keys are symbols. They should have name of object
-    #   attributes, as defined by {.define_attr} and by {.define_bit_attrs_on}.
+    #   attributes, as defined by {.define_attr} and by {.define_bit_attr}.
     def initialize(options = {})
       @attributes = {}
       @optional_attributes = {}
@@ -413,8 +379,8 @@ module BinStruct
         initialize_optional(attr)
       end
 
-      self.class.bit_attrs.each_value do |hsh|
-        hsh.each_key do |bit|
+      self.class.bit_attrs.each_value do |bit_fields|
+        bit_fields.each do |bit|
           send(:"#{bit}=", options[bit]) if options[bit]
         end
       end
@@ -435,6 +401,15 @@ module BinStruct
       @attributes[attr] = obj
     end
 
+    # Say if struct has given attribute
+    # @param [Symbol] attr attribute name
+    # @return [Boolean]
+    # @since 0.4.0
+    # @author LemonTree55
+    def attribute?(attr)
+      @attributes.key?(attr)
+    end
+
     # Get all attribute names
     # @return [Array<Symbol>]
     def attributes
@@ -599,26 +574,39 @@ module BinStruct
       end
     end
 
+    # @param [Symbol] attr
+    # @return [void]
     def initialize_optional(attr)
       optional = attr_defs[attr].optional
       @optional_attributes[attr] = optional if optional
     end
 
+    # @return [String]
     def inspect_titleize
       title = self.class.to_s
-      +"-- #{title} #{'-' * (66 - title.length)}\n"
+      "-- #{title} #{'-' * (66 - title.length)}\n"
     end
 
+    # @param [:Symbol] attr
+    # @param [Structable] value
+    # @param [Integer] level
+    # @return [::String]
     def inspect_attribute(attr, value, level = 1)
-      type = value.class.to_s.sub(/.*::/, '')
-      inspect_format(type, attr, value.format_inspect, level)
-    end
-
-    def inspect_format(type, attr, value, level = 1)
       str = inspect_shift_level(level)
-      str << (FMT_ATTR % [type, attr, value])
+      value_lines = value.format_inspect.split("\n")
+      str << (FMT_ATTR % [value.type_name, attr, value_lines.shift])
+      return str if value_lines.empty?
+
+      shift = (FMT_ATTR % ['', '', 'START']).index('START')
+      value_lines.each do |l|
+        str << inspect_shift_level(level)
+        str << (' ' * shift) << l << "\n"
+      end
+      str
     end
 
+    # @param [Integer] level
+    # @return [String]
     def inspect_shift_level(level = 1)
       '  ' * (level + 1)
     end

data/lib/bin_struct/structable.rb

@@ -58,7 +58,7 @@ module BinStruct
     # Format object when inspecting a {Struct} object
     # @return [::String]
     def format_inspect
-      to_human
+      to_human.to_s
     end
   end
 end

data/lib/bin_struct/version.rb

@@ -8,5 +8,5 @@
 
 module BinStruct
   # BinStruct version
-  VERSION = '0.2.1'
+  VERSION = '0.4.0'
 end

data/lib/bin_struct.rb

@@ -25,6 +25,7 @@ end
 require_relative 'bin_struct/structable'
 require_relative 'bin_struct/int'
 require_relative 'bin_struct/enum'
+require_relative 'bin_struct/bit_attr'
 require_relative 'bin_struct/struct'
 require_relative 'bin_struct/length_from'
 require_relative 'bin_struct/abstract_tlv'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bin_struct
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - LemonTree55
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-25 00:00:00.000000000 Z
+date: 2025-02-13 00:00:00.000000000 Z
 dependencies: []
 description: 'BinStruct is a binary dissector and generator. It eases manipulating
   complex binary data.
@@ -26,6 +26,7 @@ files:
 - lib/bin_struct.rb
 - lib/bin_struct/abstract_tlv.rb
 - lib/bin_struct/array.rb
+- lib/bin_struct/bit_attr.rb
 - lib/bin_struct/cstring.rb
 - lib/bin_struct/enum.rb
 - lib/bin_struct/int.rb
@@ -57,7 +58,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="