bin_struct 0.1.0 → 0.2.1

data/lib/bin_struct.rb

@@ -22,10 +22,10 @@ module BinStruct
   end
 end
 
-require_relative 'bin_struct/fieldable'
+require_relative 'bin_struct/structable'
 require_relative 'bin_struct/int'
 require_relative 'bin_struct/enum'
-require_relative 'bin_struct/fields'
+require_relative 'bin_struct/struct'
 require_relative 'bin_struct/length_from'
 require_relative 'bin_struct/abstract_tlv'
 require_relative 'bin_struct/array'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bin_struct
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - LemonTree55
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-16 00:00:00.000000000 Z
+date: 2024-11-25 00:00:00.000000000 Z
 dependencies: []
 description: 'BinStruct is a binary dissector and generator. It eases manipulating
   complex binary data.
@@ -28,13 +28,13 @@ files:
 - lib/bin_struct/array.rb
 - lib/bin_struct/cstring.rb
 - lib/bin_struct/enum.rb
-- lib/bin_struct/fieldable.rb
-- lib/bin_struct/fields.rb
 - lib/bin_struct/int.rb
 - lib/bin_struct/int_string.rb
 - lib/bin_struct/length_from.rb
 - lib/bin_struct/oui.rb
 - lib/bin_struct/string.rb
+- lib/bin_struct/struct.rb
+- lib/bin_struct/structable.rb
 - lib/bin_struct/version.rb
 homepage: https://github.com/lemontree55/bin_struct
 licenses:

data/lib/bin_struct/fields.rb

