bin_struct 0.5.1 → 0.5.3

data/lib/bin_struct/struct.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of BinStruct
-# see https://github.com/lemontree55/bin_struct for more informations
+# see https://codeberg.org/lemontree55/bin_struct for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -115,15 +115,17 @@ module BinStruct
     FMT_ATTR = "%14s %16s: %s\n"
 
     class << self
+      # @private
       # Get attribute definitions for this class.
-      # @return [Hash]
+      # @return [Hash{Symbol=>StructDef}]
       attr_reader :attr_defs
+      # @private
       # Get bit attribute defintions for this class
-      # @return [Hash{Symbol=>Array[Symbol]}]
+      # @return [Hash{Symbol=>Array<Symbol>}]
       attr_reader :bit_attrs
 
       # On inheritage, create +@attr_defs+ class variable
-      # @param [Class] klass
+      # @param klass [Class]
       # @return [void]
       def inherited(klass)
         super
@@ -149,6 +151,27 @@ module BinStruct
       end
 
       # Define an attribute in class
+      # @param name [Symbol] name of the attribute to define
+      # @param type [Structable] class or instance
+      #   +:builder+ option is not set.
+      # @!macro [new] x_attr_options
+      #   @param options [Hash{Symbol=>Object}] Unrecognized options are passed to object builder if
+      #   @option options [Object] :default default value. May be a proc. This lambda
+      #     take one argument: the caller object.
+      #   @option options [Lambda] :builder lambda to construct this attribute.
+      #     Parameters to this lambda is the caller object and the attribute type class.
+      #   @option options [Lambda] :optional define this attribute as optional. Given lambda
+      #     is used to known if this attribute is present or not. Parameter to this lambda is
+      #     the being defined Struct object.
+      # @!macro x_attr_options
+      # @return [void]
+      # @example
+      #   class MyClass < BinStruct::Struct
+      #     def initialize(parent, options={})
+      #       super(options)
+      #       @parent = parent
+      #     end
+      #   end
       #   class BinaryStruct < BinStruct::Struct
       #     # 8-bit value
       #     define_attr :value1, BinStruct::Int8
@@ -159,20 +182,9 @@ module BinStruct
       #   end
       #
       #   bs = BinaryStruct.new
-      #   bs[value1]   # => BinStruct::Int8
-      #   bs.value1    # => Integer
-      # @param [Symbol] name attribute name
-      # @param [Structable] type class or instance
-      # @param [Hash] options Unrecognized options are passed to object builder if
-      #   +:builder+ option is not set.
-      # @option options [Object] :default default value. May be a proc. This lambda
-      #   take one argument: the caller object.
-      # @option options [Lambda] :builder lambda to construct this attribute.
-      #   Parameters to this lambda is the caller object and the attribute type class.
-      # @option options [Lambda] :optional define this attribute as optional. Given lambda
-      #   is used to known if this attribute is present or not. Parameter to this lambda is
-      #   the being defined Struct object.
-      # @return [void]
+      #   bs[:value1].class   # => BinStruct::Int8
+      #   bs.value1.class     # => Integer
+      #   bs.value1           # => 0
       def define_attr(name, type, options = {})
         attributes << name
         attr_defs[name] = StructDef.new(type,
@@ -185,11 +197,11 @@ module BinStruct
       end
 
       # Define a attribute, before another one
-      # @param [Symbol,nil] other attribute name to create a new one before. If +nil+,
+      # @param other [Symbol,nil] attribute name to create a new one before. If +nil+,
       #    new attribute is appended.
-      # @param [Symbol] name attribute name to create
-      # @param [Structable] type class or instance
-      # @param [Hash] options See {.define_attr}.
+      # @param name [Symbol] attribute name to create
+      # @param type [Structable] class or instance
+      # @!macro x_attr_options
       # @return [void]
       # @see .define_attr
       def define_attr_before(other, name, type, options = {})
@@ -200,11 +212,11 @@ module BinStruct
       end
 
       # Define an attribute, after another one
-      # @param [Symbol,nil] other attribute name to create a new one after. If +nil+,
+      # @param other [Symbol,nil] attribute name to create a new one after. If +nil+,
       #    new attribute is appended.
-      # @param [Symbol] name attribute name to create
-      # @param [Structable] type class or instance
-      # @param [Hash] options See {.define_attr}.
+      # @param name [Symbol] attribute name to create
+      # @param type [Structable] class or instance
+      # @!macro x_attr_options
       # @return [void]
       # @see .define_attr
       def define_attr_after(other, name, type, options = {})
@@ -215,7 +227,7 @@ module BinStruct
       end
 
       # Remove a previously defined attribute
-      # @param [Symbol] name
+      # @param name [Symbol]
       # @return [void]
       def remove_attr(name)
         attributes.delete(name)
@@ -228,8 +240,8 @@ module BinStruct
       end
 
       # Update a previously defined attribute
-      # @param [Symbol] name attribute name to create
-      # @param [Hash] options See {.define_attr}.
+      # @param name [Symbol] attribute name to create
+      # @!macro x_attr_options
       # @return [void]
       # @see .define_attr
       # @raise [ArgumentError] unknown attribute
@@ -243,13 +255,7 @@ module BinStruct
         attr_defs[name].options.merge!(options)
       end
 
-      # Define a bit attribute
-      #   class MyHeader < BinStruct::Struct
-      #     # 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 7-bit attribute
-      #     define_bit_attr :flags, flag1: 1, flag2: 1, flag3: 1, type: 3, stype: 3, reserved: 7
-      #   end
+      # Define a bit attribute.
       # A bit attribute of size 1 bit defines 3 methods:
       # * +#attr+ which returns an Integer,
       # * +#attr?+ which returns a Boolean,
@@ -257,12 +263,21 @@ module BinStruct
       # A bit attribute of more bits defines only 2 methods:
       # * +#attr+ which returns an Integer,
       # * +#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.
+      # @param attr [Symbol] attribute name
+      # @param endian [Symbol] endianess of Integer (:big, :little or :native)
+      # @param default [Integer] default value for whole attribute
+      # @param fields [Hash{Symbol=>Integer}] Hash defining fields. Keys are field names, values are field sizes.
       # @return [void]
       # @since 0.3.0
+      # @example
+      #   class MyHeader < BinStruct::Struct
+      #     # 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 7-bit attribute
+      #     define_bit_attr :flags, flag1: 1, flag2: 1, flag3: 1, type: 3, stype: 3, reserved: 7
+      #   end
+      #   my_header = MyHeader.new(flag1: true)
+      #   my_header.flags   #=> 0x8000
       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)
