nucleon 0.2.2 → 0.2.3

data/lib/core/util/data.rb

@@ -1,77 +1,193 @@
 
 module Nucleon
 module Util
+#
+# == Data utilities
+#
+# The Nucleon::Util::Data class defines various tools for working with data in
+# the Nucleon system.
+#
+# It implements:
+# 1. Type checkers
+# 2. Basic data translators
+# 3. Data transformations
+# 4. Other utilities
+#
 class Data
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Type checking
-  
+
+  # Check if given value is undefined.
+  #
+  # It currently checks for: (our definition of undefined)
+  # * *nil*
+  # * Symbols: *:undef*, *:undefined*
+  # * Strings: "*undef*", "*UNDEF*", "*Undef*", "*nil*", "*NIL*", "*Nil*"
+  #
+  # This method was created to provide an easy way for us to load and work with
+  # configurations from text formats, such as JSON.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Value to check if undefined
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if value is undefined, false otherwise
+  #
+  # * *Errors*
+  #
   def self.undef?(value)
-    if value.nil? || 
-      (value.is_a?(Symbol) && value == :undef || value == :undefined) || 
+    if value.nil? ||
+      (value.is_a?(Symbol) && value == :undef || value == :undefined) ||
       (value.is_a?(String) && value.match(/^\s*(undef|UNDEF|Undef|nil|NIL|Nil)\s*$/))
       return true
     end
-    return false  
+    return false
   end
-  
-  #---
-  
+
+  # Check if given value is true.
+  #
+  # It currently checks for: (our definition of true)
+  # * *true*
+  # * Symbols: *:true*
+  # * Strings: "*true*", "*TRUE*", "*True*"
+  #
+  # This method was created to provide an easy way for us to load and work with
+  # configurations from text formats, such as JSON.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Value to check if true
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if value is true, false otherwise
+  #
+  # * *Errors*
+  #
   def self.true?(value)
-    if value == true || 
+    if value == true ||
+      (value.is_a?(Symbol) && value == :true) ||
       (value.is_a?(String) && value.match(/^\s*(true|TRUE|True)\s*$/))
       return true
     end
-    return false  
+    return false
   end
-  
-  #---
-  
+
+  # Check if given value is false.
+  #
+  # It currently checks for: (our definition of false)
+  # * *false*
+  # * Symbols: *:false*
+  # * Strings: "*false*", "*FALSE*", "*False*"
+  #
+  # This method was created to provide an easy way for us to load and work with
+  # configurations from text formats, such as JSON.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Value to check if false
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if value is false, false otherwise
+  #
+  # * *Errors*
+  #
   def self.false?(value)
-    if value == false || 
+    if value == false ||
+      (value.is_a?(Symbol) && value == :false) ||
       (value.is_a?(String) && value.match(/^\s*(false|FALSE|False)\s*$/))
       return true
     end
-    return false  
+    return false
   end
-  
-  #---
-  
+
+  # Check if given value is empty.
+  #
+  # It currently checks for: (our definition of empty)
+  # * ::undef?
+  # * ::false?
+  # * value.empty?
+  #
+  # This method was created to provide an easy way for us to load and work with
+  # configurations from text formats, such as JSON.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Value to check if empty
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if value is empty, false otherwise
+  #
+  # * *Errors*
+  #
   def self.empty?(value)
     if undef?(value) || false?(value) || (value.respond_to?('empty?') && value.empty?)
       return true
     end
     return false
   end
-  
-  #---
-  
+
+  # Check if given keys exist in data hash.
+  #
+  # This method allows for the easy checking of nested keys.  It takes care of
+  # traversing the data structure and checking for empty recursively.
+  #
+  # * *Parameters*
+  #   - [Hash<String, Symbol|...|ANY>] *data*  Data object to check
+  #   - [Array<String, Symbol>] *keys*  Hash key path (nested keys)
+  #   - [Boolean] *check_empty*  Whether to check element for emptiness
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if keys exist and not empty, false otherwise if check_empty
+  #   - [Boolean]  Returns true if keys exist, false otherwise
+  #
+  # * *Errors*
+  #
+  # See:
+  # - ::empty?
+  #
   def self.exists?(data, keys, check_empty = false)
     if keys.is_a?(String) || keys.is_a?(Symbol)
       keys = [ keys ]
