bin_struct 0.1.0

data/lib/bin_struct/int.rb

@@ -0,0 +1,514 @@
+# 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.
+
+module BinStruct
+  # Base integer class to handle binary integers
+  # @abstract
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class Int
+    include Fieldable
+
+    # Integer value
+    # @return [Integer,nil]
+    attr_accessor :value
+    # Integer endianness
+    # @return [:little,:big,:native,nil]
+    attr_accessor :endian
+    # Integer size, in bytes
+    # @return [Integer, nil]
+    attr_accessor :width
+    # Integer default value
+    # @return [Integer]
+    attr_accessor :default
+
+    # @param [Hash] options
+    # @option options [Integer, nil] :value
+    # @option options [:little,:big,nil] :endian
+    # @option options [Integer,nil] :width
+    # @option options [Integer] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      @value = options[:value]
+      @endian = options[:endian]
+      @width = options[:width]
+      @default = options[:default] || 0
+    end
+
+    # @abstract
+    # Read an Int from a binary string or an integer
+    # @param [#to_s] str
+    # @return [self]
+    # @raise [Error] when reading +#to_s+ objects with abstract Int class.
+    # @author LemonTree55
+    def read(str)
+      raise Error, 'BinStruct::Int#read is abstract' unless defined? @packstr
+
+      @value = str.to_s.unpack1(@packstr[@endian])
+      self
+    end
+
+    # @abstract
+    # @return [::String]
+    # @raise [Error] This is an abstrat method and must be redefined
+    def to_s
+      raise Error, 'BinStruct::Int#to_s is abstract' unless defined? @packstr
+
+      [to_i].pack(@packstr[@endian])
+    end
+
+    # Convert Int to Integer
+    # @return [Integer]
+    def to_i
+      @value || @default
+    end
+    alias to_human to_i
+
+    # @param [Integer] value
+    # @return [self]
+    def from_human(value)
+      @value = value
+      self
+    end
+
+    # Convert Int to Float
+    # @return [Float]
+    def to_f
+      to_i.to_f
+    end
+
+    # Give size in bytes of self
+    # @return [Integer]
+    def sz
+      width
+    end
+
+    # Format Int type when inspecting header or packet
+    # @return [String]
+    def format_inspect
+      format_str % [to_i.to_s, to_i]
+    end
+
+    # Return the number of bits used to encode this Int
+    # @return [Integer]
+    def nbits
+      width * 8
+    end
+
+    private
+
+    def format_str
+      "%-16s (0x%0#{width * 2}x)"
+    end
+  end
+
+  # One byte unsigned integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class Int8 < Int
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @author LemonTree55
+    def initialize(options = {})
+      options[:endian] = nil
+      options[:width] = 1
+      super
+      @packstr = { nil => 'C' }
+    end
+  end
+
+  # One byte signed integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class SInt8 < Int
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @author LemonTree55
+    def initialize(options = {})
+      options[:endian] = nil
+      options[:width] = 1
+      super
+      @packstr = { nil => 'c' }
+    end
+  end
+
+  # 2-byte unsigned integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class Int16 < Int
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @option [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = { value: options[:value], endian: options[:endian] || :big, width: 2 }
+      super(opts)
+      @packstr = { big: 'n', little: 'v', native: 'S' }
+    end
+  end
+
+  # big endian 2-byte unsigned integer
+  # @author Sylvain Daubert
+  class Int16be < Int16
+    undef endian=
+  end
+
+  # little endian 2-byte unsigned integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class Int16le < Int16
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 2-byte unsigned integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class Int16n < Int16
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+
+  # 2-byte signed integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class SInt16 < Int16
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = { value: options[:value], endian: options[:endian] || :big }
+      super(opts)
+      @packstr = { big: 's>', little: 's<', native: 's' }
+    end
+  end
+
+  # big endian 2-byte signed integer
+  # @author Sylvain Daubert
+  class SInt16be < SInt16
+    undef endian=
+  end
+
+  # little endian 2-byte signed integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class SInt16le < SInt16
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Integer, nil] value
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 2-byte signed integer
+  # @author Sylvain Daubert
+  # @author LemonTree55
+  class SInt16n < SInt16
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Integer, nil] value
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+
+  # 3-byte unsigned integer
+  # @author LemonTree55
+  class Int24 < Int
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @option options [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = options.slice(:value, :endian)
+      opts[:endian] ||= :big
+      opts[:width] = 3
+
+      if opts[:endian] == :native
+        opts[:endian] = if [1].pack('S').unpack1('n') == 1
+                          :big
+                        else
+                          :little
+                        end
+      end
+      super(opts)
+    end
+
+    # Read an 3-byte Int from a binary string
+    # @param [String] str
+    # @return [self]
+    def read(value)
+      return self if value.nil?
+
+      up8 = down16 = 0
+      if @endian == :big
+        up8, down16 = value.to_s.unpack('Cn')
+      else
+        down16, up8 = value.to_s.unpack('vC')
+      end
+      @value = (up8 << 16) | down16
+      self
+    end
+
+    # @author Sylvain Daubert
+    # @return [::String]
+    def to_s
+      up8 = to_i >> 16
+      down16 = to_i & 0xffff
+      if @endian == :big
+        [up8, down16].pack('Cn')
+      else
+        [down16, up8].pack('vC')
+      end
+    end
+  end
+
+  # big endian 3-byte unsigned integer
+  # @author Sylvain Daubert
+  class Int24be < Int24
+    undef endian=
+  end
+
+  # little endian 3-byte unsigned integer
+  # @author LemonTree55
+  class Int24le < Int24
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 3-byte unsigned integer
+  # @author LemonTree55
+  class Int24n < Int24
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # 4-byte unsigned integer
+  # @author LemonTree55
+  class Int32 < Int
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    # @option [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = { value: options[:value], endian: options[:endian] || :big, width: 4 }
+      super(opts)
+      @packstr = { big: 'N', little: 'V', native: 'L' }
+    end
+  end
+
+  # big endian 4-byte unsigned integer
+  # @author Sylvain Daubert
+  class Int32be < Int32
+    undef endian=
+  end
+
+  # little endian 4-byte unsigned integer
+  # @author LemonTree55
+  class Int32le < Int32
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 4-byte unsigned integer
+  # @author LemonTree55
+  class Int32n < Int32
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+
+  # 4-byte unsigned integer
+  # @author LemonTree55
+  class SInt32 < Int32
+    # @param [Hash] options
+    # @option options [Integer] :value
+    # @option options [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = { value: options[:value], endian: options[:endian] || :big }
+      super(opts)
+      @packstr = { big: 'l>', little: 'l<', native: 'l' }
+    end
+  end
+
+  # big endian 4-byte unsigned integer
+  # @author Sylvain Daubert
+  class SInt32be < SInt32
+    undef endian=
+  end
+
+  # little endian 4-byte unsigned integer
+  # @author LemonTree55
+  class SInt32le < SInt32
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 4-byte unsigned integer
+  # @author LemonTree55
+  class SInt32n < SInt32
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+
+  # 8-byte unsigned integer
+  # @author LemonTree55
+  class Int64 < Int
+    # @param [Hash] options
+    # @option options [Integer] :value
+    # @option options [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = options.slice(:value, :endian)
+      opts[:endian] ||= :big
+      opts[:width] = 8
+      super(opts)
+      @packstr = { big: 'Q>', little: 'Q<', native: 'Q' }
+    end
+  end
+
+  # big endian 8-byte unsigned integer
+  # @author Sylvain Daubert
+  class Int64be < Int64
+    undef endian=
+  end
+
+  # little endian 8-byte unsigned integer
+  # @author LemonTree55
+  class Int64le < Int64
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 8-byte unsigned integer
+  # @author LemonTree55
+  class Int64n < Int64
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+
+  # 8-byte unsigned integer
+  # @author LemonTree55
+  class SInt64 < Int64
+    # @param [Hash] options
+    # @option options [Integer] :value
+    # @option options [:big, :little, :native] :endian
+    def initialize(options = {})
+      opts = options.slice(:value, :endian)
+      super(opts)
+      @packstr = { big: 'q>', little: 'q<', native: 'q' }
+    end
+  end
+
+  # big endian 8-byte unsigned integer
+  # @author Sylvain Daubert
+  class SInt64be < SInt64
+    undef endian=
+  end
+
+  # little endian 8-byte unsigned integer
+  # @author LemonTree55
+  class SInt64le < SInt64
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :little }
+      super(opts)
+    end
+  end
+
+  # native endian 8-byte unsigned integer
+  # @author LemonTree55
+  class SInt64n < SInt64
+    # @param [Integer,nil] value
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Integer] :value
+    def initialize(options = {})
+      opts = { value: options[:value], endian: :native }
+      super(opts)
+    end
+  end
+end

