string.rb in ronin-0.3.0

- old
+ new

@@ -1,9 +1,7 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -16,11 +14,10 @@
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/formatting/extensions/binary/integer'
 require 'ronin/formatting/extensions/text'
 require 'ronin/arch'
@@ -28,16 +25,26 @@
 require 'base64'
 
 class String
 
   #
-  # Packs the integer using the specified _arch_ and the given
-  # _address_length_. The _address_length_ will default to the address
-  # length of the _arch_.
+  # Packs an Integer from a String, which was originally packed for
+  # a specific architecture and address-length.
   #
+  # @param [Ronin::Arch] arch
+  #   The architecture that the Integer was originally packed with.
+  #
+  # @param [Integer] address_length
+  #   The number of bytes to depack.
+  #
+  # @return [Integer]
+  #   The depacked Integer.
+  #
+  # @example
   #   0x41.pack(Arch('i686')) # => "A\000\000\000"
   #
+  # @example
   #   0x41.pack(Arch('ppc'),2) # => "\000A"
   #
   def depack(arch,address_length=arch.address_length)
     integer = 0x0
     byte_index = 0
@@ -59,22 +66,26 @@
 
     return integer
   end
 
   #
-  # Returns the hex escaped form of the string.
+  # @return [String]
+  #   The hex escaped version of the String.
   #
+  # @example
   #   "hello".hex_escape
   #   # => "\\x68\\x65\\x6c\\x6c\\x6f"
   #
   def hex_escape(options={})
     format_bytes(options) { |b| "\\x%.2x" % b }
   end
 
   #
-  # Returns an unescaped version of the hex escaped string.
+  # @return [String]
+  #   The unescaped version of the hex escaped String.
   #
+  # @example
   #   "\\x68\\x65\\x6c\\x6c\\x6f".hex_unescape
   #   # => "hello"
   #
   def hex_unescape
     buffer = ''
@@ -124,59 +135,71 @@
 
     return buffer
   end
 
   #
-  # XOR encodes the string using the specified _key_.
+  # XOR encodes the String.
   #
+  # @param [Integer] key
+  #   The byte to XOR against each byte in the String.
+  #
+  # @return [String]
+  #   The XOR encoded String.
+  #
+  # @example
+  #   "hello".xor(0x41)
+  #   # => ")$--."
+  #
   def xor(key)
     encoded = ''
 
     each_byte { |b| encoded << (b ^ key).chr }
     return encoded
   end
 
   #
-  # Returns the base64 encoded form of the string.
+  # Base64 encodes a string.
   #
+  # @return [String]
+  #   The base64 encoded form of the string.
+  #
   def base64_encode
     Base64.encode64(self)
   end
 
   #
-  # Returns the base64 decoded form of the string.
+  # Base64 decodes a string.
   #
+  # @return [String]
+  #   The base64 decoded form of the string.
+  #
   def base64_decode
     Base64.decode64(self)
   end
 
   #
   # Converts a multitude of hexdump formats back into the original
-  # raw-data using the given _options_.
+  # raw-data.
   #
-  # _options_ may contain the following keys:
-  # <tt>:format</tt>:: The expected format of the hexdump. Must be either
-  #                    <tt>:od</tt> or <tt>:hexdump</tt>.
-  # <tt>:encoding</tt>:: Denotes the encoding used for the bytes within the
-  #                      hexdump. Must be one of the following:
-  #                      <tt>:binary</tt>:: Binary encoded bytes.
-  #                      <tt>:octal</tt>:: Octal encoding.
-  #                      <tt>:octal_bytes</tt>:: Octal encoded bytes.
-  #                      <tt>:octal_shorts</tt>:: Octal encoded shorts.
-  #                      <tt>:octal_ints</tt>:: Octal encoded integers.
-  #                      <tt>:octal_quads</tt>:: Octal encoded quads.
-  #                      <tt>:decimal</tt>:: Unsigned decimal encoding.
-  #                      <tt>:decimal_bytes</tt>:: Unsigned decimal bytes.
-  #                      <tt>:decimal_shorts</tt>:: Unsigned decimal shorts.
-  #                      <tt>:decimal_ints</tt>:: Unsigned decimal ints.
-  #                      <tt>:decimal_quads</tt>:: Unsigned decimal quads.
-  #                      <tt>:hex</tt>:: Hexadecimal encoding.
-  #                      <tt>:hex_bytes</tt>:: Hexadecimal bytes.
-  #                      <tt>:hex_shorts</tt>:: Hexadecimal shorts.
-  #                      <tt>:hex_ints</tt>:: Hexadecimal ints.
-  #                      <tt>:hex_quads</tt>:: Hexadecimal quads.
-  # <tt>:segment</tt>:: The length in bytes of each segment in the hexdump.
-  #                     Defaults to 16, if not specified.
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Symbol] :format
+  #   The expected format of the hexdump. Must be either +:od+ or
+  #   +:hexdump+.
+  #
+  # @option options [Symbol] :encoding
+  #   Denotes the encoding used for the bytes within the hexdump.
+  #   Must be one of the following: +:binary+, +:octal+, +:octal_bytes+
+  #   +:octal_shorts+, +:octal_ints+, :octal_quads+, +:decimal+,
+  #   +:decimal_bytes+, +:decimal_shorts+, +:decimal_ints+,
+  #   +:decimal_quads+, +:hex+ +:hex_bytes+, +:hex_shorts+, +:hex_ints+ or
+  #   +:hex_quads+.
+  #
+  # @option options [Integer] :segment (16)
+  #   The length in bytes of each segment in the hexdump.
+  #
+  # @return [String] The raw-data from the hexdump.
   #
   def unhexdump(options={})
     case (format = options[:format])
     when :od
       address_base = base = 8