-    end    
+    end
     key = keys.shift.to_sym
-    
+
     if data.has_key?(key)
       value = data[key]
-      
+
       if keys.empty?
         return false if check_empty && empty?(value)
         return true
       else
-        return exists?(data[key], keys)  
+        return exists?(data[key], keys)
       end
     end
     return false
   end
-   
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Translation
 
+  # Return hash as a symbol map.
+  #
+  # This method converts all hash keys to symbols.  Nested hashes are
+  # recursively translated as well.
+  #
+  # This comes in really handy when performing operations across hashes in Ruby
+  # because of the distinction between symbols and strings.
+  #
+  # * *Parameters*
+  #   - [Hash<String, Symbol|...|ANY>] *data*  Hash data to symbolize keys
+  #
+  # * *Returns*
+  #   - [Hash<Symbol|...|ANY>]  Returns data structure symbolized
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::string_map
+  #
   def self.symbol_map(data)
     results = {}
     return data unless data
-    
+
     case data
     when Hash
       data.each do |key, value|
@@ -79,16 +195,33 @@ class Data
       end
     else
       results = data
-    end    
+    end
     return results
   end
-  
-  #---
-  
+
+  # Return hash as a string map.
+  #
+  # This method converts all hash keys to strings.  Nested hashes are
+  # recursively translated as well.
+  #
+  # This comes in really handy when performing operations across hashes in Ruby
+  # because of the distinction between symbols and strings.
+  #
+  # * *Parameters*
+  #   - [Hash<String, Symbol|...|ANY>] *data*  Hash data to stringify keys
+  #
+  # * *Returns*
+  #   - [Hash<String|...|ANY>]  Returns data structure grouped by string keys
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::symbol_map
+  #
   def self.string_map(data)
     results = {}
     return data unless data
-    
+
     case data
     when Hash
       data.each do |key, value|
@@ -96,36 +229,111 @@ class Data
       end
     else
       results = data
-    end    
+    end
     return results
   end
-  
-  #---
-  
+
+  # Parse a JSON string into a Ruby data object.
+  #
+  # This method uses the MultiJson gem to carry out the heavy lifting. We just
+  # sit back and enjoy the ride.
+  #
+  # * *Parameters*
+  #   - [String] *json_text*  JSON text string to parse into Ruby data
+  #
+  # * *Returns*
+  #   - [nil, true, false, String, Array, Hash<String|...|ANY>]  Returns parsed data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::to_json
+  #
   def self.parse_json(json_text)
     return MultiJson.load(json_text)
   end
-    
-  #---
-  
+
+  # Dump a Ruby object to a JSON string.
+  #
+  # This method uses the MultiJson gem to carry out the heavy lifting. We just
+  # sit back and enjoy the ride.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to render JSON string
+  #
+  # * *Returns*
+  #   - [String]  Returns JSON rendered data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::parse_json
+  #
   def self.to_json(data, pretty = true)
     return MultiJson.dump(data, :pretty => pretty)
   end
-  
-  #---
-  
+
+  # Parse a YAML string into a Ruby data object.
+  #
+  # This method uses the Ruby YAML module to carry out the heavy lifting. We
+  # just sit back and enjoy the ride.
+  #
+  # * *Parameters*
+  #   - [String] *yaml_text*  YAML text string to parse into Ruby data
+  #
+  # * *Returns*
+  #   - [nil, true, false, String, Array, Hash<String|...|ANY>]  Returns parsed data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::to_yaml
+  #
   def self.parse_yaml(yaml_text)
     return YAML.load(yaml_text)
   end
-  
-  #---
-  
+
+  # Dump a Ruby object to a YAML string.
+  #
+  # This method uses the Ruby YAML module to carry out the heavy lifting. We
+  # just sit back and enjoy the ride.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to render YAML string
+  #
+  # * *Returns*
+  #   - [String]  Returns YAML rendered data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::parse_yaml
+  #
   def self.to_yaml(data)
     return YAML.dump(data)
   end
