bin_struct 0.1.0 → 0.2.1

data/lib/bin_struct/cstring.rb

@@ -10,30 +10,81 @@ 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
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class CString
     extend Forwardable
-    include Fieldable
-
+    include Structable
+
+    # @!method [](index)
+    #   @overload [](index)
+    #     Return the character at +index+.
+    #     @param [Integer] index
+    #   @overload [](start, length)
+    #     Return the substring starting at +start+ with +length+ length.
+    #     @param [Integer] start
+    #     @param [Integer] length
+    #   @return [::String,nil]
+    # @!method length
+    #   Return string length (without null-terminator)
+    #   @return [Integer]
+    # @method size
+    #   Return string length (without null-terminator)
+    #   @return [Integer]
+    #   @see #length
+    # @!method ==
+    #   Check equality with underlying Ruby String
+    #   @return [Boolean]
+    # @!method unpack
+    #   Apply unpack on underlying Ruby String
+    #   @see ::String#unpack
+    #   @return [::Array]
+    # @!method force_encoding
+    #   @see ::String#force_encoding
+    # @!method encoding
+    #   @see ::String#encoding
+    #   @return [Encoding]
+    # @!method index(substring, offset = 0)
+    #   Returns the Integer index of the first occurrence of the given substring, or +nil+ if none found.
+    #   @param [::String] substring
+    #   @param [Integer] offset
+    #   @return [Integer,nil]
+    # @!method empty?
+    #   Return +true+ is string is empty.
+    #   @return [Boolean]
+    # @!method encode(encoding, **options)
+    #   @return [::String]
+    #   @see ::String#encode
+    # @!method slice(*args)
+    #   Returns the substring of +self+ specified by the arguments.
+    #   @see ::String#slice
+    #   @return [String,nil]
+    # @!method slice!(*args)
+    #   Removes the substring of +self+ specified by the arguments; returns the removed substring.
+    #   @see ::String#slice!
+    #   @return [String,nil]
     def_delegators :@string, :[], :length, :size, :inspect, :==,
                    :unpack, :force_encoding, :encoding, :index, :empty?,
                    :encode, :slice, :slice!
 
+    # Underlying Ruby String
     # @return [::String]
     attr_reader :string
-    # @return [Integer]
+    # Static length, if any
+    # @return [Integer,nil]
     attr_reader :static_length
 
     # @param [Hash] options
     # @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] || +'')
       @static_length = options[:static_length]
     end
 
+    # Populate self from binary string
     # @param [::String] str
-    # @return [String] self
+    # @return [self]
     def read(str)
       s = str.to_s
       s = s[0, static_length] if static_length?
@@ -42,8 +93,8 @@ module BinStruct
       self
     end
 
-    # get null-terminated string
-    # @return [String]
+    # Get null-terminated string
+    # @return [::String]
     def to_s
       if static_length?
         s = string[0, static_length - 1]
@@ -63,6 +114,7 @@ module BinStruct
       self
     end
 
+    # Get C String size in bytes
     # @return [Integer]
     def sz
       if static_length?
@@ -74,19 +126,19 @@ module BinStruct
 
     # 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
+    # @param [::String] str
     # @return [self]
     def from_human(str)
       read str
     end
 
-    # @return [String]
+    # Get human-readable string
+    # @return [::String]
     def to_human
       string
     end

data/lib/bin_struct/enum.rb

@@ -9,12 +9,12 @@
 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
+  # An {Enum} type is used to handle an {Int} attribute 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
+  # In this example, +enum+ is a 8-bit attribute which may take one
   # among three values: +low+, +medium+ or +high+:
   #  enum.value = 'high'
   #  enum.value              # => 2
@@ -26,16 +26,18 @@ module BinStruct
   #  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
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Enum < Int
-    # @return [Hash]
+    # Enumerated values
+    # @return [Hash{::String => Integer}]
     attr_reader :enum
 
     # @param [Hash] options
     # @see Int#initialize
-    # @option options [Hash] enum enumerated values. Default value is taken from
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
     #   first element unless given. This option is mandatory.
-    # @option options [Integer,String] :default
+    # @option options [Integer,::String] :default
     # @author LemonTree55
     def initialize(options = {})
       enum = options[:enum]
@@ -69,11 +71,13 @@ module BinStruct
     alias from_human value=
 
     # Get human readable value (enum name)
-    # @return [String]
+    # @return [::String]
     def to_human
       @enum.key(to_i) || "<unknown:#{@value}>"
     end
 
+    # Format Enum type when inspecting Struct
+    # @return [::String]
     def format_inspect
       format_str % [to_human, to_i]
     end
@@ -83,7 +87,8 @@ module BinStruct
   # @author LemonTree55
   class Int8Enum < Enum
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
     def initialize(options = {})
@@ -99,7 +104,8 @@ module BinStruct
   # @author LemonTree55
   class Int16Enum < Enum
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [:big,:little] :endian
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
@@ -113,15 +119,16 @@ module BinStruct
   end
 
   # Enumeration on big endian 2-byte integer. See {Enum}.
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Int16beEnum < Int16Enum
     undef endian=
 
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
-    # @author LemonTree55
     def initialize(options = {})
       opts = options.slice(:enum, :default, :value)
       opts[:endian] = :big
@@ -129,16 +136,17 @@ module BinStruct
     end
   end
 
-  # Enumeration on big endian 2-byte integer. See {Enum}.
-  # @author Sylvain Daubert
+  # Enumeration on little endian 2-byte integer. See {Enum}.
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Int16leEnum < Int16Enum
     undef endian=
 
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
-    # @author LemonTree55
     def initialize(options = {})
       opts = options.slice(:enum, :default, :value)
       opts[:endian] = :little
@@ -150,7 +158,8 @@ module BinStruct
   # @author LemonTree55
   class Int32Enum < Enum
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [:big,:little] :endian
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
@@ -164,15 +173,16 @@ module BinStruct
   end
 
   # Enumeration on big endian 4-byte integer. See {Enum}.
-  # @author Sylvain Daubert
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Int32beEnum < Int32Enum
     undef endian=
 
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
-    # @author LemonTree55
     def initialize(options = {})
       opts = options.slice(:enum, :default, :value)
       opts[:endian] = :big
@@ -180,17 +190,17 @@ module BinStruct
     end
   end
 
-  # Enumeration on big endian 4-byte integer. See {Enum}.
-  # @author Sylvain Daubert
-  # @since 2.1.3
+  # Enumeration on little endian 4-byte integer. See {Enum}.
+  # @author Sylvain Daubert (2016-2024)
+  # @author LemonTree55
   class Int32leEnum < Int32Enum
     undef endian=
 
     # @param [Hash] options
-    # @option options [Hash] :enum
+    # @option options [Hash{::String => Integer}] :enum enumerated values. Default value is taken from
+    #   first element unless given. This option is mandatory.
     # @option options [Integer,::String] :value
     # @option options [Integer,::String] :default
-    # @author LemonTree55
     def initialize(options = {})
       opts = options.slice(:enum, :default, :value)
       opts[:endian] = :little