@@ -280,11 +295,11 @@ module BinStruct
       end
 
       # Define a bit attribute, before another attribute
-      # @param [Symbol,nil] other attribute name to create a new one before.
+      # @param other [Symbol,nil] 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.
+      # @param name [Symbol] attribute name to create
+      # @param endian [Symbol] endianess of Integer (:big, :little or :native)
+      # @param fields [Hash{Symbol=>Integer}] Hash defining fields. Keys are field names, values are field sizes.
       # @return [void]
       # @since 0.3.0
       # @see .define_bit_attr
@@ -296,11 +311,11 @@ module BinStruct
       end
 
       # Define a bit attribute after another attribute
-      # @param [Symbol,nil] other attribute name to create a new one after.
+      # @param other [Symbol,nil] 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.
+      # @param name [Symbol] attribute name to create
+      # @param endian [Symbol] endianess of Integer (:big, :little or :native)
+      # @param fields [Hash{Symbol=>Integer}] Hash defining fields. Keys are field names, values are field sizes.
       # @return [void]
       # @since 0.3.0
       # @see .define_bit_attr
@@ -313,9 +328,9 @@ module BinStruct
 
       private
 
-      # @param [Symbol] name
-      # @param [Symbol,nil] before
-      # @param [Symbol,nil] after
+      # @param name [Symbol]
+      # @param before [Symbol,nil]
+      # @param after [Symbol,nil]
       # @return [void]
       # @raise [ArgumentError] Both +before+ and +after+ are nil, or both are set.
       def move_attr(name, before: nil, after: nil)
@@ -330,11 +345,19 @@ module BinStruct
         attributes[idx, 0] = name
       end
 
+      # @param before [Symbol,nil]
+      # @param after [Symbol,nil]
+      # @return [void]
+      # @raise [ArgumentError] +before+ and +after+ are both nil or set
       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
 
+      # Generate Ruby code to define +name+ accessor
+      # @param name [Symbol]
+      # @param type [Class]
+      # @return [Array<String>]
       def add_methods(name, type)
         define = []
         if type < Enum
@@ -349,28 +372,40 @@ module BinStruct
                     'end'
         end
 
-        define.delete_at(1) if instance_methods.include?(:"#{name}=")
-        define.delete_at(0) if instance_methods.include?(name)
+        define.delete_at(1) if method_defined?(:"#{name}=")
+        define.delete_at(0) if method_defined?(name)
         class_eval define.join("\n")
       end
 