-  
-  #---
-  
+
+  # Translate a value to internally standardized form.
+  #
+  # It currently translates:
+  # * ::undef? to *undefined_value*
+  # * ::true? to *true*
+  # * ::false? to *false*
+  # * Array (recursively)
+  # * Hash (recursively)
+  #
+  # This method was created to provide an easy way for us to load and work with
+  # configurations from text formats, such as JSON.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Value to internalize
+  #   - [ANY] *undefined_value*  Value that represents undefined (*nil*)
+  #
+  # * *Returns*
+  #   - [ANY]  Returns internalized value object
+  #
+  # * *Errors*
+  #
   def self.value(value, undefined_value = nil)
     case value
     when String
@@ -136,34 +344,89 @@ class Data
       elsif false?(value)
         value = false
       end
-    
+
     when Array
       value.each_with_index do |item, index|
         value[index] = value(item, undefined_value)
       end
-    
+
     when Hash
       value.each do |key, data|
         value[key] = value(data, undefined_value)
       end
     end
-    return value  
+    return value
   end
-  
-  #---
-      
+
+  # Run a defined filter on a data object.
+  #
+  # This method ensures that a given data object meets some criteria or else
+  # an empty value for that type is returned that matches the criteria.
+  #
+  # Currently implemented filters:
+  # 1. ::array  Ensure result is an array (non arrays are converted)
+  # 2. ::hash   Ensure result is a hash (non hashes are converted)
+  # 3. ::string Ensure result is a string (non strings are converted)
+  # 4. ::symbol Ensure result is a symbol (non symbols are converted)
+  # 5. ::test   Ensure result is not empty (runs a boolean ::empty? check)
+  #
+  # More filters can be added by adding methods to the Nucleon::Util::Data class.
+  #
+  # For example:
+  #
+  #   module Nucleon::Util::Data
+  #     def my_filter(data, default = '')
+  #       # Return data modified or default
+  #     end
+  #   end
+  #
+  #   my_data = Nucleon::Util::Data.filter(my_data, :my_filter)
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data object to run through filter
+  #   - [false, String] *method*  Filter method to execute or false for none
+  #
+  # * *Returns*
+  #   - [ANY]  Returns filtered data object
+  #
+  # * *Errors*
+  #
   def self.filter(data, method = false)
-    if method && method.is_a?(Symbol) && 
-      [ :array, :hash, :string, :symbol, :test ].include?(method.to_sym)
-      return send(method, data)
+    if method && respond_to?(method.to_sym)
+      return send(method.to_sym, data)
     end
     return data
   end
-  
-  #---
-          
+
+  # Ensure a data object is an array.
+  #
+  # It converts:
+  # 1. Symbols to arrays
+  # 2. Strings to arrays
+  # 3. Splits strings on commas (if *split_string* requested)
+  # 4. If no array found, returns *default*
+  #
+  # TODO: Parameter for string separator split
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to ensure array
+  #   - [Array] *default*  Default value if no array is found
+  #   - [Boolean] *split_string*  Whether to split strings on comma
+  #
+  # * *Returns*
+  #   - [Array]  Returns an array
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::filter (switch)
+  # - ::hash
+  # - ::string
+  # - ::symbol
+  # - ::test
+  #
   def self.array(data, default = [], split_string = false)
-    result = default    
+    result = default
     if data
       case data
       when Array
@@ -176,11 +439,30 @@ class Data
     end
     return result
   end
-    
-  #---
-        
+
+  # Ensure a data object is a hash.
+  #
+  # If data is given and it is not a hash, an empty hash is returned in it's
+  # place.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to ensure hash
+  #   - [Hash] *default*  Default value if no data is given (nil)
+  #
+  # * *Returns*
+  #   - [Hash]  Returns a hash
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::filter (switch)
+  # - ::array
+  # - ::string
+  # - ::symbol
+  # - ::test
+  #
   def self.hash(data, default = {})
-    result = default    
+    result = default
     if data
       case data
       when Hash
@@ -191,11 +473,30 @@ class Data
     end
     return result
   end
-    
-  #---
-         
+
+  # Ensure a data object is a string.
+  #
+  # If data is given and it is not a string, the data.to_s method is called to
+  # get the rendered string.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to ensure string
+  #   - [String] *default*  Default value if no data is given (nil)
+  #
+  # * *Returns*
+  #   - [String]  Returns a string
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::filter (switch)
+  # - ::array
+  # - ::hash
+  # - ::symbol
+  # - ::test
+  #
   def self.string(data, default = '')
