ronin-support 1.0.0 → 1.0.2

data/lib/ronin/support/binary/byte_slice.rb

@@ -69,15 +69,15 @@ module Ronin
 
           case string
           when ByteSlice
-            if (offset < 0) || (offset+length > string.bytesize)
+            if (offset < 0) || ((offset + length) > string.bytesize)
               raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{string.bytesize}")
             end
 
             @string = string.string
-            @offset = string.offset+offset
+            @offset = string.offset + offset
             @length = length
           when String
-            if (offset < 0) || (offset+length > string.bytesize)
+            if (offset < 0) || ((offset + length) > string.bytesize)
               raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{string.bytesize}")
             end
 
@@ -109,17 +109,17 @@ module Ronin
           when Range
             range = index_or_range
 
-            @string[@offset+range.begin,range.end-range.begin]
+            @string[@offset + range.begin,range.end - range.begin]
           when Integer
             index = index_or_range
 
             case length
             when Integer
-              @string[@offset+index,length]
+              @string[@offset + index,length]
             when nil
-              @string[@offset+index]
+              @string[@offset + index]
             when Float::INFINITY
-              @string[@offset+index,@length-index]
+              @string[@offset + index,@length - index]
             else
               raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
             end
@@ -151,17 +151,17 @@ module Ronin
           when Range
             range = index_or_range
 
-            @string[@offset+range.begin,range.end-range.begin] = value
+            @string[@offset + range.begin,range.end - range.begin] = value
           when Integer
             index = index_or_range
 
             case length
             when Integer
-              @string[@offset+index,length] = value
+              @string[@offset + index,length] = value
             when nil
-              @string[@offset+index] = value
+              @string[@offset + index] = value
             when Float::INFINITY
-              @string[@offset+index,@length-index] = value
+              @string[@offset + index,@length - index] = value
             else
               raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
             end
@@ -200,7 +200,7 @@ module Ronin
         #   found.
         #
         def index(substring,offset=0)
-          if (index = @string.index(substring,@offset+offset))
+          if (index = @string.index(substring,@offset + offset))
             if index < (@offset + @length)
               index - @offset
             end
@@ -211,13 +211,13 @@ module Ronin
         # Gets the byte at the given index within the byte slice.
         #
         # @param [Integer] index
-        # 
+        #
         # @return [Integer, nil]
         #   The byte at the given index, or nil if the index is out of bounds.
         #
         def getbyte(index)
           if index < @length
-            @string.getbyte(@offset+index)
+            @string.getbyte(@offset + index)
           end
         end
 
@@ -235,7 +235,7 @@ module Ronin
         #
         def setbyte(index,byte)
           if index < @length
-            @string.setbyte(@offset+index,byte)
+            @string.setbyte(@offset + index,byte)
           else
             raise(IndexError,"index #{index.inspect} is out of bounds")
           end
@@ -257,7 +257,7 @@ module Ronin
         def each_byte
           return enum_for(__method__) unless block_given?
 
-          (@offset...(@offset+@length)).each do |index|
+          (@offset...(@offset + @length)).each do |index|
             yield @string.getbyte(index)
           end
         end
@@ -288,7 +288,7 @@ module Ronin
         def each_char
           return enum_for(__method__) unless block_given?
 
-          (@offset...(@offset+@length)).each do |index|
+          (@offset...(@offset + @length)).each do |index|
             yield @string[index]
           end
         end

data/lib/ronin/support/binary/core_ext.rb

@@ -16,6 +16,8 @@
 # along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
+require 'ronin/support/binary/core_ext/integer'
+require 'ronin/support/binary/core_ext/float'
 require 'ronin/support/binary/core_ext/string'
 require 'ronin/support/binary/core_ext/array'
 require 'ronin/support/binary/core_ext/io'

data/lib/ronin/support/binary/cstring.rb

@@ -24,6 +24,49 @@ module Ronin
       #
       # Represents a null terminated C string.
       #
