lib/ronin/formatting/extensions/text/string.rb in ronin-0.2.4 vs lib/ronin/formatting/extensions/text/string.rb in ronin-0.3.0

@@ -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,67 +14,103 @@
 # 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 'chars'
 
 class String
 
   #
-  # Creates a new String by passing each byte to the specified _block_
-  # using the given _options_.
+  # Creates a new String by formatting each byte.
   #
-  # _options_ may include the following keys:
-  # <tt>:included</tt>:: The set of characters that will be formated,
-  #                      defaults to <tt>Chars.all</tt>.
-  # <tt>:excluded</tt>:: The characters not to format.
+  # @param [Hash] options
+  #   Additional options.
   #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
+  #
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
+  #
+  # @yield [byte]
+  #   The block which will return the formatted version of each byte
+  #   within the String.
+  #
+  # @yieldparam [Integer] byte
+  #   The byte to format.
+  #
+  # @return [String]
+  #   The formatted version of the String.
+  #
   def format_bytes(options={},&block)
-    included = (options[:included] || Chars.all)
+    included = (options[:included] || (0x00..0xff))
     excluded = (options[:excluded] || [])
 
-    targeted = included - excluded
     formatted = ''
 
     self.each_byte do |b|
-      if targeted.include_byte?(b)
+      c = b.chr
+
+      if ((included.include?(b) || included.include?(c)) \
+          && !(excluded.include?(b) || excluded.include?(c)))
         formatted << block.call(b)
       else
         formatted << b
       end
     end
 
     return formatted
   end
 
   #
-  # Creates a new String by passing each character to the specified _block_
-  # using the given _options_.
+  # Creates a new String by formatting each character.
   #
-  # _options_ may include the following keys:
-  # <tt>:included</tt>:: The set of characters that will be formated,
-  #                      defaults to <tt>Chars.all</tt>.
-  # <tt>:excluded</tt>:: The characters not to format.
+  # @param [Hash] options
+  #   Additional options.
   #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
+  #
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
+  #
+  # @yield [char]
+  #   The block which will return the formatted version of each character
+  #   within the String.
+  #
+  # @yieldparam [String] char
+  #   The character to format.
+  #
+  # @return [String]
+  #   The formatted version of the String.
+  #
   def format_chars(options={},&block)
     format_bytes(options) do |b|
       block.call(b.chr)
     end
   end
 
   #
-  # Creates a new String by randomizing the case of each character using
-  # the given _options_.
+  # Creates a new String by randomizing the case of each character in the
+  # String.
   #
-  # _options_ may include the following keys:
-  # <tt>:probability</tt>:: The probability that a character will have it's
-  #                         case changed; defaults to 0.5.
+  # @param [Hash] options
+  #   Additional options.
   #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
+  #
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
+  #
+  # @option options [Float] :probability (0.5)
+  #   The probability that a character will have it's case changed.
+  #
+  # @example
   #   "get out your checkbook".random_case
   #   # => "gEt Out YOur CHEckbook"
   #
   def random_case(options={})
     prob = (options[:probability] || 0.5)
@@ -89,13 +123,22 @@
       end
     end
   end
 
   #
-  # Pads the string using the specified _padding_ out to the given
-  # _max_length_. _max_length_ will default to the strings own length,
-  # if not given.
+  # Creates a new String by padding the String with repeating text,
+  # out to a specified length.
   #
+  # @param [String] padding
+  #   The text to pad the new String with.
+  #
+  # @param [String] max_length
+  #   The maximum length to pad the new String out to.
+  #
+  # @return [String]
+  #   The padded version of the String.
+  #
+  # @example
   #   "hello".pad('A',50)
   #   # => "helloAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
   #
   def pad(padding,max_length=self.length)
     padding = padding.to_s