-    result = default    
+    result = default
     if data
       case data
       when String
@@ -206,13 +507,35 @@ class Data
     end
     return result
   end
-    
-  #---
-         
+
+  # Ensure a data object is a symbol.
+  #
+  # If data is given and it is not a symbol, the data.to_sym method is called to
+  # get the generated symbol.  If data is not a string or symbol, it's class name
+  # is symbolized.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to ensure symbol
+  #   - [Symbol] *default*  Default value if no data is given (:undefined)
+  #
+  # * *Returns*
+  #   - [Symbol]  Returns a symbol
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::filter (switch)
+  # - ::array
+  # - ::hash
+  # - ::string
+  # - ::test
+  #
   def self.symbol(data, default = :undefined)
-    result = default    
+    result = default
     if data
       case data
+      when TrueClass, FalseClass
+        result = data ? :true : :false
       when Symbol
         result = data
       when String
@@ -223,17 +546,48 @@ class Data
     end
     return result
   end
-     
-  #---
-    
+
+  # Test a data object for emptiness and return boolean result.
+  #
+  # Uses the ::empty? method to check for emptiness.
+  #
+  # * *Parameters*
+  #   - [ANY] *data*  Ruby data to test for emptiness
+  #
+  # * *Returns*
+  #   - [Boolean]  Returns true if data not empty, false otherwise
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::filter (switch)
+  # - ::array
+  # - ::hash
+  # - ::string
+  # - ::symbol
+  #
   def self.test(data)
     return false if Util::Data.empty?(data)
     return true
   end
-    
-  #-----------------------------------------------------------------------------
-  # Operations
-  
+
+  #*****************************************************************************
+  # Transformation
+
+  # Clean nil or empty values out of a hash object.
+  #
+  # * *Parameters*
+  #   - [Hash] *data*  Ruby data to clean properties
+  #   - [Boolean] *remove_empty*  Whether or not to remove empty values or just nil
+  #
+  # * *Returns*
+  #   - [Hash]  Returns hash with all nil or empty values scrubbed (depending on *remove_empty*)
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::deep_clean (recursive clean)
+  #
   def self.clean(data, remove_empty = true)
     data.keys.each do |key|
       obj = data[key]
@@ -241,178 +595,327 @@ class Data
     end
     data
   end
-  
-  #---
-  
+
+  # Recursively clean nil or empty values out of a hash object.
+  #
+  # * *Parameters*
+  #   - [Hash] *data*  Ruby data to clean properties
+  #   - [Boolean] *remove_empty*  Whether or not to remove empty values or just nil
+  #
+  # * *Returns*
+  #   - [Hash]  Returns hash with all nil or empty values scrubbed (depending on *remove_empty*)
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::clean (shallow clean)
+  #
   def self.deep_clean(data, remove_empty = true)
     data.keys.each do |key|
       obj = data[key]
-        
+
       if obj.nil? || ( remove_empty && obj.is_a?(Hash) && obj.empty? )
         data.delete(key)
-          
+
       elsif data[key].is_a?(Hash)
         deep_clean(data[key], remove_empty)
       end
     end
     data
   end
-  
-  #---
-  
+
+  # Recursively clone an array or tree based hash object.
+  #
+  # * *Parameters*
+  #   - [Hash, Array] *data*  Ruby data to recursively clone
+  #
+  # * *Returns*
+  #   - [Hash]  Returns completely new nested hash if hash data given
+  #   - [Array] Returns completely new array if array data given
+  #
+  # * *Errors*
+  #
+  #
+  def self.clone(data)
+    if data.is_a?(Array)
+      new_data = []
+      data.each do |item|
+        new_data << clone(item)
+      end
+    elsif data.is_a?(Hash)
+      new_data = {}
+      data.each do |key, value|
+        new_data[key] = clone(value)
+      end
+    else
+      new_data = data
+    end
+    new_data
+  end
+
+  # Merge data objects together.
+  #
+  # This method relies on the merging capabilities of the deep_merge gem. It
+  # switches between core Ruby shallow merge and deep_merge merges based on
+  # the *basic* boolean.
+  #
+  # Elements at the end of the array override values for data at the beginning.
+  #
+  # * *Parameters*
+  #   - [Array<nil, String, Symbol, Array, Hash>] *data*  Ruby data objects to merge
+  #   - [Boolean] *force*  Whether or not to force override of values where types don't match
+  #   - [Boolean] *basic*  Whether or not to perform a basic merge or deep (recursive) merge
+  #
+  # * *Returns*
+  #   - [nil, String, Symbol, Array, Hash]  Returns merged data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::undef?
+  #
   def self.merge(data, force = true, basic = true)
     value = data