+      # Define a bit attribute on +self+
+      # @param attr [Symbol]
+      # @param field [Hash{Symbol=>Integer}]
+      # @return [void]
       def register_bit_attr_field(attr, field)
         bit_attrs[attr] ||= []
         bit_attrs[attr] << field
       end
 
+      # Add a property on given +attr+ from +options+
+      # @param attr [Symbol]
+      # @param property [Symbol] :default, :builder or :optional
+      # @!macro x_attr_options
+      # @return [void]
       def attr_defs_property_from(attr, property, options)
         attr_defs[attr].send(:"#{property}=", options.delete(property)) if options.key?(property)
       end
 
+      # @param attr [Symbol]
+      # @return [void]
+      # @raise [ArgumentError] +attr+ is unknown
       def check_existence_of(attr)
         raise ArgumentError, "unknown #{attr} attribute for #{self}" unless attr_defs.key?(attr)
       end
     end
 
     # 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_attr}.
+    # @param options [Hash{Symbol=>Object}] Keys are attributes names, as defined by {.define_attr} and by
+    #   {.define_bit_attr}. Values are values to set to attributes, as Ruby values (i.e Integer, String, etc...)
     def initialize(options = {})
       @attributes = {}
       @optional_attributes = {}
@@ -389,22 +424,22 @@ module BinStruct
     end
 
     # Get attribute object
-    # @param [Symbol] attr attribute name
+    # @param attr [Symbol] attribute name
     # @return [Structable]
     def [](attr)
       @attributes[attr]
     end
 
     # Set attribute object
-    # @param [Symbol] attr attribute name
-    # @param [Object] obj
+    # @param attr [Symbol] attribute name
+    # @param obj [Object]
     # @return [Object]
     def []=(attr, obj)
       @attributes[attr] = obj
     end
 
     # Say if struct has given attribute
-    # @param [Symbol] attr attribute name
+    # @param attr [Symbol] attribute name
     # @return [Boolean]
     # @since 0.4.0
     # @author LemonTree55
@@ -425,13 +460,14 @@ module BinStruct
     end
 
     # Say if this attribue is optional
-    # @param [Symbol] attr attribute name
+    # @param attr [Symbol] attribute name
     # @return [Boolean]
     def optional?(attr)
       @optional_attributes.key?(attr)
     end
 
     # Say if an optional attribute is present
+    # @param attr [Symbol]
     # @return [Boolean]
     def present?(attr)
       return true unless optional?(attr)
@@ -440,16 +476,17 @@ module BinStruct
     end
 
     # Populate object from a binary string
-    # @param [String] str
+    # @param str [String]
     # @return [Struct] self
     def read(str)
       return self if str.nil?
 
       start = 0
+      str = str.b
       attributes.each do |attr|
         next unless present?(attr)
 
-        obj = self[attr].read(str.b[start..])
+        obj = self[attr].read(str[start..])
         start += self[attr].sz
         self[attr] = obj unless obj == self[attr]
       end
@@ -491,13 +528,13 @@ module BinStruct
     end
 
     # Return object as a hash
-    # @return [Hash] keys: attributes, values: attribute values
+    # @return [Hash] keys: attributes, values: attribute human values
     def to_h
       attributes.to_h { |attr| [attr, @attributes[attr].to_human] }
     end
 
     # Get offset of given attribute in {Struct}.
-    # @param [Symbol] attr attribute name
+    # @param attr [Symbol] attribute name
     # @return [Integer]
     # @raise [ArgumentError] unknown attribute
     def offset_of(attr)
@@ -513,7 +550,7 @@ module BinStruct
     end
 
     # Get bit attributes definition for given attribute.
-    # @param [Symbol] attr attribute defining bit attributes
+    # @param attr [Symbol] attribute defining bit attributes
     # @return [Hash,nil] keys: bit attributes, values: their size in bits
     def bits_on(attr)
       self.class.bit_attrs[attr]
@@ -521,33 +558,37 @@ module BinStruct
 
     private
 
-    # Deeply duplicate +@attributes+
-    # @return [void]
-    def initialize_copy(_other)
-      attributes = {}
-      @attributes.each { |k, v| attributes[k] = v.dup }
-      @attributes = attributes
+    # Deeply duplicate +@attributes+ and +@optional_attributes+
+    def initialize_copy(*)
+      @attributes = @attributes.transform_values(&:dup)
+      @optional_attributes = @optional_attributes.dup
     end
 
     # Force str to binary encoding
