bin_struct 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5412a49a789a410de1120e6cbcbf55a7bd07783846a4e2f4cf9bc14eac76bfd
+  data.tar.gz: 9ae9eabeb7c3fe672e8ba229bc116c9a72bf26c7b1fd9eace52bb0f8036f0fea
+SHA512:
+  metadata.gz: 8fa11b03a84dca208c63d23358187b575982f5331d5c1da7fdd7c2343505ed932bc884a440b23589943d4eb5d9f78f942d77e8b271bef919277536a0ab9ab3b7
+  data.tar.gz: ecd4e847f6dc8392b759b8ef7a23df05191c697bb471a1ef8c685e12009be544b2dac4f8d77a944190a607b26216d90bd034742c95f9b2034b2701c4ec726602

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-07-13
+
+- Initial release

data/README.md

@@ -0,0 +1,18 @@
+# BinStruct
+
+BinStruct provides a simple ways to create and dissect binary data. It is an extraction from [PacketGen](https://github.com/lemontree55/packetgen) fields.
+
+## Installation
+
+Installation using RubyGems is easy:
+
+    $ gem install bin_struct
+
+Or add it to a Gemfile:
+```ruby
+gem 'bin_struct'
+```
+
+## 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

@@ -0,0 +1,270 @@
+# 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.
+
+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.
+  #
+  # ===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:
+  # * +#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:
+  #   tlv = MyTLV.new(type: 1, value: 'abcd')  # automagically set #length from value
+  #   tlv.type        #=> 1
+  #   tlv.human_type  #=> 'one'
+  #   tlv.length      #=> 4
+  #   tlv.value       #=> "abcd"
+  #
+  # ===Advanced usage
+  # Each field'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)
+  #   tlv = MyTLV.new(type: 1, value: '1.2.3.4')
+  #   tlv.type        #=> 1
+  #   tlv.length      #=> 4
+  #   tlv.value       #=> '1.2.3.4'
+  #   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+:
+  #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
+  #                                                length_class: PacketGen::Types::Int16,
+  #                                                aliases: { code: :type })
+  #   tlv = MyTLV.new(code: 1, value: 'abcd')
+  #   tlv.code        #=> 1
+  #   tlv.type        #=> 1
+  #   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
+
+    # @private
+    FIELD_TYPES = { 'T' => :type, 'L' => :length, 'V' => :value }.freeze
+
+    class << self
+      # @return [Hash]
+      attr_accessor :aliases
+      # @private
+      attr_accessor :field_in_length
+
+      # rubocop:disable Metrics/ParameterLists
+
+      # Generate a TLV class
+      # @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,
+      #   in the desired order.
+      # @param [String] field_in_length give fields 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')
+        unless equal?(AbstractTLV)
+          raise Error,
+                '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV'
+        end
+
+        klass = Class.new(self)
+        klass.aliases = aliases
+        klass.field_in_length = field_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)
+
+        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
+
+        klass
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @!attribute type
+      #   @abstract Type attribute for real TLV class
+      #   @return [Integer]
+      # @!attribute length
+      #   @abstract Length attribute for real TLV class
+      #   @return [Integer]
+      # @!attribute value
+      #   @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
+      # @return [void]
+      def define_type_enum(hsh)
+        field_defs[:type][:options][:enum].clear
+        field_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
+      # @return [void]
+      # @since 3.4.0
+      def define_type_default(default)
+        field_defs[:type][:default] = default
+      end
+
+      private
+
+      def check_field_in_length(field_in_length)
+        return if /^[TLV]{1,3}$/.match?(field_in_length)
+
+        raise 'field_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])
+          return
+        end
+
+        raise 'field_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
+          when 'T'
+            if type_class < Enum
+              klass.define_field(:type, type_class, enum: {})
+            else
+              klass.define_field(:type, type_class)
+            end
+          when 'L'
+            klass.define_field(:length, length_class)
+          when 'V'
+            klass.define_field(:value, value_class)
+          end
+        end
+      end
+    end
+
+    # @!attribute type
+    #   @abstract Type attribute
+    #   @return [Integer]
+    # @!attribute length
+    #   @abstract Length
+    #   @return [Integer]
+    # @!attribute value
+    #   @abstract Value attribute
+    #   @return [Object]enum
+
+    # @abstract Should only be called on real TLV classes, created by {.create}.
+    # @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
+      self.class.aliases.each do |al, orig|
+        options[orig] = options[al] if options.key?(al)
+      end
+
+      super
+      # used #value= defined below, which set length if needed
+      self.value = options[:value] if options[:value]
+      calc_length unless options.key?(:length)
+    end
+
+    # @abstract Should only be called on real TLV class instances.
+    # Populate object from a binary string
+    # @param [String,nil] str
+    # @return [Fields] 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
+      end
+
+      self
+    end
+
+    # @abstract Should only be called on real TLV class instances.
+    # 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
+      elsif self[:value].respond_to?(:from_human)
+        self[:value].from_human(val)
+      else
+        self[:value].read(val)
+      end
+      calc_length
+    end
+
+    # @abstract Should only be called on real TLV class instances.
+    # Get human-readable type
+    # @return [String]
+    def human_type
+      self[:type].to_human.to_s
+    end
+
+    # @abstract Should only be called on real TLV class instances.
+    # @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
+    def calc_length
+      fil = @field_in_length
+
+      length = 0
+      fil.each_char do |field_type|
+        length += self[FIELD_TYPES[field_type]].sz
+      end
+      self.length = length
+    end
+
+    private
+
+    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
+    end
+  end
+end