-    
-    # Special case because this method is called from within Config.new so we 
+
+    # Special case because this method is called from within Config.new so we
     # can not use Config.ensure, as that would cause an infinite loop.
     if force.is_a?(Nucleon::Config)
       basic = force.get(:basic, true)
-      force = force.get(:force, true)      
+      force = force.get(:force, true)
     end
-    
+
     if data.is_a?(Array)
       value = undef?(data[0]) ? nil : data.shift.clone
-      
+
       data.each do |item|
         item = undef?(item) ? nil : item.clone
-        
+
         case value
         when Hash
           if basic
             if item.is_a?(Hash)
-              value = value.merge(item)              
+              value = value.merge(item)
             elsif force
               value = item
-            end  
+            end
           else
             begin
               require 'deep_merge'
               value = force ? value.deep_merge!(item) : value.deep_merge(item)
-              
+
             rescue LoadError
               if item.is_a?(Hash) # Non recursive top level by default.
-                value = value.merge(item)              
+                value = value.merge(item)
               elsif force
                 value = item
               end
             end
-          end  
+          end
         when Array
           if item.is_a?(Array)
             value = value.concat(item).uniq
           elsif force
             value = item
           end
-                
+
         else
           value = item if force || item.is_a?(String) || item.is_a?(Symbol)
         end
-      end  
+      end
     end
     return value
   end
 
-  #---
-  
-  def self.interpolate(value, scope, options = {})    
-    
+  # Interpolate values into data objects based on patterns.
+  #
+  # This method interpolates values into either a single string or a hash of
+  # strings that are recursively processed.
+  #
+  # This method requires our Hash#search method defined in the mod folder.
+  #
+  # * *Parameters*
+  #   - [String, Hash] *value*  Value to interpolate properties into
+  #   - [Hash] *scope*  Property values for text replacements
+  #   - [Hash] *options*  Method options
+  #     - [String] *:pattern*  Regexp pattern to match intepolated properties against
+  #     - [Integer] *:var_group*  Regexp group match for property name
+  #     - [String] *:flags*  Optional Regexp flags
+  #
+  # * *Returns*
+  #   - [String, Hash]  Returns interpolated string or hash of strings
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Hash#search
+  #
+  def self.interpolate(value, scope, options = {})
+
     pattern = ( options.has_key?(:pattern) ? options[:pattern] : '\$(\{)?([a-zA-Z0-9\_\-]+)(\})?' )
     group   = ( options.has_key?(:var_group) ? options[:var_group] : 2 )
     flags   = ( options.has_key?(:flags) ? options[:flags] : '' )
-    
+
     if scope.is_a?(Hash)
       regexp = Regexp.new(pattern, flags.split(''))
-    
+
       replace = lambda do |item|
         matches = item.match(regexp)
         result  = nil
-        
+
         unless matches.nil?
           replacement = scope.search(matches[group], options)
           result      = item.gsub(matches[0], replacement) unless replacement.nil?
         end
         return result
       end
-      
+
       case value
       when String
         while (temp = replace.call(value))
           value = temp
         end
-        
+
       when Hash
         value.each do |key, data|
           value[key] = interpolate(data, scope, options)
         end
       end
     end
-    return value  
+    return value
   end
-  
-  #---
-  
+
+  # Remove keys from a given hash.
+  #
+  # This method first symbolizes all keys of the hash and then deletes any
+  # matching elements if the *symbolize* option is given.
+  #
+  # * *Parameters*
+  #   - [Hash] *data*  Ruby hash to remove keys from
+  #   - [String, Symbol, Array] *keys*  Keys to remove from
+  #   - [Boolean] *symbolize*  Whether or not to symbolize data keys before removal
+  #
+  # * *Returns*
+  #   - [Hash]  Returns cleaned data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::hash
+  # - ::symbol_map
+  #
   def self.rm_keys(data, keys, symbolize = false)
     keys = [ keys ] unless keys.is_a?(Array)
     data = hash(data)
     data = symbol_map(data) if symbolize
