bin_struct 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5412a49a789a410de1120e6cbcbf55a7bd07783846a4e2f4cf9bc14eac76bfd
-  data.tar.gz: 9ae9eabeb7c3fe672e8ba229bc116c9a72bf26c7b1fd9eace52bb0f8036f0fea
+  metadata.gz: 5a90f75409d497521af8957e89577a4e8b7c14211e5343aa9126a71ef413d759
+  data.tar.gz: b07e2bf73d2cb1f4b7be4340944cd52df4382fc94f171607357adf10ddc7a914
 SHA512:
-  metadata.gz: 8fa11b03a84dca208c63d23358187b575982f5331d5c1da7fdd7c2343505ed932bc884a440b23589943d4eb5d9f78f942d77e8b271bef919277536a0ab9ab3b7
-  data.tar.gz: ecd4e847f6dc8392b759b8ef7a23df05191c697bb471a1ef8c685e12009be544b2dac4f8d77a944190a607b26216d90bd034742c95f9b2034b2701c4ec726602
+  metadata.gz: 6acd7aeb0516bf6692ae5971aecb10c8ae685936f24302d909ff16f055118a68588876409819d0ba966e4f3a7b524b194e58713bfb0ccaef95eb542fca221bb3
+  data.tar.gz: 790bf0b81cef084c030e0412731e3b0b852815fa1f66f5d28564278579e12b7e3fd3ef3674c6f36dd32bc792e1c248f7f20b3f65f505d3193f370b2d8c6f1d88

data/CHANGELOG.md

@@ -1,5 +1,22 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2024-07-13
+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.2.0 - 2024-07-21
+
+### Changed
+
+- `BinStruct::Fields` renamed into `BinStruct::Struct`, and `*field*` methods are renamed into `*attr*` or `*attributes*`.
+- `BinStruct::Struct#inspect`: add a title line.
+
+### Fixed
+
+- Fix `BinStruct::ArrayOfInt#read_from_array` by using `value:` option.
+- Fix `BinStruct::IntString#calc_length` by using `#from_human` instead of `#read`.
+- `BinStruct::String#to_s`: force binary encoding.
+- `BinStruct::String#<<`: force binary encoding on argument before catenating.
+
+## 0.1.0 - 2024-07-13
 
 - Initial release

data/README.md

@@ -1,6 +1,6 @@
 # BinStruct
 