+      # ## Examples
+      #
+      # ### Initializing C Strings
+      #
+      # From a String:
+      #
+      #     str = Binary::CString.new("hello ")
+      #     # => #<Ronin::Support::Binary::CString:0x00007fc94ba577f8 @string="hello \u0000">
+      #
+      # From a binary C string:
+      #
+      #     str = Binary::CString.new("world\0".b)
+      #     # => #<Ronin::Support::Binary::CString:0x00007fc94ba06f88 @string="world\u0000">
+      #
+      # From characters:
+      #
+      #     str = Binary::CString['A', 'B', 'C']
+      #     # => #<Ronin::Support::Binary::CString:0x00007fc94ba6f268 @string="ABC\x00">
+      #
+      # ### Modifying C Strings
+      #
+      # Concating Strings to a C String:
+      #
+      #     str = Binary::CString.new("hello ")
+      #     str.concat("world")
+      #     # => #<Ronin::Support::Binary::CString:0x00007fc94b978df0 @string="hello world\u0000">
+      #     str.to_s
+      #     # => "hello world"
+      #
+      # Appending two C Strings:
+      #
+      #     str1 = Binary::CString.new("hello ")
+      #     str2 = Binary::CString.new("world\0")
+      #     str = str1 + str2
+      #     # => #<Ronin::Support::Binary::CString:0x00007fc94b9523f8 @string="hello world\u0000">
+      #
+      # Setting characters:
+      #
+      #     str = Binary::CString.new("hello")
+      #     str[0] = 'X'
+      #     str.to_s
+      #     # => "Xello"
+      #
       # @api public
       #
       # @since 1.0.0
@@ -101,14 +144,15 @@ module Ronin
         # @return [self]
         #
         def concat(value)
-          value = case value
-                  when Integer then value.chr
-                  else              value.to_s
-                  end
+          value      = case value
+                       when Integer then value.chr
+                       else              value.to_s
+                       end
           value_size = value.bytesize
 
           unless value.include?(NULL)
             value = "#{value}#{NULL}"
+
             value_size += 1
           end
 
@@ -153,6 +197,7 @@ module Ronin
 
           @string.each_char do |char|
             break if char == NULL
+
             yield char
           end
         end
@@ -185,6 +230,7 @@ module Ronin
 
           @string.each_byte do |byte|
             break if byte == 0x00
+
             yield byte
           end
         end

data/lib/ronin/support/binary/ctypes/arch/arm/big_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module ARM
+            #
+            # Represents the C types for the ARM architecture, in big-endian
+            # mode.
+            #
             module BigEndian
               include CTypes::BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/arm.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the ARM architecture.
+          #
           module ARM
             include LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/arm64/big_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module ARM64
+            #
+            # Represents the C types for the ARM64 architecture, in big-endian
+            # mode.
+            #
             module BigEndian
               include CTypes::BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/arm64.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the ARM64 architecture.
+          #
           module ARM64
             include LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/mips/little_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module MIPS
+            #
+            # Represents the C types for the MIPS architecture, in little-endian
+            # mode.
+            #
             module LittleEndian
               include CTypes::LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/mips.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the MIPS architecture.
+          #
           module MIPS
             include BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/mips64/little_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module MIPS64
+            #
+            # Represents the C types for the MIPS64 architecture,
+            # in little-endian mode.
+            #
             module LittleEndian
               include CTypes::LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/mips64.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the MIPS64 architecture.
+          #
           module MIPS64
             include BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/ppc.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the PPC architecture.
+          #
           module PPC
             include BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/ppc64.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the PPC64 architecture.
+          #
           module PPC64
             include BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/x86.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the x86 architecture.
+          #
           module X86
             include LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/x86_64.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the x86-64 architecture.
+          #
           module X86_64
             include LittleEndian
 

data/lib/ronin/support/binary/ctypes/array_type.rb

@@ -60,7 +60,7 @@ module Ronin
           #   Custom type alignment to override the type's alignment.
           #
           def initialize(type,length, alignment: nil)
-            if type.class == UnboundedArrayType
+            if type.kind_of?(UnboundedArrayType)
               raise(ArgumentError,"cannot initialize an #{self.class} of #{UnboundedArrayType}")
             end
 
@@ -152,7 +152,7 @@ module Ronin
             if @pack_string
               super(array)
             else
-              buffer = String.new("", encoding: Encoding::ASCII_8BIT)
+              buffer = String.new
 
               @length.times do |index|
                 value = array[index] || @type.uninitialized_value

data/lib/ronin/support/binary/ctypes/big_endian.rb

@@ -33,6 +33,9 @@ module Ronin
   module Support
     module Binary
       module CTypes
+        #
+        # Represents the C types, but in big-endian byte-order.
+        #
         module BigEndian
           include CharTypes
 

