bin_struct 0.1.0 → 0.2.1

data/lib/bin_struct/int.rb

@@ -9,10 +9,10 @@
 module BinStruct
   # Base integer class to handle binary integers
   # @abstract
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class Int
-    include Fieldable
+    include Structable
 
     # Integer value
     # @return [Integer,nil]
@@ -21,22 +21,22 @@ module BinStruct
     # @return [:little,:big,:native,nil]
     attr_accessor :endian
     # Integer size, in bytes
-    # @return [Integer, nil]
+    # @return [Integer]
     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
+    # @option options [Integer, nil] :value Value to set Int to
+    # @option options [:little,:big,:native,nil] :endian Int's endianess
+    # @option options [Integer,nil] :width Int's width in bytes
+    # @option options [Integer] :default Default value to use when {#value} is not set (Default to +0+).
     # @author LemonTree55
     def initialize(options = {})
       @value = options[:value]
       @endian = options[:endian]
-      @width = options[:width]
+      @width = options[:width] || 0
       @default = options[:default] || 0
     end
 
@@ -69,6 +69,7 @@ module BinStruct
     end
     alias to_human to_i
 
+    # Initialize value from an Integer.
     # @param [Integer] value
     # @return [self]
     def from_human(value)
@@ -88,8 +89,8 @@ module BinStruct
       width
     end
 
-    # Format Int type when inspecting header or packet
-    # @return [String]
+    # Format Int type when inspecting Struct
+    # @return [::String]
     def format_inspect
       format_str % [to_i.to_s, to_i]
     end
@@ -108,12 +109,10 @@ module BinStruct
   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
@@ -123,12 +122,10 @@ module BinStruct
   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
@@ -138,12 +135,12 @@ module BinStruct
   end
 
   # 2-byte unsigned integer
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class Int16 < Int
     # @param [Hash] options
     # @option options [Integer,nil] :value
-    # @option [:big, :little, :native] :endian
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = { value: options[:value], endian: options[:endian] || :big, width: 2 }
       super(opts)
@@ -151,17 +148,16 @@ module BinStruct
     end
   end
 
-  # big endian 2-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 2-byte unsigned integer
+  # @author Sylvain Daubert (2016-2024)
   class Int16be < Int16
     undef endian=
   end
 
-  # little endian 2-byte unsigned integer
-  # @author Sylvain Daubert
+  # Little endian 2-byte unsigned integer
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class Int16le < Int16
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -172,16 +168,13 @@ module BinStruct
     end
   end
 
-  # native endian 2-byte unsigned integer
-  # @author Sylvain Daubert
+  # Native endian 2-byte unsigned integer
   # @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)
@@ -189,12 +182,12 @@ module BinStruct
   end
 
   # 2-byte signed integer
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class SInt16 < Int16
     # @param [Hash] options
     # @option options [Integer,nil] :value
-    # @author LemonTree55
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = { value: options[:value], endian: options[:endian] || :big }
       super(opts)
@@ -202,20 +195,20 @@ module BinStruct
     end
   end
 
-  # big endian 2-byte signed integer
-  # @author Sylvain Daubert
+  # Big endian 2-byte signed integer
+  # @author Sylvain Daubert (2016-2024)
   class SInt16be < SInt16
     undef endian=
   end
 
-  # little endian 2-byte signed integer
-  # @author Sylvain Daubert
+  # Little endian 2-byte signed integer
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class SInt16le < SInt16
-    # @param [Integer,nil] value
     undef endian=
 
-    # @param [Integer, nil] value
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
     # @author LemonTree55
     def initialize(options = {})
       opts = { value: options[:value], endian: :little }
@@ -223,15 +216,14 @@ module BinStruct
     end
   end
 
-  # native endian 2-byte signed integer
-  # @author Sylvain Daubert
+  # Native endian 2-byte signed integer
+  # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class SInt16n < SInt16
-    # @param [Integer,nil] value
     undef endian=
 
-    # @param [Integer, nil] value
-    # @author LemonTree55
+    # @param [Hash] options
+    # @option options [Integer,nil] :value
     def initialize(options = {})
       opts = { value: options[:value], endian: :native }
       super(opts)