data/lib/bin_struct/int_string.rb

@@ -0,0 +1,99 @@
+# 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.
+
+module BinStruct
+  # Provides a class for creating strings preceeded by their length as a {Int}.
+  # By default, a null string will have one byte length (length byte set to 0).
+  # @author Sylvain Daubert
+  class IntString
+    include Fieldable
+
+    # internal string
+    # @return [String]
+    attr_reader :string
+
+    # @param [Hash] options
+    # @option options [Class] :length_type should be a {Int} subclass. Default to {Int8}.
+    # @option options [::String] :string String value. Default to +''+
+    def initialize(options = {})
+      @string = BinStruct::String.new.read(options[:string] || '')
+      @length = (options[:length_type] || Int8).new
+      calc_length
+    end
+
+    # @param [::String] str
+    # @return [IntString] self
+    def read(str)
+      unless str[0, @length.width].size == @length.width
+        raise Error,
+              "String too short for type #{@length.class.to_s.gsub(/.*::/, '')}"
+      end
+      @length.read str[0, @length.width]
+      @string.read str[@length.width, @length.to_i]
+      self
+    end
+
+    # @param [Integer] len
+    # @return [Integer]
+    def length=(len)
+      @length.from_human(len)
+    end
+
+    # @return [Integer]
+    def length
+      @length.to_i
+    end
+
+    # @param [#to_s] str
+    # @return [String]
+    def string=(str)
+      @length.value = str.to_s.size
+      @string = str.to_s
+    end
+
+    # Get binary string
+    # @return [::String]
+    def to_s
+      @length.to_s << @string.to_s
+    end
+
+    # Set from a human readable string
+    # @param [String] str
+    # @return [self]
+    def from_human(str)
+      @string.read str
+      calc_length
+      self
+    end
+
+    # Get human readable string
+    # @return [::String]
+    # @since 2.2.0
+    def to_human
+      @string
+    end
+
+    # Set length from internal string length
+    # @return [Integer]
+    def calc_length
+      @length.read @string.length
+    end
+
+    # Give binary string length (including +length+ field)
+    # @return [Integer]
+    def sz
+      to_s.size
+    end
+
+    # Say if IntString is empty
+    # @return [Boolean]
+    def empty?
+      length.zero?
+    end
+  end
+end