data/lib/ronin/support/binary/ctypes/enum_type.rb

@@ -54,8 +54,8 @@ module Ronin
           def initialize(int_type,mapping)
             super(pack_string: nil)
 
-            @int_type = int_type
-            @mapping  = mapping
+            @int_type        = int_type
+            @mapping         = mapping
             @reverse_mapping = @mapping.invert
           end
 

data/lib/ronin/support/binary/ctypes/little_endian.rb

@@ -33,6 +33,9 @@ module Ronin
   module Support
     module Binary
       module CTypes
+        #
+        # Represents the C types, but in little-endian byte-order.
+        #
         module LittleEndian
           include CharTypes
 

data/lib/ronin/support/binary/ctypes/native.rb

@@ -32,6 +32,9 @@ module Ronin
   module Support
     module Binary
       module CTypes
+        #
+        # Represents the system's native C types.
+        #
         module Native
           include CharTypes
 

data/lib/ronin/support/binary/ctypes/os/bsd.rb

@@ -33,7 +33,7 @@ module Ronin
           class BSD < UNIX
 
             #
-            # Initializes the FreeBSD types object.
+            # Initializes the common BSD types object.
             #
             # @param [#[]] types
             #   The base types module.

data/lib/ronin/support/binary/ctypes/scalar_type.rb

@@ -82,7 +82,7 @@ module Ronin
             @signed    = signed
           end
 
-          # 
+          #
           # Whether the scalar type is signed.
           #
           # @return [Boolean]
@@ -91,7 +91,7 @@ module Ronin
             @signed
           end
 
-          # 
+          #
           # Whether the scalar type is unsigned.
           #
           # @return [Boolean]

data/lib/ronin/support/binary/ctypes/struct_type.rb

@@ -214,9 +214,9 @@ module Ronin
           #   The uninitialized values for the new struct's members.
           #
           def uninitialized_value
-            Hash[@members.map { |name,member|
-              [name, member.type.uninitialized_value]
-            }]
+            @members.transform_values do |member|
+              member.type.uninitialized_value
+            end
           end
 
           #

data/lib/ronin/support/binary/ctypes/type_resolver.rb

@@ -155,9 +155,9 @@ module Ronin
           #
           def resolve_struct(type_signature)
             struct_class   = type_signature
