bin_struct 0.1.0

data/lib/bin_struct/enum.rb

@@ -0,0 +1,200 @@
+# 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
+  # @abstract Base enum class to handle binary integers with limited
+  #   authorized values
+  # An {Enum} type is used to handle an {Int} field with limited
+  # and named values.
+  #
+  # == Simple example
+  #  enum = Int8Enum.new('low' => 0, 'medium' => 1, 'high' => 2})
+  # In this example, +enum+ is a 8-bit field which may take one
+  # among three values: +low+, +medium+ or +high+:
+  #  enum.value = 'high'
+  #  enum.value              # => 2
+  #  enum.value = 1
+  #  enum.value              # => 1
+  #  enum.to_human           # => "medium"
+  # Setting an unknown value will raise an exception:
+  #  enum.value = 4          # => raise!
+  #  enum.value = 'unknown'  # => raise!
+  # But {#read} will not raise when reading an outbound value. This
+  # to enable decoding (or forging) of bad packets.
+  # @author Sylvain Daubert
+  class Enum < Int
+    # @return [Hash]
+    attr_reader :enum
+
+    # @param [Hash] options
+    # @see Int#initialize
+    # @option options [Hash] enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
+    # @option options [Integer,String] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      enum = options[:enum]
+      raise TypeError, 'enum must be defined as a Hash' unless enum.is_a?(Hash)
+
+      options[:default] ||= enum[enum.keys.first]
+      super
+      @enum = enum
+    end
+
+    # Setter for value attribute
+    # @param [#to_i, String,nil] value value as an Integer or as a String
+    #   from enumration
+    # @return [Integer]
+    # @raise [ArgumentError] String value is unknown
+    def value=(value)
+      ival = case value
+             when NilClass
+               nil
+             when ::String
+               raise ArgumentError, "#{value.inspect} not in enumeration" unless @enum.key?(value)
+
+               @enum[value]
+             else
+               value.to_i
+             end
+      @value = ival
+    end
+
+    # To handle human API: set value from a String
+    alias from_human value=
+
+    # Get human readable value (enum name)
+    # @return [String]
+    def to_human
+      @enum.key(to_i) || "<unknown:#{@value}>"
+    end
+
+    def format_inspect
+      format_str % [to_human, to_i]
+    end
+  end
+
+  # Enumeration on one byte. See {Enum}.
+  # @author LemonTree55
+  class Int8Enum < Enum
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    def initialize(options = {})
+      opts = options.slice(:enum, :value, :default)
+      opts[:width] = 1
+      opts[:endian] = nil
+      super(opts)
+      @packstr = { nil => 'C' }
+    end
+  end
+
+  # Enumeration on 2-byte integer. See {Enum}.
+  # @author LemonTree55
+  class Int16Enum < Enum
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [:big,:little] :endian
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    def initialize(options = {})
+      opts = options.slice(:enum, :endian, :default, :value)
+      opts[:endian] ||= :big
+      opts[:width] = 2
+      super(opts)
+      @packstr = { big: 'n', little: 'v' }
+    end
+  end
+
+  # Enumeration on big endian 2-byte integer. See {Enum}.
+  # @author Sylvain Daubert
+  class Int16beEnum < Int16Enum
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = options.slice(:enum, :default, :value)
+      opts[:endian] = :big
+      super(opts)
+    end
+  end
+
+  # Enumeration on big endian 2-byte integer. See {Enum}.
+  # @author Sylvain Daubert
+  class Int16leEnum < Int16Enum
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = options.slice(:enum, :default, :value)
+      opts[:endian] = :little
+      super(opts)
+    end
+  end
+
+  # Enumeration on 4-byte integer. See {Enum}.
+  # @author LemonTree55
+  class Int32Enum < Enum
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [:big,:little] :endian
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    def initialize(options = {})
+      opts = options.slice(:enum, :endian, :default, :value)
+      opts[:endian] ||= :big
+      opts[:width] = 4
+      super(opts)
+      @packstr = { big: 'N', little: 'V' }
+    end
+  end
+
+  # Enumeration on big endian 4-byte integer. See {Enum}.
+  # @author Sylvain Daubert
+  class Int32beEnum < Int32Enum
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = options.slice(:enum, :default, :value)
+      opts[:endian] = :big
+      super(opts)
+    end
+  end
+
+  # Enumeration on big endian 4-byte integer. See {Enum}.
+  # @author Sylvain Daubert
+  # @since 2.1.3
+  class Int32leEnum < Int32Enum
+    undef endian=
+
+    # @param [Hash] options
+    # @option options [Hash] :enum
+    # @option options [Integer,::String] :value
+    # @option options [Integer,::String] :default
+    # @author LemonTree55
+    def initialize(options = {})
+      opts = options.slice(:enum, :default, :value)
+      opts[:endian] = :little
+      super(opts)
+    end
+  end
+end

data/lib/bin_struct/fieldable.rb

@@ -0,0 +1,64 @@
+# 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
+  # Mixin to define minimal API for a class to be embbeded as a field in
+  # {Fields} type.
+  #
+  # == Optional methods
+  # These methods may, optionally, be defined by fieldable types:
+  # * +from_human+ to load data from a human-readable string.
+  # @author Sylvain Daubert
+  # @since 3.1.6
+  module Fieldable
+    # Get type name
+    # @return [String]
+    def type_name
+      self.class.to_s.split('::').last
+    end
+
+    # rubocop:disable Lint/UselessMethodDefinition
+    # These methods are defined for documentation.
+
+    # Populate object from a binary string
+    # @param [String] str
+    # @return [Fields] self
+    # @abstract subclass should overload it.
+    def read(str)
+      super
+    end
+
+    # Return object as a binary string
+    # @return [String]
+    # @abstract subclass should overload it.
+    def to_s
+      super
+    end
+
+    # Size of object as binary string
+    # @return [Integer]
+    def sz
+      to_s.size
+    end
+
+    # Return a human-readbale string
+    # @return [String]
+    # @abstract subclass should overload it.
+    def to_human
+      super
+    end
+
+    # rubocop:enable Lint/UselessMethodDefinition
+
+    # Format object when inspecting a {Fields} object
+    # @return [String]
+    def format_inspect
+      to_human
+    end
+  end
+end