@@ -1,612 +0,0 @@
-# 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.
-
-# rubocop:disable Metrics/ClassLength
-
-module BinStruct
-  # @abstract Set of fields
-  # This class is a base class to define headers or anything else with a binary
-  # format containing multiple fields.
-  #
-  # == Basics
-  # A {Fields} subclass is generaly composed of multiple binary fields. These fields
-  # have each a given type. All {Fieldable} types are supported.
-  #
-  # To define a new subclass, it has to inherit from {Fields}. And some class
-  # methods have to be used to declare attributes/fields:
-  #   class MyBinaryStructure < BinStruct::Fields
-  #     # define a first Int8 attribute, with default value: 1
-  #     define_field :attr1, BinStruct::Int8, default: 1
-  #     #define a second attribute, of kind Int32
-  #     define_field :attr2, BinStruct::Int32
-  #   end
-  #
-  # These defintions create 4 methods: +#attr1+, +#attr1=+, +#attr2+ and +#attr2=+.
-  # All these methods take and/or return Integers.
-  #
-  # Fields may also be accessed through {#[]} ans {#[]=}. These methods give access
-  # to type object:
-  #   mybs = MyBinaryStructure.new
-  #   mybs.attr1     # => Integer
-  #   mybs[:attr1]   # => BinStruct::Int8
-  #
-  # {#initialize} accepts an option hash to populate attributes. Keys are attribute
-  # name symbols, and values are those expected by writer accessor.
-  #
-  # {#read} is able to populate object from a binary string.
-  #
-  # {#to_s} returns binary string from object.
-  #
-  # == Add Fields
-  # {.define_field} adds a field to Fields subclass. A lot of field types may be
-  # defined: integer types, string types (to handle a stream of bytes). More
-  # complex field types may be defined using others Fields subclasses:
-  #   # define a 16-bit little-endian integer field, named type
-  #   define_field :type, BinStruct::Int16le
-  #   # define a string field
-  #   define_field :body, BinStruct::String
-  #   # define a field using a complex type (Fields subclass)
-  #   define_field :mac_addr, PacketGen::Eth::MacAddr
-  #
-  # This example creates six methods on our Fields subclass: +#type+, +#type=+,
-  # +#body+, +#body=+, +#mac_addr+ and +#mac_addr=+.
-  #
-  # {.define_field} has many options (third optional Hash argument):
-  # * +:default+ gives default field value. It may be a simple value (an Integer
-  #   for an Int field, for example) or a lambda,
-  # * +:builder+ to give a builder/constructor lambda to create field. The lambda
-  #   takes 2 argument: {Fields} subclass object owning field, and type class as passes
-  #   as second argument to .define_field,
-  # * +:optional+ to define this field as optional. This option takes a lambda
-  #   parameter used to say if this field is present or not. The lambda takes an argument
-  #   ({Fields} subclass object owning field),
-  # For example:
-  #   # 32-bit integer field defaulting to 1
-  #   define_field :type, BinStruct::Int32, default: 1
-  #   # 16-bit integer field, created with a random value. Each instance of this
-  #   # object will have a different value.
-  #   define_field :id, BinStruct::Int16, default: ->(obj) { rand(65535) }
-  #   # a size field
-  #   define_field :body_size, BinStruct::Int16
-  #   # String field which length is taken from body_size field
-  #   define_field :body, BinStruct::String, builder: ->(obj, type) { type.new(length_from: obj[:body_size]) }
-  #   # 16-bit enumeration type. As :default not specified, default to first value of enum
-  #   define_field :type_class, BinStruct::Int16Enum, enum: { 'class1' => 1, 'class2' => 2}
-  #   # optional field. Only present if another field has a certain value
-  #   define_field :opt1, BinStruct::Int16, optional: ->(h) { h.type == 42 }
-  #
-  # {.define_field_before} and {.define_field_after} are also defined to relatively
-  # create a field from anoher one (for example, when adding a field in a subclass).
-  # == Generating bit fields
-  # {.define_bit_fields_on} creates a bit field on a previuously declared integer
-  # field. For example, +frag+ field in IP header:
-  #   define_field :frag, Types::Int16, default: 0
-  #   define_bit_fields_on :frag, :flag_rsv, :flag_df, :flag_mf, :fragment_offset, 13
-  #
-  # This example generates methods:
-  # * +#frag+ and +#frag=+ to access +frag+ field 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+ field,
-  # * +#fragment_offset+ and +#fragment_offset=+ to access 13-bit integer fragment
-  #   offset subfield from +frag+ field.
-  #
-  # == Creating a new field class from another one
-  # Some methods may help in this case:
-  # * {.define_field_before} to define a new field before an existing one,
-  # * {.define_field_after} to define a new field after an existing onr,
-  # * {.remove_field} to remove an existing field,
-  # * {.uptade_fied} to change options of a field (but not its type),
-  # * {.remove_bit_fields_on} to remove a bit fields definition.
-  #
-  # @author Sylvain Daubert
-  class Fields
-    # @private
-    FieldDef = Struct.new(:type, :default, :builder, :optional, :options)
-    # @private field names, ordered as they were declared
-    @ordered_fields = []
-    # @private field definitions
-    @field_defs = {}
-    # @private bit field definitions
-    @bit_fields = {}
-
-    class << self
-      # Get field definitions for this class.
-      # @return [Hash]
-      # @since 3.1.0
-      attr_reader :field_defs
-      # Get bit fields defintions for this class
-      # @return [Hash]
-      # @since 3.1.5
-      attr_reader :bit_fields
-
-      # On inheritage, create +@field_defs+ class variable
-      # @param [Class] klass
-      # @return [void]
-      def inherited(klass)
-        super
-
-        field_defs = {}
-        @field_defs.each do |k, v|
-          field_defs[k] = v.clone
-        end
-        ordered = @ordered_fields.clone
-        bf = bit_fields.clone
-
-        klass.class_eval do
-          @ordered_fields = ordered
-          @field_defs = field_defs
-          @bit_fields = bf
-        end
-      end
-
-      # Get field names
-      # @return [Array<Symbol>]
-      def fields
-        @ordered_fields
-      end
-
-      # Define a field in class
-      #   class BinaryStruct < BinStruct::Fields
-      #     # 8-bit value
-      #     define_field :value1, Types::Int8
-      #     # 16-bit value
-      #     define_field :value2, Types::Int16
-      #     # specific class, may use a specific constructor
-      #     define_field :value3, MyClass, builder: ->(obj, type) { type.new(obj) }
-      #   end
-      #
-      #   bs = BinaryStruct.new
-      #   bs[value1]   # => Types::Int8
-      #   bs.value1    # => Integer
-      # @param [Symbol] name field name
-      # @param [Fieldable] 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 field.
-      #   Parameters to this lambda is the caller object and the field type class.
-      # @option options [Lambda] :optional define this field as optional. Given lambda
-      #   is used to known if this field is present or not. Parameter to this lambda is
-      #   the being defined Field object.
-      # @return [void]
-      def define_field(name, type, options = {})
-        fields << name
-        field_defs[name] = FieldDef.new(type,
-                                        options.delete(:default),
-                                        options.delete(:builder),
-                                        options.delete(:optional),
-                                        options)
-
-        add_methods(name, type)
-      end
-
-      # Define a field, before another one
-      # @param [Symbol,nil] other field name to create a new one before. If +nil+,
-      #    new field is appended.
-      # @param [Symbol] name field name to create
-      # @param [Fieldable] type class or instance
-      # @param [Hash] options See {.define_field}.
-      # @return [void]
-      # @see .define_field
-      def define_field_before(other, name, type, options = {})
-        define_field name, type, options
-        return if other.nil?
-
-        fields.delete name
-        idx = fields.index(other)
-        raise ArgumentError, "unknown #{other} field" if idx.nil?
-
-        fields[idx, 0] = name
-      end
-
-      # Define a field, after another one
-      # @param [Symbol,nil] other field name to create a new one after. If +nil+,
-      #    new field is appended.
-      # @param [Symbol] name field name to create
-      # @param [Fieldable] type class or instance
-      # @param [Hash] options See {.define_field}.
-      # @return [void]
-      # @see .define_field
-      def define_field_after(other, name, type, options = {})
-        define_field name, type, options
-        return if other.nil?
-
-        fields.delete name
-        idx = fields.index(other)
-        raise ArgumentError, "unknown #{other} field" if idx.nil?
-
-        fields[idx + 1, 0] = name
-      end
-
-      # Remove a previously defined field
-      # @param [Symbol] name
-      # @return [void]
-      # @since 2.8.4
-      def remove_field(name)
-        fields.delete name
-        @field_defs.delete name
-        undef_method name if method_defined?(name)
-        undef_method :"#{name}=" if method_defined?(:"#{name}=")
-      end
-
-      # Update a previously defined field
-      # @param [Symbol] field field name to create
-      # @param [Hash] options See {.define_field}.
-      # @return [void]
-      # @see .define_field
-      # @raise [ArgumentError] unknown +field+
-      # @since 2.8.4
-      def update_field(field, options)
-        check_existence_of field
-
-        %i[default builder optional].each do |property|
-          field_defs_property_from(field, property, options)
-        end
-
-        field_defs[field].options.merge!(options)
-      end
-
-      # Define a bitfield on given attribute
-      #   class MyHeader < BinStruct::Fields
-      #     define_field :flags, Types::Int16
-      #     # define a bit field on :flag attribute:
-      #     # flag1, flag2 and flag3 are 1-bit fields
-      #     # type and stype are 3-bit fields. reserved is a 6-bit field
-      #     define_bit_fields_on :flags, :flag1, :flag2, :flag3, :type, 3, :stype, 3, :reserved, 7
-      #   end
-      # A bitfield of size 1 bit defines 2 methods:
-      # * +#field?+ which returns a Boolean,
-      # * +#field=+ which takes and returns a Boolean.
-      # A bitfield of more bits defines 2 methods:
-      # * +#field+ which returns an Integer,
-      # * +#field=+ which takes and returns an Integer.
-      # @param [Symbol] attr attribute name (attribute should be a {Types::Int}
-      #   subclass)
-      # @param [Array] args list of bitfield names. Name may be followed
-      #   by bitfield size. If no size is given, 1 bit is assumed.
-      # @raise [ArgumentError] unknown +attr+
-      # @return [void]
-      def define_bit_fields_on(attr, *args)
-        check_existence_of attr
-
-        type = field_defs[attr].type
-        raise TypeError, "#{attr} is not a BinStruct::Int" unless type < Int
-
-        total_size = type.new.nbits
-        idx = total_size - 1
-
-        until args.empty?
-          field = args.shift
-          next unless field.is_a? Symbol
-
-          size = size_from(args)
-
-          unless field == :_
-            add_bit_methods(attr, field, size, total_size, idx)
-            register_bit_field_size(attr, field, size)
-          end
-
-          idx -= size
-        end
-      end
-
-      # Remove all bit fields defined on +attr+
-      # @param [Symbol] attr attribute defining bit fields
-      # @return [void]
-      # @since 2.8.4
-      def remove_bit_fields_on(attr)
-        fields = bit_fields.delete(attr)
-        return if fields.nil?
-
-        fields.each do |field, size|
-          undef_method :"#{field}="
-          undef_method(size == 1 ? "#{field}?" : field)
-        end
-      end
-
-      private
-
-      def add_methods(name, type)
-        define = []
-        if type < Enum
-          define << "def #{name}; self[:#{name}].to_i; end"
-          define << "def #{name}=(val) self[:#{name}].value = val; end"
-        else
-          define << "def #{name}\n  " \
-                    "to_and_from_human?(:#{name}) ? self[:#{name}].to_human : self[:#{name}]\n" \
-                    'end'
-          define << "def #{name}=(val)\n  " \
-                    "to_and_from_human?(:#{name}) ? self[:#{name}].from_human(val) : self[:#{name}].read(val)\n" \
-                    'end'
-        end
-
-        define.delete_at(1) if instance_methods.include?(:"#{name}=")
-        define.delete_at(0) if instance_methods.include? name
-        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_field_mask(size, shift)
-        ((2**size) - 1) << shift
-      end
-
-      def compute_clear_mask(total_size, field_mask)
-        ((2**total_size) - 1) & (~field_mask & ((2**total_size) - 1))
-      end
-
-      def add_single_bit_methods(attr, name, size, total_size, shift)
-        field_mask = compute_field_mask(size, shift)
-        clear_mask = compute_clear_mask(total_size, field_mask)
-
-        class_eval <<-METHODS, __FILE__, __LINE__ + 1
-          def #{name}?                                                  # def bit?
-            val = (self[:#{attr}].to_i & #{field_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)
-        field_mask = compute_field_mask(size, shift)
-        clear_mask = compute_clear_mask(total_size, field_mask)
-
-        class_eval <<-METHODS, __FILE__, __LINE__ + 1
-          def #{name}                                                   # def multibit
-            (self[:#{attr}].to_i & #{field_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_field_size(attr, field, size)
-        bit_fields[attr] = {} if bit_fields[attr].nil?
-        bit_fields[attr][field] = size
-      end
-
-      def field_defs_property_from(field, property, options)
-        field_defs[field].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(field)
-        raise ArgumentError, "unknown #{field} field for #{self}" unless field_defs.key?(field)
-      end
-    end
-
-    # Create a new fields object
-    # @param [Hash] options Keys are symbols. They should have name of object
-    #   attributes, as defined by {.define_field} and by {.define_bit_fields_on}.
-    def initialize(options = {})
-      @fields = {}
-      @optional_fields = {}
-
-      self.class.fields.each do |field|
-        build_field field
-        initialize_value field, options[field]
-        initialize_optional field
-      end
-
-      self.class.bit_fields.each_value do |hsh|
-        hsh.each_key do |bit_field|
-          send(:"#{bit_field}=", options[bit_field]) if options[bit_field]
-        end
-      end
-    end
-
-    # Get field object
-    # @param [Symbol] field
-    # @return [Fieldable]
-    def [](field)
-      @fields[field]
-    end
-
-    # Set field object
-    # @param [Symbol] field
-    # @param [Object] obj
-    # @return [Object]
-    def []=(field, obj)
-      @fields[field] = obj
-    end
-
-    # Get all field names
-    # @return [Array<Symbol>]
-    def fields
-      self.class.fields
-    end
-
-    # Get all optional field name
-    # @return[Array<Symbol>,nil]
-    def optional_fields
-      @optional_fields.keys
-    end
-
-    # Say if this field is optional
-    # @return [Boolean]
-    def optional?(field)
-      @optional_fields.key? field
-    end
-
-    # Say if an optional field is present
-    # @return [Boolean]
-    def present?(field)
-      return true unless optional?(field)
-
-      @optional_fields[field].call(self)
-    end
-
-    # Populate object from a binary string
-    # @param [String] str
-    # @return [Fields] self
-    def read(str)
-      return self if str.nil?
-
-      force_binary str
-      start = 0
-      fields.each do |field|
-        next unless present?(field)
-
-        obj = self[field].read str[start..]
-        start += self[field].sz
-        self[field] = obj unless obj == self[field]
-      end
-
-      self
-    end
-
-    # Common inspect method for headers.
-    #
-    # A block may be given to differently format some attributes. This
-    # may be used by subclasses to handle specific fields.
-    # @yieldparam attr [Symbol] attribute to inspect
-    # @yieldreturn [String,nil] the string to print for +attr+, or +nil+
-    #  to let +inspect+ generate it
-    # @return [String]
-    def inspect
-      str = Inspect.dashed_line(self.class, 1)
-      fields.each do |attr|
-        next if attr == :body
-        next unless present?(attr)
-
-        result = yield(attr) if block_given?
-        str << (result || Inspect.inspect_attribute(attr, self[attr], 1))
-      end
-      str
-    end
-
-    # Return object as a binary string
-    # @return [String]
-    def to_s
-      fields.select { |f| present?(f) }
-            .map! { |f| force_binary @fields[f].to_s }.join
-    end
-
-    # Size of object as binary string
-    # @return [nteger]
-    def sz
-      to_s.size
-    end
-
-    # Return object as a hash
-    # @return [Hash] keys: attributes, values: attribute values
-    def to_h
-      fields.to_h { |f| [f, @fields[f].to_human] }
-    end
-
-    # Get offset of given field in {Fields} structure.
-    # @param [Symbol] field
-    # @return [Integer]
-    # @raise [ArgumentError] unknown field
-    def offset_of(field)
-      raise ArgumentError, "#{field} is an unknown field of #{self.class}" unless @fields.include?(field)
-
-      offset = 0
-      fields.each do |f|
-        break offset if f == field
-        next unless present?(f)
-
-        offset += self[f].sz
-      end
-    end
-
-    # Get bit fields definition for given field.
-    # @param [Symbol] field defining bit fields
-    # @return [Hash,nil] keys: bit fields, values: their size in bits
-    # @since 2.8.3
-    def bits_on(field)
-      self.class.bit_fields[field]
-    end
-
-    private
-
-    # Deeply duplicate +@fields+
-    # @return [void]
-    def initialize_copy(_other)
-      fields = {}
-      @fields.each { |k, v| fields[k] = v.dup }
-      @fields = fields
-    end
-
-    # Force str to binary encoding
-    # @param [String] str
-    # @return [String]
-    def force_binary(str)
-      BinStruct.force_binary(str)
-    end
-
-    # @param [Symbol] attr attribute
-    # @return [Boolean] +tru+e 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
-
-    def field_defs
-      self.class.field_defs
-    end
-
-    # rubocop:disable Metrics/AbcSize
-    def build_field(field)
-      type = field_defs[field].type
-
-      @fields[field] = if field_defs[field].builder
-                         field_defs[field].builder.call(self, type)
-                       elsif !field_defs[field].options.empty?
-                         type.new(field_defs[field].options)
-                       else
-                         type.new
-                       end
-    end
-    # rubocop:enable Metrics/AbcSize
-
-    def initialize_value(field, val)
-      type = field_defs[field].type
-      default = field_defs[field].default
-      default = default.to_proc.call(self) if default.is_a?(Proc)
-
-      value = val || default
-      if value.class <= type
-        @fields[field] = value
-      elsif @fields[field].respond_to? :from_human
-        @fields[field].from_human(value)
-      else
-        @fields[field].read(value)
-      end
-    end
-
-    def initialize_optional(field)
-      optional = field_defs[field].optional
-      @optional_fields[field] = optional if optional
-    end
-  end
-end
-
-# rubocop:enable Metrics/ClassLength