-            struct_members = Hash[struct_class.members.map { |name,member|
-              [name, resolve(member.type_signature)]
-            }]
+            struct_members = struct_class.members.transform_values { |member|
+              resolve(member.type_signature)
+            }
 
             struct_type = StructType.build(
               struct_members, alignment: struct_class.alignment,
@@ -176,9 +176,9 @@ module Ronin
           #
           def resolve_union(type_signature)
             union_class   = type_signature
-            union_members = Hash[union_class.members.map { |name,member|
-              [name, resolve(member.type_signature)]
-            }]
+            union_members = union_class.members.transform_values { |member|
+              resolve(member.type_signature)
+            }
 
             union_type = UnionType.build(
               union_members, alignment: union_class.alignment
@@ -191,7 +191,7 @@ module Ronin
           # Resolves a type name.
           #
           # @param [Symbol] name
-          # 
+          #
           # @return [Type]
           #
           def resolve_symbol(name)
@@ -203,4 +203,3 @@ module Ronin
     end
   end
 end
-

data/lib/ronin/support/binary/ctypes/unbounded_array_type.rb

@@ -47,7 +47,7 @@ module Ronin
           #   Cannot initialize a nested {UnboundedArrayType}.
           #
           def initialize(type, alignment: nil)
-            if type.class == UnboundedArrayType
+            if type.kind_of?(UnboundedArrayType)
               raise(ArgumentError,"cannot initialize a nested #{UnboundedArrayType}")
             end
 
@@ -149,7 +149,7 @@ module Ronin
             if @pack_string
               super(array)
             else
-              buffer = String.new('', encoding: Encoding::ASCII_8BIT)
+              buffer = String.new
 
               array.each do |element|
                 buffer << @type.pack(element)

data/lib/ronin/support/binary/ctypes/union_type.rb

@@ -162,9 +162,9 @@ module Ronin
           #   The uninitialized values for the new union's members.
           #
           def uninitialized_value
-            Hash[@members.map { |name,member|
-              [name, member.type.uninitialized_value]
-            }]
+            @members.transform_values do |member|
+              member.type.uninitialized_value
+            end
           end
 
           #

data/lib/ronin/support/binary/ctypes.rb

@@ -61,7 +61,7 @@ module Ronin
       #   * Floating Point Types:
       #     * {CTypes::Float32Type float} (`-3.40282347E+38F` -
       #       `3.40282347E+38F`)
-      #     * {CTypes::Float64Type double} (`-1.79769313486231570E+308` - 
+      #     * {CTypes::Float64Type double} (`-1.79769313486231570E+308` -
       #       `1.79769313486231570E+308`)
       # * Aggregate Types:
       #   * {CTypes::ArrayType Array} (ex: `{1,2,3}`)
@@ -182,7 +182,7 @@ module Ronin
         UINT32_NET = Network::UINT32
         UINT64_NET = Network::UINT64
 
-        WORD_NET = Network::WORD
+        WORD_NET  = Network::WORD
         DWORD_NET = Network::DWORD
         QWORD_NET = Network::QWORD
 
@@ -390,7 +390,7 @@ module Ronin
           openbsd: OS::OpenBSD,
           netbsd:  OS::NetBSD,
 
-          linux:   OS:: Linux,
+          linux:   OS::Linux,
           macos:   OS::MacOS,
           windows: OS::Windows
         }

data/lib/ronin/support/binary/memory.rb

@@ -145,7 +145,7 @@ module Ronin
 
             case length
             when Integer then @string[index,length] = value
-            when nil     then @string[index] = value
+            when nil     then @string[index]        = value
             when Float::INFINITY
               @string[index,@string.length - index] = value
             else
@@ -157,7 +157,7 @@ module Ronin
         end
 
         #
-        # Returns a byte slice of the memory at the given offset and for the 
+        # Returns a byte slice of the memory at the given offset and for the
         # remainder of the memory.
         #
         # @param [Integer] offset

data/lib/ronin/support/binary/packet.rb

@@ -21,6 +21,86 @@ require 'ronin/support/binary/struct'
 module Ronin
   module Support
     module Binary
+      #
+      # Represents a network packet in network byte-order.
+      #
+      # ## Examples
+      #
+      # ### Defining Packet Fields
+      #
+      #     class Packet < Ronin::Support::Binary::Packet
+      #
+      #       member :flags,  :uint8
+      #       member :src,    :uint32
+      #       member :dst,    :uint32
+      #       member :length, :uint32
+      #
+      #     end
+      #
+      # ### Initializing Packets
+      #
+      # From a Hash:
+      #
+      #     packet = Packet.new(
+      #       flags:  0x0c,
+      #       src:    IPAddr.new('1.2.3.4').to_i,
+      #       dst:    IPAddr.new('5.6.7.8').to_i,
+      #       length: 1024
+      #     )
+      #
+      # From a buffer:
+      #
+      #     packet = Packet.unpack("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
+      #
+      # ### Reading Fields
+      #
+      #     packet = Packet.new("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
+      #     packet[:flags]
+      #     # => 12
+      #     packet.flags
+      #     # => 12
+      #
+      # ### Packing Packets
+      #
+      #     class Packet < Ronin::Support::Binary::Packet
+      #
+      #       member :flags,  :uint8
+      #       member :src,    :uint32
+      #       member :dst,    :uint32
+      #       member :length, :uint32
+      #
+      #     end
+      #
+      #     packet = Packet.new(
+      #       flags:  0x0c,
+      #       src:    IPAddr.new('1.2.3.4').to_i,
+      #       dst:    IPAddr.new('5.6.7.8').to_i,
+      #       length: 1024
+      #     )
+      #     packet.pack
+      #     # => "\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00"
+      #
+      # ### Unpacking Packets
+      #
+      #     class Packet < Ronin::Support::Binary::Packet
+      #
+      #       member :flags,  :uint8
+      #       member :src,    :uint32
+      #       member :dst,    :uint32
+      #       member :length, :uint32
+      #
+      #     end
+      #
+      #     packet = Packet.unpack("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
+      #     packet.flags
+      #     # => 12
+      #     packet.src
+      #     # => 16909060
+      #     packet.dst
+      #     # => 84281096
+      #     packet.length
+      #     # => 1024
+      #
       class Packet < Binary::Struct
 
         platform endian: :net