-    
+
     keys.each do |key|
       key = key.to_sym if symbolize
       data.delete(key)
     end
     data
   end
-  
-  #---
-  
+
+  # Select specific keys from a given hash.
+  #
+  # This method first symbolizes all keys of the hash and then deletes any
+  # matching elements if the *symbolize* option is given.
+  #
+  # * *Parameters*
+  #   - [Hash] *data*  Ruby hash to select keys from
+  #   - [String, Symbol, Array] *keys*  Keys to select
+  #   - [Boolean] *symbolize*  Whether or not to symbolize data keys before selection
+  #
+  # * *Returns*
+  #   - [Hash]  Returns data object with selected keys
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::hash
+  # - ::symbol_map
+  #
   def self.subset(data, keys, symbolize = false)
     keys     = [ keys ] unless keys.is_a?(Array)
     data     = hash(data)
     data     = symbol_map(data) if symbolize
     new_data = {}
-     
+
     keys.each do |key|
       key           = key.to_sym if symbolize
       new_data[key] = data[key] if data.has_key?(key)
     end
-    new_data 
+    new_data
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Utilities
-  
+
+  # Prefix every element in data with prefix separated by pad.
+  #
+  # This method basically just does bulk prefixing.  This has come in useful in
+  # quite a few applications, particularly with dealing with configurations.
+  #
+  # This method can recursively set prefixes for hash keys as well.
+  #
+  # * *Parameters*
+  #   - [String] *prefix*  Prefix string to prepend to data elements
+  #   - [String, Symbol, Array, Hash] *data*  Data elements to prefix
+  #   - [String] *pad*  Whether or not to symbolize data keys before selection
+  #
+  # * *Returns*
+  #   - [String, Symbol, Array, Hash]  Returns prefixed data object
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::empty?
+  #
   def self.prefix(prefix, data, pad = '_')
     result = nil
-    
-    unless prefix.is_a?(String) && ! empty?(prefix)
+
+    unless prefix.is_a?(Symbol) || ( prefix.is_a?(String) && ! empty?(prefix) )
       prefix = ''
     end
-    
+    prefix = prefix.to_s
+
     case data
     when String, Symbol
       result = ( prefix.empty? ? data.to_s : prefix + pad + data.to_s )
-      
+
     when Array
       result = []
       data.each do |value|
         result << prefix(prefix, value, pad)
       end
-      
+
     when Hash
       result = {}
       data.each do |key, value|
-        result[prefix(prefix, key, pad)] = value  
-      end      
+        result[prefix(prefix, key, pad)] = value
+      end
     end
     return result
   end
-  
-  #---
-  
+
+  # Ensure a value is set one way or another depending on a test condition.
+  #
+  # * *Parameters*
+  #   - [Boolean] *test*  Test for success / failure
+  #   - [ANY] *success_value*  Value returned if test is not empty
+  #   - [ANY] *failure_value*  Value returned if test is empty
+  #
+  # * *Returns*
+  #   - [ANY]  Success or failure values depending on the outcome of test
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - ::empty?
+  #
   def self.ensure(test, success_value = nil, failure_value = nil)
     success_value = (success_value ? success_value : test)
     failure_value = (failure_value ? failure_value : nil)
-      
+
     if empty?(test)
       value = failure_value
     else
@@ -420,9 +923,21 @@ class Data
     end
     return value
   end
-  
-  #---
-  
+
+  # Return value if not empty or else return failure value.
+  #
+  # * *Parameters*
+  #   - [ANY] *value*  Test for success / failure
+  #   - [ANY] *failure_value*  Value returned if value is empty
+  #
+  # * *Returns*
+  #   - [ANY]  Value or failure value depending on the emptiness of value
+  #
+  # * *Errors*
+  #
+  # See:
+  # - ::ensure
+  #
   def self.ensure_value(value, failure_value = nil)
     return self.ensure(value, nil, failure_value)
   end