@@ -259,8 +251,8 @@ module BinStruct
       super(opts)
     end
 
-    # Read an 3-byte Int from a binary string
-    # @param [String] str
+    # Read a 3-byte Int from a binary string
+    # @param [::String] value
     # @return [self]
     def read(value)
       return self if value.nil?
@@ -275,7 +267,7 @@ module BinStruct
       self
     end
 
-    # @author Sylvain Daubert
+    # @author Sylvain Daubert (2016-2024)
     # @return [::String]
     def to_s
       up8 = to_i >> 16
@@ -288,16 +280,15 @@ module BinStruct
     end
   end
 
-  # big endian 3-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 3-byte unsigned integer
+  # @author Sylvain Daubert (2016-2024)
   class Int24be < Int24
     undef endian=
   end
 
-  # little endian 3-byte unsigned integer
+  # Little endian 3-byte unsigned integer
   # @author LemonTree55
   class Int24le < Int24
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -308,10 +299,9 @@ module BinStruct
     end
   end
 
-  # native endian 3-byte unsigned integer
+  # Native endian 3-byte unsigned integer
   # @author LemonTree55
   class Int24n < Int24
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -327,7 +317,7 @@ module BinStruct
   class Int32 < Int
     # @param [Hash] options
     # @option options [Integer,nil] :value
-    # @option [:big, :little, :native] :endian
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = { value: options[:value], endian: options[:endian] || :big, width: 4 }
       super(opts)
@@ -335,16 +325,15 @@ module BinStruct
     end
   end
 
-  # big endian 4-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 4-byte unsigned integer
+  # @author Sylvain Daubert (2016-2024)
   class Int32be < Int32
     undef endian=
   end
 
-  # little endian 4-byte unsigned integer
+  # Little endian 4-byte unsigned integer
   # @author LemonTree55
   class Int32le < Int32
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -355,10 +344,9 @@ module BinStruct
     end
   end
 
-  # native endian 4-byte unsigned integer
+  # Native endian 4-byte unsigned integer
   # @author LemonTree55
   class Int32n < Int32
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -369,12 +357,12 @@ module BinStruct
     end
   end
 
-  # 4-byte unsigned integer
+  # 4-byte signed integer
   # @author LemonTree55
   class SInt32 < Int32
     # @param [Hash] options
     # @option options [Integer] :value
-    # @option options [:big, :little, :native] :endian
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = { value: options[:value], endian: options[:endian] || :big }
       super(opts)
@@ -382,16 +370,15 @@ module BinStruct
     end
   end
 
-  # big endian 4-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 4-byte signed integer
+  # @author Sylvain Daubert (2016-2024)
   class SInt32be < SInt32
     undef endian=
   end
 
-  # little endian 4-byte unsigned integer
+  # Little endian 4-byte signed integer
   # @author LemonTree55
   class SInt32le < SInt32
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -402,10 +389,9 @@ module BinStruct
     end
   end
 
-  # native endian 4-byte unsigned integer
+  # Native endian 4-byte signed integer
   # @author LemonTree55
   class SInt32n < SInt32
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -421,7 +407,7 @@ module BinStruct
   class Int64 < Int
     # @param [Hash] options
     # @option options [Integer] :value
-    # @option options [:big, :little, :native] :endian
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = options.slice(:value, :endian)
       opts[:endian] ||= :big
@@ -431,16 +417,15 @@ module BinStruct
     end
   end
 
-  # big endian 8-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 8-byte unsigned integer
+  # @author Sylvain Daubert (2016-2024)
   class Int64be < Int64
     undef endian=
   end
 
-  # little endian 8-byte unsigned integer
+  # Little endian 8-byte unsigned integer
   # @author LemonTree55
   class Int64le < Int64
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -451,10 +436,9 @@ module BinStruct
     end
   end
 
-  # native endian 8-byte unsigned integer
+  # Native endian 8-byte unsigned integer
   # @author LemonTree55
   class Int64n < Int64
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -465,12 +449,12 @@ module BinStruct
     end
   end
 
-  # 8-byte unsigned integer
+  # 8-byte signed integer
   # @author LemonTree55
   class SInt64 < Int64
     # @param [Hash] options
     # @option options [Integer] :value