data/lib/bin_struct/length_from.rb

@@ -0,0 +1,51 @@
+# 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.
+
+module BinStruct
+  # This module is a mixin adding +length_from+ capacity to a type.
+  # +length_from+ capacity is the capacity, for a type, to gets its
+  # length from another object.
+  # @author Sylvain Daubert
+  # @since 3.0.0
+  module LengthFrom
+    # Max value returned by {#sz_to_read}.
+    MAX_SZ_TO_READ = 65_535
+
+    # Initialize +length from+ capacity.
+    # Should be call by extensed object's initialize.
+    # @param [Hash] options
+    # @option options [Types::Int,Proc] :length_from object or proc from which
+    #   takes length when reading
+    # @return [void]
+    def initialize_length_from(options)
+      @length_from = options[:length_from]
+    end
+
+    # Return a substring from +str+ of length given in another object.
+    # @param [#to_s] str
+    # @return [String]
+    def read_with_length_from(str)
+      s = BinStruct.force_binary(str.to_s)
+      s[0, sz_to_read]
+    end
+
+    # Size to read, from length_from
+    # @return [Integer]
+    def sz_to_read
+      len = case @length_from
+            when Int
+              @length_from.to_i
+            when Proc
+              @length_from.call
+            else
+              MAX_SZ_TO_READ
+            end
+      [0, len].max
+    end
+  end
+end

data/lib/bin_struct/oui.rb

@@ -0,0 +1,49 @@
+# 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.
+
+module BinStruct
+  # OUI type, defined as a set of 3 bytes
+  #  oui = OUI.new
+  #  oui.from_human('00:01:02')
+  #  oui.to_human   # => "00:01:02"
+  # @author Sylvain Daubert
+  class OUI < Fields
+    include Fieldable
+
+    # @attribute b2
+    #  @return [Integer] left-most byte
+    define_field :b2, Int8
+    # @attribute b1
+    #  @return [Integer] center byte
+    define_field :b1, Int8
+    # @attribute b0
+    #  @return [Integer] right-most byte
+    define_field :b0, Int8
+
+    # Read a human-readable string to populate object
+    # @param [String] str
+    # @return [OUI] self
+    def from_human(str)
+      return self if str.nil?
+
+      bytes = str.split(':')
+      raise ArgumentError, 'not a OUI' unless bytes.size == 3
+
+      self[:b2].from_human(bytes[0].to_i(16))
+      self[:b1].from_human(bytes[1].to_i(16))
+      self[:b0].from_human(bytes[2].to_i(16))
+      self
+    end
+
+    # Get OUI in human readable form (colon-separated bytes)
+    # @return [String]
+    def to_human
+      fields.map { |m| '%02x' % self[m] }.join(':')
+    end
+  end
+end