-BinStruct provides a simple ways to create and dissect binary data. It is an extraction from [PacketGen](https://github.com/lemontree55/packetgen) fields.
+BinStruct provides a simple way to create and dissect binary data. It is an extraction from [PacketGen](https://github.com/lemontree55/packetgen) 3.x Fields.
 
 ## Installation
 

data/lib/bin_struct/abstract_tlv.rb

@@ -2,28 +2,28 @@
 
 # This file is part of BinStruct
 # See https://github.com/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.
 
+# BinStruct module
+# @author LemonTree55
 module BinStruct
-  # This class is an abstract class to define type-length-value data.
-  #
-  # This class supersedes {TLV} class, which is not well defined on some corner
-  # cases.
+  # @abstract Base class to define type-length-value data.
   #
   # ===Usage
   # To simply define a new TLV class, do:
   #   MyTLV = PacketGen::Types::AbstractTLV.create
   #   MyTLV.define_type_enum 'one' => 1, 'two' => 2
-  # This will define a new +MyTLV+ class, subclass of {Fields}. This class will
-  # define 3 fields:
+  # This will define a new +MyTLV+ class, subclass of {AbstractTLV}. This class will
+  # define 3 attributes:
   # * +#type+, as a {Int8Enum} by default,
   # * +#length+, as a {Int8} by default,
   # * and +#value+, as a {String} by default.
   # +.define_type_enum+ is, here, necessary to define enum hash to be used
   # for +#type+ accessor, as this one is defined as an {Enum}.
   #
-  # This class may then be used as older {TLV} class:
+  # This new defined class may now be easily used:
   #   tlv = MyTLV.new(type: 1, value: 'abcd')  # automagically set #length from value
   #   tlv.type        #=> 1
   #   tlv.human_type  #=> 'one'
@@ -31,7 +31,7 @@ module BinStruct
   #   tlv.value       #=> "abcd"
   #
   # ===Advanced usage
-  # Each field's type may be changed at generating TLV class:
+  # 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)
@@ -42,7 +42,7 @@ module BinStruct
   #   tlv.to_s        #=> "\x00\x01\x00\x04\x01\x02\x03\x04"
   #
   # Some aliases may also be defined. For example, to create a TLV type
-  # whose +type+ field should be named +code+:
+  # 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 })
@@ -52,20 +52,20 @@ module BinStruct
   #   tlv.length      #=> 4
   #   tlv.value       #=> 'abcd'
   #
-  # @author Sylvain Daubert
-  # @since 3.1.0
-  # @since 3.1.1 add +:aliases+ keyword to {#initialize}
-  class AbstractTLV < Fields
-    include Fieldable
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
+  class AbstractTLV < Struct
+    include Structable
 
     # @private
-    FIELD_TYPES = { 'T' => :type, 'L' => :length, 'V' => :value }.freeze
+    ATTR_TYPES = { 'T' => :type, 'L' => :length, 'V' => :value }.freeze
 
     class << self
+      # Aliases defined in {.create}
       # @return [Hash]
       attr_accessor :aliases
       # @private
-      attr_accessor :field_in_length
+      attr_accessor :attr_in_length
 
       # rubocop:disable Metrics/ParameterLists
 
@@ -73,14 +73,12 @@ module BinStruct
       # @param [Class] type_class Class to use for +type+
       # @param [Class] length_class Class to use for +length+
       # @param [Class] value_class Class to use for +value+
-      # @param [String] field_order give field order. Each character in [T,L,V] MUST be present once,
+      # @param [::String] attr_order gives attribute order. Each character in [T,L,V] MUST be present once,
       #   in the desired order.
-      # @param [String] field_in_length give fields to compute length on.
+      # @param [::String] attr_in_length give attributes to compute length on.
       # @return [Class]
-      # @since 3.1.4 Add +header_in_length+ parameter
-      # @since 3.3.1 Add +field_order+ and +field_in_length' parameters. Deprecate +header_in_length+ parameter.
       def create(type_class: Int8Enum, length_class: Int8, value_class: String,
-                 aliases: {}, field_order: 'TLV', field_in_length: 'V')
+                 aliases: {}, attr_order: 'TLV', attr_in_length: 'V')
         unless equal?(AbstractTLV)
           raise Error,
                 '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV'
@@ -88,11 +86,11 @@ module BinStruct
 
         klass = Class.new(self)
         klass.aliases = aliases
-        klass.field_in_length = field_in_length
+        klass.attr_in_length = attr_in_length
 
-        check_field_in_length(field_in_length)
-        check_field_order(field_order)
-        generate_fields(klass, field_order, type_class, length_class, value_class)
+        check_attr_in_length(attr_in_length)
+        check_attr_order(attr_order)
+        generate_attributes(klass, attr_order, type_class, length_class, value_class)
 
         aliases.each do |al, orig|
           klass.instance_eval do
@@ -106,87 +104,93 @@ module BinStruct
       # rubocop:enable Metrics/ParameterLists
 
       # @!attribute type
-      #   @abstract Type attribute for real TLV class
+      #   @abstract
+      #   Type attribute for real TLV class
       #   @return [Integer]
       # @!attribute length
-      #   @abstract Length attribute for real TLV class
+      #   @abstract
+      #   Length attribute for real TLV class
       #   @return [Integer]
       # @!attribute value
-      #   @abstract Value attribute for real TLV class
+      #   @abstract
+      #   Value attribute for real TLV class
       #   @return [Object]
 
       # @abstract Should only be called on real TLV classes, created by {.create}.
-      # Set enum hash for {#type} field.
-      # @param [Hash{String, Symbol => Integer}] hsh enum hash
+      # Set enum hash for {#type} attribute.
+      # @param [Hash{::String, Symbol => Integer}] hsh enum hash
       # @return [void]
       def define_type_enum(hsh)
-        field_defs[:type][:options][:enum].clear
-        field_defs[:type][:options][:enum].merge!(hsh)
+        attr_defs[:type][:options][:enum].clear
+        attr_defs[:type][:options][:enum].merge!(hsh)
       end
 
       # @abstract Should only be called on real TLV classes, created by {.create}.
-      # Set default value for {#type} field.
-      # @param [Integer,String,Symbol,nil] default default value from +hsh+ for type
+      # Set default value for {#type} attribute.
+      # @param [Integer,::String,Symbol,nil] default default value from +hsh+ for type
       # @return [void]
-      # @since 3.4.0
       def define_type_default(default)
-        field_defs[:type][:default] = default
+        attr_defs[:type][:default] = default
       end
 
       private
 
-      def check_field_in_length(field_in_length)
-        return if /^[TLV]{1,3}$/.match?(field_in_length)
+      def check_attr_in_length(attr_in_length)
+        return if /^[TLV]{1,3}$/.match?(attr_in_length)
 
-        raise 'field_in_length must only contain T, L and/or V characters'
+        raise 'attr_in_length must only contain T, L and/or V characters'
       end
 
-      def check_field_order(field_order)
-        if field_order.match(/^[TLV]{3,3}$/) &&
-           (field_order[0] != field_order[1]) &&
-           (field_order[0] != field_order[2]) &&
-           (field_order[1] != field_order[2])
+      def check_attr_order(attr_order)
+        if attr_order.match(/^[TLV]{3,3}$/) &&
+           (attr_order[0] != attr_order[1]) &&
+           (attr_order[0] != attr_order[2]) &&
+           (attr_order[1] != attr_order[2])
           return
         end
 
-        raise 'field_order must contain all three letters TLV, each once'
+        raise 'attr_order must contain all three letters TLV, each once'
       end
 
-      def generate_fields(klass, field_order, type_class, length_class, value_class)
-        field_order.each_char do |field_type|
-          case field_type
+      def generate_attributes(klass, attr_order, type_class, length_class, value_class)
+        attr_order.each_char do |attr_type|
+          case attr_type
           when 'T'
             if type_class < Enum
-              klass.define_field(:type, type_class, enum: {})
+              klass.define_attr(:type, type_class, enum: {})
             else
-              klass.define_field(:type, type_class)
+              klass.define_attr(:type, type_class)
             end
           when 'L'
-            klass.define_field(:length, length_class)
+            klass.define_attr(:length, length_class)
           when 'V'
-            klass.define_field(:value, value_class)
+            klass.define_attr(:value, value_class)
           end
         end
       end
     end
 
     # @!attribute type
-    #   @abstract Type attribute
+    #   @abstract
+    #   Type attribute
     #   @return [Integer]
     # @!attribute length
-    #   @abstract Length
+    #   @abstract
+    #   Length attribute
     #   @return [Integer]
     # @!attribute value
-    #   @abstract Value attribute
+    #   @abstract
+    #   Value attribute
     #   @return [Object]enum
 
     # @abstract Should only be called on real TLV classes, created by {.create}.
+    # Return a new instance of a real TLV class.
     # @param [Hash] options
     # @option options [Integer] :type
     # @option options [Integer] :length
     # @option options [Object] :value
     def initialize(options = {})
-      @field_in_length = self.class.field_in_length
+      @attr_in_length = self.class.attr_in_length
       self.class.aliases.each do |al, orig|
         options[orig] = options[al] if options.key?(al)
       end
@@ -199,17 +203,17 @@ module BinStruct
 
     # @abstract Should only be called on real TLV class instances.
     # Populate object from a binary string
-    # @param [String,nil] str
-    # @return [Fields] self
+    # @param [::String,nil] str
+    # @return [AbstractTLV] self
     def read(str)
       return self if str.nil?
 
       idx = 0
-      fields.each do |field_name|
-        field = self[field_name]
-        length = field_name == :value ? real_length : field.sz
-        field.read(str[idx, length])
-        idx += field.sz
+      attributes.each do |attr_name|
+        attr = self[attr_name]
+        length = attr_name == :value ? real_length : attr.sz
+        attr.read(str[idx, length])
+        idx += attr.sz
       end
 
       self
@@ -219,7 +223,6 @@ module BinStruct
     # Set +value+. May set +length+ if value is a {Types::String}.
     # @param [Object] val
     # @return [Object]
-    # @since 3.4.0 Base on field's +#from_human+ method
     def value=(val)
       if val.is_a?(self[:value].class)
         self[:value] = val
@@ -233,27 +236,26 @@ module BinStruct
 
     # @abstract Should only be called on real TLV class instances.
     # Get human-readable type
-    # @return [String]
+    # @return [::String]
     def human_type
       self[:type].to_human.to_s
     end
 
     # @abstract Should only be called on real TLV class instances.
-    # @return [String]
+    # @return [::String]
     def to_human
       my_value = self[:value].is_a?(String) ? self[:value].inspect : self[:value].to_human
       'type:%s,length:%u,value:%s' % [human_type, length, my_value]
     end
 
     # Calculate length
-    # @return [void]
-    # @since 3.4.0
+    # @return [Integer]
     def calc_length
-      fil = @field_in_length
+      ail = @attr_in_length
 
       length = 0
-      fil.each_char do |field_type|
-        length += self[FIELD_TYPES[field_type]].sz
+      ail.each_char do |attr_type|
+        length += self[ATTR_TYPES[attr_type]].sz
       end
       self.length = length
     end
@@ -262,8 +264,8 @@ module BinStruct
 
     def real_length
       length = self.length
-      length -= self[:type].sz if @field_in_length.include?('T')
-      length -= self[:length].sz if @field_in_length.include?('L')
+      length -= self[:type].sz if @attr_in_length.include?('T')
+      length -= self[:length].sz if @attr_in_length.include?('L')
       length
     end
   end

data/lib/bin_struct/array.rb

@@ -9,10 +9,15 @@
 require 'forwardable'
 
 module BinStruct
-  # @abstract Base class to define set of {Fields} subclasses.
+  # @abstract Base class to define set of {Struct} subclasses.
+  #
+  # This class mimics regular Ruby Array, but it is {Structable} and responds to {LengthFrom}.
+  #
+  # Concrete subclasses may define 2 private methods:
+  #
   # == #record_from_hash
-  # Subclasses should define private method +#record_from_hash+. This method
-  # is called by {#push} to add an object to the set.
+  # This method
+  # is called by {#push} and {#<<} to add an object to the set.
   #
   # A default method is defined by {Array}: it calls constructor of class defined
   # by {.set_of}.
@@ -24,16 +29,17 @@ module BinStruct
   #
   # Default behaviour of this method is to return argument's class.
   #
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Array
     extend Forwardable
     include Enumerable
-    include Fieldable
+    include Structable
     include LengthFrom
 
     # @!method [](index)
     #   Return the element at +index+.
-    #   @param [integer] index
+    #   @param [Integer] index
     #   @return [Object]
     # @!method clear
     #   Clear array.
@@ -41,10 +47,10 @@ module BinStruct
     # @!method each
     #   Calls the given block once for each element in self, passing that
     #   element as a parameter. Returns the array itself.
-    #   @return [Array]
+    #   @return [::Array]
     # @method empty?
     #   Return +true+ if contains no element.
-    #   @return [Booelan]
+    #   @return [Boolean]
     # @!method first
     #   Return first element
     #   @return [Object]
@@ -58,14 +64,13 @@ module BinStruct
     alias length size
 
     # Separator used in {#to_human}.
-    # May be ovverriden by subclasses
+    # May be overriden by subclasses
     HUMAN_SEPARATOR = ','
 
     # rubocop:disable Naming/AccessorMethodName
     class << self
       # Get class set with {.set_of}.
       # @return [Class]
-      # @since 3.0.0
       def set_of_klass
         @klass
       end
@@ -89,10 +94,13 @@ module BinStruct
 
     # Initialize array for copy:
     # * duplicate internal array.
+    # @note Associated counter, if any, is not duplicated
     def initialize_copy(_other)
       @array = @array.dup
     end
 
+    # Check equality. Equality is checked on underlying array.
+    # @return [Boolean]
     def ==(other)
       @array == case other
                 when Array
@@ -118,7 +126,7 @@ module BinStruct
       deleted
     end
 
-    # Delete element at +index+.
+    # Delete element at +index+. Update associated counter if any
     # @param [Integer] index
     # @return [Object,nil] deleted object
     def delete_at(index)
@@ -129,13 +137,14 @@ module BinStruct
 
     # @abstract depend on private method +#record_from_hash+ which should be
     #   declared by subclasses.
-    # Add an object to this array
+    # Add an object to this array. Do not update associated counter.
     # @param [Object] obj type depends on subclass
-    # @return [Array] self
+    # @return [self]
+    # @see #<<
     def push(obj)
       obj = case obj
             when Hash
-              record_from_hash obj
+              record_from_hash(obj)
             else
               obj
             end
@@ -147,15 +156,15 @@ module BinStruct
     #   declared by subclasses.
     # Add an object to this array, and increment associated counter, if any
     # @param [Object] obj type depends on subclass
-    # @return [Array] self
+    # @return [self]
     def <<(obj)
-      push obj
+      push(obj)
       @counter&.from_human(@counter.to_i + 1)
       self
     end
 
     # Populate object from a string or from an array of hashes
-    # @param [String, Array<Hash>] data
+    # @param [::String, ::Array<Hash>] data
     # @return [self]
     def read(data)
       clear
@@ -174,20 +183,20 @@ module BinStruct
       to_s.size
     end
 
-    # Return an Array
+    # Return underlying Ruby Array
     # @return [::Array]
     def to_a
       @array
     end
 
     # Get binary string
-    # @return [String]
+    # @return [::String]
     def to_s
       @array.map(&:to_s).join
     end
 
     # Get a human readable string
-    # @return [String]
+    # @return [::String]
     def to_human
       @array.map(&:to_human).join(self.class::HUMAN_SEPARATOR)
     end
@@ -251,36 +260,36 @@ module BinStruct
       return self if ary.empty?
 
       ary.each do |i|
-        self << self.class.set_of_klass.new(i)
+        self << self.class.set_of_klass.new(value: i)
       end
     end
   end
 
-  # Specialized array to handle serie of {Int8}.
+  # Specialized {Array} to handle serie of {Int8}.
   class ArrayOfInt8 < Array
     include ArrayOfIntMixin
     set_of Int8
   end
 
-  # Specialized array to handle serie of {Int16}.
+  # Specialized {Array} to handle serie of {Int16}.
   class ArrayOfInt16 < Array
     include ArrayOfIntMixin
     set_of Int16
   end
 
-  # Specialized array to handle serie of {Int16le}.
+  # Specialized {Array} to handle serie of {Int16le}.
   class ArrayOfInt16le < Array
     include ArrayOfIntMixin
     set_of Int16le
   end
 
-  # Specialized array to handle serie of {Int32}.
+  # Specialized {Array} to handle serie of {Int32}.
   class ArrayOfInt32 < BinStruct::Array
     include ArrayOfIntMixin
     set_of Int32
   end
 
-  # Specialized array to handle serie of {Int32le}.
+  # Specialized {Array} to handle serie of {Int32le}.
   class ArrayOfInt32le < BinStruct::Array
     include ArrayOfIntMixin
     set_of Int32le

data/lib/bin_struct/cstring.rb

@@ -10,19 +10,68 @@ require 'forwardable'
 
 module BinStruct
   # This class handles null-terminated strings (aka C strings).
-  # @author Sylvain Daubert
-  # @since 3.1.6 no more a subclass or regular String
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class CString
     extend Forwardable
-    include Fieldable
-
+    include Structable
+
+    # @!method [](index)
+    #   @overload [](index)
+    #     Return the character at +index+.
+    #     @param [Integer] index
+    #   @overload [](start, length)
+    #     Return the substring starting at +start+ with +length+ length.
+    #     @param [Integer] start
+    #     @param [Integer] length
+    #   @return [::String,nil]
+    # @!method length
+    #   Return string length (without null-terminator)
+    #   @return [Integer]
+    # @method size
+    #   Return string length (without null-terminator)
+    #   @return [Integer]
+    #   @see #length
+    # @!method ==
+    #   Check equality with underlying Ruby String
+    #   @return [Boolean]
+    # @!method unpack
+    #   Apply unpack on underlying Ruby String
+    #   @see ::String#unpack
+    #   @return [::Array]
+    # @!method force_encoding
+    #   @see ::String#force_encoding
+    # @!method encoding
+    #   @see ::String#encoding
+    #   @return [Encoding]
+    # @!method index(substring, offset = 0)
+    #   Returns the Integer index of the first occurrence of the given substring, or +nil+ if none found.
+    #   @param [::String] substring
+    #   @param [Integer] offset
+    #   @return [Integer,nil]
+    # @!method empty?
+    #   Return +true+ is string is empty.
+    #   @return [Boolean]
+    # @!method encode(encoding, **options)
+    #   @return [::String]
+    #   @see ::String#encode
+    # @!method slice(*args)
+    #   Returns the substring of +self+ specified by the arguments.
+    #   @see ::String#slice
+    #   @return [String,nil]
+    # @!method slice!(*args)
+    #   Removes the substring of +self+ specified by the arguments; returns the removed substring.
+    #   @see ::String#slice!
+    #   @return [String,nil]
     def_delegators :@string, :[], :length, :size, :inspect, :==,
                    :unpack, :force_encoding, :encoding, :index, :empty?,
                    :encode, :slice, :slice!
 
+    # Underlying Ruby String
     # @return [::String]
     attr_reader :string
-    # @return [Integer]
+    # Static length, if any
+    # @return [Integer,nil]
     attr_reader :static_length
 
     # @param [Hash] options
@@ -32,8 +81,9 @@ module BinStruct
       @static_length = options[:static_length]
     end
 
+    # Populate self from binary string
     # @param [::String] str
-    # @return [String] self
+    # @return [self]
     def read(str)
       s = str.to_s
       s = s[0, static_length] if static_length?
@@ -42,8 +92,8 @@ module BinStruct
       self
     end
 
-    # get null-terminated string
-    # @return [String]
+    # Get null-terminated string
+    # @return [::String]
     def to_s
       if static_length?
         s = string[0, static_length - 1]
@@ -63,6 +113,7 @@ module BinStruct
       self
     end
 
+    # Get C String size in bytes
     # @return [Integer]
     def sz
       if static_length?
@@ -74,19 +125,19 @@ module BinStruct
 
     # Say if a static length is defined
     # @return [Boolean]
-    # @since 3.1.6
     def static_length?
       !static_length.nil?
     end
 
     # Populate CString from a human readable string
-    # @param [String] str
+    # @param [::String] str
     # @return [self]
     def from_human(str)
       read str
     end
 
-    # @return [String]
+    # Get human-readable string
+    # @return [::String]
     def to_human
       string
     end