-    # @option options [:big, :little, :native] :endian
+    # @option options [:big,:little,:native] :endian
     def initialize(options = {})
       opts = options.slice(:value, :endian)
       super(opts)
@@ -478,16 +462,15 @@ module BinStruct
     end
   end
 
-  # big endian 8-byte unsigned integer
-  # @author Sylvain Daubert
+  # Big endian 8-byte signed integer
+  # @author Sylvain Daubert (2016-2024)
   class SInt64be < SInt64
     undef endian=
   end
 
-  # little endian 8-byte unsigned integer
+  # Little endian 8-byte signed integer
   # @author LemonTree55
   class SInt64le < SInt64
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options
@@ -498,10 +481,9 @@ module BinStruct
     end
   end
 
-  # native endian 8-byte unsigned integer
+  # Native endian 8-byte signed integer
   # @author LemonTree55
   class SInt64n < SInt64
-    # @param [Integer,nil] value
     undef endian=
 
     # @param [Hash] options

data/lib/bin_struct/int_string.rb

@@ -7,27 +7,29 @@
 # This program is published under MIT license.
 
 module BinStruct
-  # Provides a class for creating strings preceeded by their length as a {Int}.
+  # Provides a class for creating strings preceeded by their length as an {Int}.
   # By default, a null string will have one byte length (length byte set to 0).
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class IntString
-    include Fieldable
+    include Structable
 
     # internal string
-    # @return [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 +''+
+    # @option options [::String] :value String value. Default to +""+
     def initialize(options = {})
-      @string = BinStruct::String.new.read(options[:string] || '')
+      @string = BinStruct::String.new.read(options[:value] || +'')
       @length = (options[:length_type] || Int8).new
       calc_length
     end
 
+    # Populate IntString from a binary String
     # @param [::String] str
-    # @return [IntString] self
+    # @return [self]
     def read(str)
       unless str[0, @length.width].size == @length.width
         raise Error,
@@ -38,19 +40,25 @@ module BinStruct
       self
     end
 
+    # Set length
     # @param [Integer] len
     # @return [Integer]
     def length=(len)
       @length.from_human(len)
+      # rubocop:disable Lint/Void
+      len
+      # rubocop:enable Lint/Void
     end
 
+    # Get length as registered in +IntLength+
     # @return [Integer]
     def length
       @length.to_i
     end
 
+    # Set string without setting {#length}
     # @param [#to_s] str
-    # @return [String]
+    # @return [::String]
     def string=(str)
       @length.value = str.to_s.size
       @string = str.to_s
@@ -63,17 +71,16 @@ module BinStruct
     end
 
     # Set from a human readable string
-    # @param [String] str
+    # @param [::String] str
     # @return [self]
     def from_human(str)
-      @string.read str
+      @string.read(str)
       calc_length
       self
     end
 
     # Get human readable string
     # @return [::String]
-    # @since 2.2.0
     def to_human
       @string
     end
@@ -81,10 +88,10 @@ module BinStruct
     # Set length from internal string length
     # @return [Integer]
     def calc_length
-      @length.read @string.length
+      @length.from_human(@string.length)
     end
 
-    # Give binary string length (including +length+ field)
+    # Give binary string length (including +length+ attribute)
     # @return [Integer]
     def sz
       to_s.size

data/lib/bin_struct/length_from.rb

@@ -10,16 +10,16 @@ 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
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   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.
+    # Initialize +length_from+ capacity.
+    # Should be called by extended object's initialize method.
     # @param [Hash] options
-    # @option options [Types::Int,Proc] :length_from object or proc from which
+    # @option options [Int,Proc] :length_from object or proc from which
     #   takes length when reading
     # @return [void]
     def initialize_length_from(options)
@@ -28,7 +28,7 @@ module BinStruct
 
     # Return a substring from +str+ of length given in another object.
     # @param [#to_s] str
-    # @return [String]
+    # @return [::String]
     def read_with_length_from(str)
       s = BinStruct.force_binary(str.to_s)
       s[0, sz_to_read]

data/lib/bin_struct/oui.rb

@@ -11,23 +11,26 @@ module BinStruct
   #  oui = OUI.new
   #  oui.from_human('00:01:02')
   #  oui.to_human   # => "00:01:02"