-    # @param [String] str
+    # @param str [String]
     # @return [String]
     # @deprecated Prefer use of Ruby's {::String#b}
     def force_binary(str)
       BinStruct.force_binary(str)
     end
 
-    # @param [Symbol] attr attribute name
+    # @param attr [Symbol] attribute name
     # @return [Boolean] +true= if #from_human and #to_human are both defined for given attribute
     def to_and_from_human?(attr)
       self[attr].respond_to?(:to_human) && self[attr].respond_to?(:from_human)
     end
 
+    # Return attribute definitions
+    # @return [Hash{Symbol=>StructDef}]
     def attr_defs
       self.class.attr_defs
     end
 
     # rubocop:disable Metrics/AbcSize
+
+    # Build attribute named +attr+
+    # @param attr [Symbol]
+    # @return [void]
     def build_attribute(attr)
       type = attr_defs[attr].type
 
@@ -561,6 +602,10 @@ module BinStruct
     end
     # rubocop:enable Metrics/AbcSize
 
+    # Initialize attribute with given value
+    # @param attr [Symbol]
+    # @param val [Object] value to set
+    # @return [void]
     def initialize_value(attr, val)
       type = attr_defs[attr].type
       default = attr_defs[attr].default
@@ -576,7 +621,7 @@ module BinStruct
       end
     end
 
-    # @param [Symbol] attr
+    # @param attr [Symbol]
     # @return [void]
     def initialize_optional(attr)
       optional = attr_defs[attr].optional
@@ -589,9 +634,9 @@ module BinStruct
       "-- #{title} #{'-' * (66 - title.length)}\n"
     end
 
-    # @param [:Symbol] attr
-    # @param [Structable] value
-    # @param [Integer] level
+    # @param attr [Symbol]
+    # @param value [Structable]
+    # @param level [Integer]
     # @return [::String]
     def inspect_attribute(attr, value, level = 1)
       str = inspect_shift_level(level)
@@ -607,7 +652,7 @@ module BinStruct
       str
     end
 
-    # @param [Integer] level
+    # @param level [Integer]
     # @return [String]
     def inspect_shift_level(level = 1)
       '  ' * (level + 1)

data/lib/bin_struct/structable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of BinStruct
-# see https://github.com/lemontree55/bin_struct for more informations
+# see https://codeberg.org/lemontree55/bin_struct for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -26,7 +26,7 @@ module BinStruct
     # These methods are defined for documentation.
 
     # Populate object from a binary string
-    # @param [::String] str
+    # @param str [::String]
     # @return [self]
     # @abstract subclass should overload it.
     def read(str)

data/lib/bin_struct/version.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # This file is part of BinStruct
-# see https://github.com/lemontree55/bin_struct for more informations
+# see https://codeberg.org/lemontree55/bin_struct for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
 
 module BinStruct
   # BinStruct version
-  VERSION = '0.5.1'
+  VERSION = '0.5.3'
 end

data/lib/bin_struct.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of BinStruct
-# see https://github.com/lemontree55/bin_struct for more informations
+# see https://codeberg.org/lemontree55/bin_struct for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -39,7 +39,7 @@ module BinStruct
   class Error < StandardError; end
 
   # Force binary encoding for +str+
-  # @param [String] str
+  # @param str [String]
   # @return [String] binary encoded string
   # @deprecated Use {::String#b} instead of this method
   def self.force_binary(str)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bin_struct
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - LemonTree55
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-21 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies: []
 description: 'BinStruct is a binary dissector and generator. It eases manipulating
   complex binary data.
@@ -37,13 +37,14 @@ files:
 - lib/bin_struct/struct.rb
 - lib/bin_struct/structable.rb
 - lib/bin_struct/version.rb
-homepage: https://github.com/lemontree55/bin_struct
+homepage: https://codeberg.org/lemontree55/bin_struct
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/lemontree55/bin_struct
-  source_code_uri: https://github.com/lemontree55/bin_struct
-  bug_tracker_uri: https://github.com/lemontree55/bin_struct/issues
+  homepage_uri: https://codeberg.org/lemontree55/bin_struct
+  source_code_uri: https://codeberg.org/lemontree55/bin_struct
+  bug_tracker_uri: https://codeberg.org/lemontree55/bin_struct/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options:
 - "--title"
@@ -58,14 +59,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.15
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Binary dissector and generator