data/lib/bin_struct/array.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+# 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.
+
+require 'forwardable'
+
+module BinStruct
+  # @abstract Base class to define set of {Fields} subclasses.
+  # == #record_from_hash
+  # Subclasses should define private method +#record_from_hash+. This method
+  # is called by {#push} to add an object to the set.
+  #
+  # A default method is defined by {Array}: it calls constructor of class defined
+  # by {.set_of}.
+  #
+  # == #real_type
+  # Subclasses should define private method +#real_type+ if {.set_of} type
+  # may be subclassed. This method should return real class to use. It
+  # takes an only argument, which is of type given by {.set_of}.
+  #
+  # Default behaviour of this method is to return argument's class.
+  #
+  # @author Sylvain Daubert
+  class Array
+    extend Forwardable
+    include Enumerable
+    include Fieldable
+    include LengthFrom
+
+    # @!method [](index)
+    #   Return the element at +index+.
+    #   @param [integer] index
+    #   @return [Object]
+    # @!method clear
+    #   Clear array.
+    #   @return [void]
+    # @!method each
+    #   Calls the given block once for each element in self, passing that
+    #   element as a parameter. Returns the array itself.
+    #   @return [Array]
+    # @method empty?
+    #   Return +true+ if contains no element.
+    #   @return [Booelan]
+    # @!method first
+    #   Return first element
+    #   @return [Object]
+    # @!method last
+    #   Return last element.
+    #   @return [Object]
+    # @!method size
+    #   Get number of element in array
+    #   @return [Integer]
+    def_delegators :@array, :[], :clear, :each, :empty?, :first, :last, :size
+    alias length size
+
+    # Separator used in {#to_human}.
+    # May be ovverriden 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
+
+      # Define type of objects in set. Used by {#read} and {#push}.
+      # @param [Class] klass
+      # @return [void]
+      def set_of(klass)
+        @klass = klass
+      end
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    # @param [Hash] options
+    # @option options [Int] counter Int object used as a counter for this set
+    def initialize(options = {})
+      @counter = options[:counter]
+      @array = []
+      initialize_length_from(options)
+    end
+
+    # Initialize array for copy:
+    # * duplicate internal array.
+    def initialize_copy(_other)
+      @array = @array.dup
+    end
+
+    def ==(other)
+      @array == case other
+                when Array
+                  other.to_a
+                else
+                  other
+                end
+    end
+
+    # Clear array. Reset associated counter, if any.
+    # @return [void]
+    def clear!
+      @array.clear
+      @counter&.from_human(0)
+    end
+
+    # Delete an object from this array. Update associated counter if any
+    # @param [Object] obj
+    # @return [Object] deleted object
+    def delete(obj)
+      deleted = @array.delete(obj)
+      @counter.from_human(@counter.to_i - 1) if @counter && deleted
+      deleted
+    end
+
+    # Delete element at +index+.
+    # @param [Integer] index
+    # @return [Object,nil] deleted object
+    def delete_at(index)
+      deleted = @array.delete_at(index)
+      @counter.from_human(@counter.to_i - 1) if @counter && deleted
+      deleted
+    end
+
+    # @abstract depend on private method +#record_from_hash+ which should be
+    #   declared by subclasses.
+    # Add an object to this array
+    # @param [Object] obj type depends on subclass
+    # @return [Array] self
+    def push(obj)
+      obj = case obj
+            when Hash
+              record_from_hash obj
+            else
+              obj
+            end
+      @array << obj
+      self
+    end
+
+    # @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
+    # @param [Object] obj type depends on subclass
+    # @return [Array] self
+    def <<(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
+    # @return [self]
+    def read(data)
+      clear
+      case data
+      when ::Array
+        read_from_array(data)
+      else
+        read_from_string(data)
+      end
+      self
+    end
+
+    # Get size in bytes
+    # @return [Integer]
+    def sz
+      to_s.size
+    end
+
+    # Return an Array
+    # @return [::Array]
+    def to_a
+      @array
+    end
+
+    # Get binary string
+    # @return [String]
+    def to_s
+      @array.map(&:to_s).join
+    end
+
+    # Get a human readable string
+    # @return [String]
+    def to_human
+      @array.map(&:to_human).join(self.class::HUMAN_SEPARATOR)
+    end
+
+    private
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+
+    def read_from_string(str)
+      return self if str.nil? || @counter&.to_i&.zero?
+
+      str = read_with_length_from(str)
+      until str.empty? || (@counter && size == @counter.to_i)
+        obj = create_object_from_str(str)
+        @array << obj
+        str.slice!(0, obj.sz)
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def read_from_array(ary)
+      return self if ary.empty?
+
+      ary.each do |hsh|
+        self << hsh
+      end
+    end
+
+    def record_from_hash(hsh)
+      obj_klass = self.class.set_of_klass
+      unless obj_klass
+        raise NotImplementedError,
+              'class should define #record_from_hash or declare type of elements in set with .set_of'
+      end
+
+      obj = obj_klass.new(hsh) if obj_klass
+      klass = real_type(obj)
+      klass == obj_klass ? obj : klass.new(hsh)
+    end
+
+    def real_type(_obj)
+      self.class.set_of_klass
+    end
+
+    def create_object_from_str(str)
+      klass = self.class.set_of_klass
+      obj = klass.new.read(str)
+      real_klass = real_type(obj)
+
+      if real_klass == klass
+        obj
+      else
+        real_klass.new.read(str)
+      end
+    end
+  end
+
+  # @private
+  module ArrayOfIntMixin
+    def read_from_array(ary)
+      return self if ary.empty?
+
+      ary.each do |i|
+        self << self.class.set_of_klass.new(i)
+      end
+    end
+  end
+
+  # Specialized array to handle serie of {Int8}.
+  class ArrayOfInt8 < Array
+    include ArrayOfIntMixin
+    set_of Int8
+  end
+
+  # Specialized array to handle serie of {Int16}.
+  class ArrayOfInt16 < Array
+    include ArrayOfIntMixin
+    set_of Int16
+  end
+
+  # Specialized array to handle serie of {Int16le}.
+  class ArrayOfInt16le < Array
+    include ArrayOfIntMixin
+    set_of Int16le
+  end
+
+  # Specialized array to handle serie of {Int32}.
+  class ArrayOfInt32 < BinStruct::Array
+    include ArrayOfIntMixin
+    set_of Int32
+  end
+
+  # Specialized array to handle serie of {Int32le}.
+  class ArrayOfInt32le < BinStruct::Array
+    include ArrayOfIntMixin
+    set_of Int32le
+  end
+end

data/lib/bin_struct/cstring.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# 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.
+
+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
+  class CString
+    extend Forwardable
+    include Fieldable
+
+    def_delegators :@string, :[], :length, :size, :inspect, :==,
+                   :unpack, :force_encoding, :encoding, :index, :empty?,
+                   :encode, :slice, :slice!
+
+    # @return [::String]
+    attr_reader :string
+    # @return [Integer]
+    attr_reader :static_length
+
+    # @param [Hash] options
+    # @option options [Integer] :static_length set a static length for this string
+    def initialize(options = {})
+      register_internal_string(+'')
+      @static_length = options[:static_length]
+    end
+
+    # @param [::String] str
+    # @return [String] self
+    def read(str)
+      s = str.to_s
+      s = s[0, static_length] if static_length?
+      register_internal_string s
+      remove_null_character
+      self
+    end
+
+    # get null-terminated string
+    # @return [String]
+    def to_s
+      if static_length?
+        s = string[0, static_length - 1]
+        s << ("\x00" * (static_length - s.length))
+      else
+        s = "#{string}\x00"
+      end
+      BinStruct.force_binary(s)
+    end
+
+    # Append the given string to CString
+    # @param [#to_s] str
+    # @return [self]
+    def <<(str)
+      @string << str.to_s
+      remove_null_character
+      self
+    end
+
+    # @return [Integer]
+    def sz
+      if static_length?
+        static_length
+      else
+        to_s.size
+      end
+    end
+
+    # 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
+    # @return [self]
+    def from_human(str)
+      read str
+    end
+
+    # @return [String]
+    def to_human
+      string
+    end
+
+    private
+
+    def register_internal_string(str)
+      @string = str
+      BinStruct.force_binary(@string)
+    end
+
+    def remove_null_character
+      idx = string.index(0.chr)
+      register_internal_string(string[0, idx]) unless idx.nil?
+    end
+  end
+end