-  # @author Sylvain Daubert
-  class OUI < Fields
-    include Fieldable
+  #  oui.to_s       # => "\x00\x01\x03"
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
+  class OUI < Struct
+    include Structable
 
     # @attribute b2
     #  @return [Integer] left-most byte
-    define_field :b2, Int8
+    define_attr :b2, Int8
     # @attribute b1
     #  @return [Integer] center byte
-    define_field :b1, Int8
+    define_attr :b1, Int8
     # @attribute b0
     #  @return [Integer] right-most byte
-    define_field :b0, Int8
+    define_attr :b0, Int8
 
     # Read a human-readable string to populate object
-    # @param [String] str
-    # @return [OUI] self
+    # @param [::String] str
+    # @return [self]
+    # @raise [ArgumentError] OUI cannot be recognized from +str+
     def from_human(str)
       return self if str.nil?
 
@@ -41,9 +44,9 @@ module BinStruct
     end
 
     # Get OUI in human readable form (colon-separated bytes)
-    # @return [String]
+    # @return [::String]
     def to_human
-      fields.map { |m| '%02x' % self[m] }.join(':')
+      attributes.map { |m| '%02x' % self[m] }.join(':')
     end
   end
 end

data/lib/bin_struct/string.rb

@@ -9,42 +9,49 @@
 require 'forwardable'
 
 module BinStruct
-  # This class mimics regular String, but it is {Fieldable}.
-  # @author Sylvain Daubert
-  # @since 3.1.6 no more a subclass or regular String
+  # This class mimics regular String, but it is {Structable}.
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class String
     extend Forwardable
-    include Fieldable
+    include Structable
     include LengthFrom
 
-    def_delegators :@string, :[], :to_s, :length, :size, :inspect, :==,
+    def_delegators :@string, :[], :length, :size, :inspect, :==,
                    :unpack, :force_encoding, :encoding, :index, :empty?,
                    :encode, :slice, :slice!, :[]=
 
+    # Underlying Ruby String
     # @return [::String]
     attr_reader :string
+    # String static length, if set
     # @return [Integer]
     attr_reader :static_length
 
     # @param [Hash] options
-    # @option options [Types::Int,Proc] :length_from object or proc from which
+    # @option options [Int,Proc] :length_from object or proc from which
     #   takes length when reading
     # @option options [Integer] :static_length set a static length for this string
+    # @option options [::String] :value string value (default to +''+)
     def initialize(options = {})
-      register_internal_string(+'')
+      register_internal_string(options[:value] || +'')
       initialize_length_from(options)
       @static_length = options[:static_length]
     end
 
+    # Initialize object on copying:
+    # * duplicate underlying Ruby String
+    # @return [void]
     def initialize_copy(_orig)
       @string = @string.dup
     end
 
+    # Populate String from a binary String. Limit length using {LengthFrom} or {#static_length}, if one is set.
     # @param [::String] str
-    # @return [String] self
+    # @return [self]
     def read(str)
       s = read_with_length_from(str)
-      register_internal_string s
+      register_internal_string(s)
       self
     end
 
@@ -52,9 +59,8 @@ module BinStruct
     private :old_sz_to_read
 
     # Size to read.
-    # Computed from static_length or length_from, if defined.
+    # Computed from {#static_length} or +length_from+, if one defined.
     # @return [Integer]
-    # @since 3.1.6
     def sz_to_read
       return static_length if static_length?
 
@@ -63,11 +69,12 @@ module BinStruct
 
     # Say if a static length is defined
     # @return [Boolean]
-    # @since 3.1.6
     def static_length?
       !static_length.nil?
     end
 
+    # Format String when inspecting from a {Struct}
+    # @return [::String]
     def format_inspect
       inspect
     end
@@ -76,10 +83,16 @@ module BinStruct
     # @param [#to_s] str
     # @return [self]
     def <<(str)
-      @string << str.to_s
+      @string << BinStruct.force_binary(str.to_s)
       self
     end
 
+    # Generate binary string
+    # @return [::String]
+    def to_s
+      @string
+    end
+
     alias sz length
     alias to_human to_s
     alias from_human read