hash_engine 0.3.0

data/lib/hash_engine.rb

@@ -0,0 +1,20 @@
+require 'hash_engine/actions'
+require 'hash_engine/fetchers'
+require 'hash_engine/conditionals'
+require 'hash_engine/format'
+require 'hash_engine/extract'
+require 'hash_engine/transform'
+require 'hash_engine/csv_parse'
+
+module HashEngine
+  extend Actions
+  extend Fetchers
+  extend Conditionals
+  extend Format
+  extend Extract
+  extend Transform
+  extend CSVParse
+  extend self
+
+  VERSION = '0.3.0'
+end

data/lib/hash_engine/actions.rb

@@ -0,0 +1,82 @@
+require 'hash_engine/format'
+
+module HashEngine
+  module Actions
+
+    include Format
+
+    @@actions = {}
+
+    def actions
+      @@actions
+    end
+
+    def add_action name, &block
+      @@actions[name] = block
+    end
+
+    def valid_action?(action)
+      actions.has_key?(action)
+    end
+
+    def action(type, field_data, fetched_data)
+      if valid_action?(type)
+        actions[type].call(fetched_data, field_data)
+      end
+    end
+
+    unprotected_proc = Proc.new do |data, action_data|
+      if action_data.is_a?(Proc)
+        action_data.call(*data)
+      else
+        eval(action_data).call(*data)
+      end
+    end
+
+    @@actions['proc'] = Proc.new do |data, action_data|
+      if data.is_a?(Array) && data.any?(&:nil?) || data.nil?
+        nil
+      else
+        unprotected_proc.call(data, action_data)
+      end
+    end
+
+    @@actions['unprotected_proc'] = unprotected_proc
+
+    @@actions['lookup_map'] = Proc.new do |key, hash|
+      if hash.has_key?(key) ||
+         hash.default ||
+         hash.default_proc then
+        hash[key]
+      elsif hash.has_key?('default') then
+        hash['default']
+      elsif hash.has_key?('default_to_key')
+        key
+      end
+    end
+
+    @@actions['join'] = Proc.new {|data, sep| data.is_a?(Array) ? data.join(sep) : data }
+    @@actions['first_value'] = Proc.new { |data, first| data.is_a?(Array) ? data.detect {|f| !(f.nil? || f.empty?)} : data }
+
+    # 1.8.7 behavior
+    @@actions['max_length'] = Proc.new {|data, length| /\w/u.match(data.to_s).to_s }
+    # 1.9.x behavior
+    if RUBY_VERSION > "1.9"
+      @@actions['max_length'] = Proc.new {|data, length| data.to_s.slice(0, length.to_i) }
+    end
+
+    @@actions['format'] = Proc.new do |data, format_instructions|
+      # puts "      Formatting data: #{data} with #{format_instructions}"
+      if format_instructions.is_a?(Hash) &&
+         format_instructions.has_key?('strftime') &&
+         data.respond_to?(:strftime) then
+        data.send(:strftime, format_instructions['strftime'])
+      elsif @@formats.has_key?(format_instructions)
+        @@formats[format_instructions][data]
+      else
+        data
+      end
+    end
+
+  end
+end

data/lib/hash_engine/add_error.rb

@@ -0,0 +1,13 @@
+module HashEngine
+  module AddError
+
+    def add_error(error_array, long, short)
+      if error_array.first == :long
+        error_array.push long
+      else
+        error_array.push short 
+      end
+    end
+
+  end
+end

data/lib/hash_engine/conditionals.rb

@@ -0,0 +1,32 @@
+module HashEngine
+  module Conditionals
+
+    @@conditionals = {}
+
+    def conditionals
+      @@conditionals
+    end
+
+    def add_conditional name, &block
+      @@conditionals[name] = block
+    end
+
+    def valid_conditional?(conditional)
+      conditionals.has_key?(conditional)
+    end
+
+    def conditional(type, left_operand, right_operand)
+      if valid_conditional?(type)
+        conditionals[type].call(left_operand, right_operand)
+      end
+    end
+
+    @@conditionals['ne'] = Proc.new {|left, right| left != right }
+    @@conditionals['eq'] = Proc.new {|left, right| left == right }
+    @@conditionals['lt'] = Proc.new {|left, right| left < right }
+    @@conditionals['gt'] = Proc.new {|left, right| left > right }
+    @@conditionals['lteq'] = Proc.new {|left, right| left <= right }
+    @@conditionals['gteq'] = Proc.new {|left, right| left >= right }
+    @@conditionals['exist'] = Proc.new {|left, right| !!left }
+  end
+end

data/lib/hash_engine/csv_parse.rb

@@ -0,0 +1,49 @@
+# Code based on FasterCSV 
+#  Created by James Edward Gray II on 2005-10-31.
+#  Copyright 2005 Gray Productions. All rights reserved.
+#
+# This is a cut down and simplified version for dealing with a single line
+
+module HashEngine
+  module CSVParse
+
+    QUOTE_CHAR = '"'.freeze
+    DEFAULT_DELIMITER = ','.freeze
+    QUOTED_FIELD = Regexp.new /^"(.*)"$/
+
+    def parse_line(line, headers, delimiter=DEFAULT_DELIMITER)
+      delimiter = DEFAULT_DELIMITER if delimiter.empty?
+      result = {:error => []}
+      unless line.empty?
+        parse = line.chomp
+        csv           = Array.new
+        current_field = String.new
+        field_quotes  = 0
+        parse.split(delimiter, -1).each do |match|
+          if current_field.empty? && match.count(QUOTE_CHAR).zero?
+            csv           << (match.empty? ? nil : match)
+          else
+            current_field << match
+            field_quotes += match.count(QUOTE_CHAR)
+            if field_quotes % 2 == 0
+              in_quotes = current_field[QUOTED_FIELD, 1] || current_field
+              current_field = in_quotes
+              current_field.gsub!(QUOTE_CHAR * 2, QUOTE_CHAR) # unescape contents
+              csv           << current_field
+              current_field =  String.new
+              field_quotes  =  0
+            else # we found a quoted field that spans multiple lines
+              current_field << delimiter
+            end
+          end
+        end
+        if csv.size == headers.size
+          headers.each_with_index {|name, index| result[name] = csv[index] }
+        else
+          result[:error] = ["header.size: #{headers.size} parsed_data.size: #{csv.size}"]
+        end
+      end
+      result
+    end
+  end
+end

data/lib/hash_engine/extract.rb

@@ -0,0 +1,139 @@
+require 'hash_engine/format'
+
+module HashEngine
+  module Extract
+    include Format
+
+    @@reserved_keys ||= {'method' => true, 'method_args' => true, 'cast' => true, 'required' => true}.freeze
+
+    # Collects data from a root object based on the provided instructions hash.
+    # The data is returned as a flat hash. A hash is used to specify the set of
+    # attributes which should be included in the .
+
+    def extract(objects, instructions)
+      if instructions.nil? || instructions.empty?
+        # can't do anything
+        {:error => ['Missing instructions']}
+      else
+        objects_to_walk = instructions.keys
+        if objects.nil?
+          {:error => ['Missing object(s)']}
+        else
+          if objects.is_a?(Hash)
+            # hash path
+            objects_given = objects.keys
+            if delta = objects_to_walk - objects_given and
+               !delta.empty?
+              {:error => ["Missing object(s): #{(delta).sort.join(', ')}"]}
+            else
+              # instructions for objects a, b, c
+              # given objects a, b, c
+              fetch_objects(objects_hash, objects_to_walk, instructions)
+            end
+          else
+            # single object path
+            if objects_to_walk.size > 1
+              {:error => ["Instructions given for #{objects_to_walk.sort.join(', ')} but only 1 object given"]}
+            else
+              # instructions for 1 object
+              # given 1 object
+              object_name = objects_to_walk.first
+              fetch_objects({object_name => objects}, objects_to_walk, instructions)
+            end
+          end
+        end
+      end
+    end
+
+    def fetch_objects(objects_hash, objects_to_walk, instructions)
+      results = {:error => []}
+      objects_to_walk.each do |object_name|
+        instructions[object_name].each_pair do |field, field_instructions|
+          # Command keywords are reserved and will not be walked.
+          unless @@reserved_keys.has_key?(field)
+            fetch_value(field, field_instructions, objects_hash[object_name], object_name, instructions[object_name], results)
+          end
+        end
+      end
+      results
+    end
+
+    def fetch_attributes(object, parent_name, object_hash, results)
+      object_hash.each_pair do |field, field_instructions|
+        # Command keywords are reserved and will not be walked.
+        unless @@reserved_keys.has_key?(field)
+          fetch_value(field, field_instructions, object, parent_name, object_hash, results)
+        end
+      end
+    end
+
+    def fetch_value(field, field_instructions, object, parent_name, object_hash, results)
+      # puts "      Field: #{field} field_instructions #{field_instructions.inspect} object #{object.inspect}"
+      method = fetch_method(object, field, field_instructions)
+      # puts "        Method: #{method.inspect}"
+      args = fetch_method_args(field, field_instructions)
+      if method
+        return_val = object.send(method, *args)
+        return_val = cast_value(return_val, field, field_instructions)
+        # check if we need to dive deeper into recursion
+        set_result_or_recurse(return_val, parent_name, field, field_instructions, results)
+      else
+        append_error_for_required_fields(results,
+          "#{parent_name} does not respond to any of: #{fetch_method_array(field, field_instructions).join(', ')}", field_instructions)
+      end
+    end
+
+    def set_result_or_recurse(return_val, parent_name, field, field_instructions, results)
+      if field_instructions && field_instructions.keys.any? {|k| !@@reserved_keys.has_key?(k) }
+        # yes, dive!
+        if return_val.nil?
+          append_error_for_required_fields(results, "Missing required field: #{parent_name}.#{field}", field_instructions)
+        else
+          fetch_attributes(return_val, "#{parent_name}.#{field}", field_instructions, results)
+        end
+      else
+        # no, add to results
+        results[field] = return_val
+      end
+    end
+
+    def cast_value(return_val, field, field_instructions)
+      if field_instructions && field_instructions.has_key?('cast')
+        return_val = format_value(return_val, field_instructions['cast'])
+      else
+        return_val
+      end
+    end
+
+    def fetch_method_array(field, field_instructions)
+      # Don't use compact! => returns nil if unchanged instead of returning the unchanged array
+      [(field_instructions && field_instructions['method']), field, field+'?'].compact
+    end
+
+    # Identify the method to be called.
+    def fetch_method(object, field, field_instructions)
+      fetch_method_array(field, field_instructions).detect {|method|
+        object.respond_to?(method) }
+    end
+
+    def fetch_method_args(field, field_instructions)
+      if field_instructions && field_instructions['method_args']
+        # if args specified make sure its an array
+        if field_instructions['method_args'].is_a?(Array)
+          field_instructions['method_args']
+        else
+          [ field_instructions['method_args'] ]
+        end
+      else
+        []
+      end
+    end
+
+    def append_error_for_required_fields(results, message, instructions)
+      # Only log an error for required fields.
+      if (!instructions || instructions.fetch('required', true))
+        results[:error] << message
+      end
+    end
+  end
+end

data/lib/hash_engine/fetchers.rb

@@ -0,0 +1,27 @@
+module HashEngine
+  module Fetchers
+    @@fetchers = {}
+
+    def fetchers
+      @@fetchers
+    end
+
+    def add_fetcher name, &block
+      @@fetchers[name] = block
+    end
+
+    def valid_fetcher?(fetcher)
+      fetchers.has_key?(fetcher)
+    end
+
+    def fetcher(type, field_data, customer_data)
+      if valid_fetcher?(type)
+        fetchers[type].call(field_data, customer_data)
+      end
+    end
+
+    @@fetchers['input'] = Proc.new {|field, data| data[field] }
+    @@fetchers['literal'] = Proc.new {|field, data| field }
+    @@fetchers['data'] = Proc.new {|field, data| data.values_at(*field) }
+  end
+end

data/lib/hash_engine/format.rb

@@ -0,0 +1,62 @@
+require 'date'
+
+module HashEngine
+  module Format
+
+    @@formats = {}
+
+    def formats
+      @@formats
+    end
+
+    def add_format name, &block
+      @@formats[name] = block
+    end
+
+    # leverage the fact that procs and hash have a common interface
+    def format(data, format_instructions)
+      if format_instructions.is_a?(Hash) &&
+         format_instructions.has_key?('strftime') &&
+         data.respond_to?(:strftime) then
+        data.send(:strftime, format_instructions['strftime'])
+      elsif formats.has_key?(format_instructions)
+        formats[format_instructions][data]
+      else
+        data
+      end
+    end
+
+    # \W includes '_0-9'
+    @@formats['alpha'] = Proc.new {|data| data.to_s.gsub(/[^A-Za-z]/,'') }
+
+    # \W includes '_'
+    @@formats['alphanumeric'] = Proc.new {|data| data.to_s.gsub(/[^A-Za-z0-9]/,'') }
+    @@formats['no_whitespace'] = Proc.new {|data| data.to_s.gsub(/[^A-Za-z0-9-]/,'') }
+    @@formats['numeric'] = Proc.new {|data| data.to_s.gsub(/\D/,'') }
+    @@formats['string'] = Proc.new {|data| data.to_s.strip }
+
+    # 1.8.7 behavior
+    @@formats['first'] = Proc.new {|data| /\w/u.match(data.to_s).to_s }
+
+    # 1.9.x behavior
+    if RUBY_VERSION > "1.9"
+      @@formats['first'] = Proc.new {|data| data.to_s[0] }
+    end
+
+    @@formats['float'] = Proc.new {|data| data.to_f }
+    @@formats['upcase'] = Proc.new {|data| data.to_s.upcase }
+    @@formats['downcase'] = Proc.new {|data| data.to_s.downcase }
+    @@formats['capitalize'] = Proc.new {|data| data.to_s.capitalize }
+    @@formats['reverse'] = Proc.new {|data| data.to_s.reverse }
+    @@formats['date'] = Proc.new {|data| Date.parse(data) rescue data }
+
+    int_lookup = Hash.new {|hash, key| hash[key] = key.to_i }
+    int_lookup[true] = 1
+    int_lookup[false] = 0
+    int_lookup[nil] = 0
+    @@formats['integer'] = int_lookup
+
+    @@formats['boolean'] = Hash.new {|hash, key|
+      hash[key] = ['true', 't', 'yes', 'y', '1'].include?(key.to_s.downcase) }
+  end
+end

data/lib/hash_engine/transform.rb

@@ -0,0 +1,196 @@
+require 'hash_engine/format'
+require 'hash_engine/actions'
+require 'hash_engine/add_error'
+require 'hash_engine/fetchers'
+require 'hash_engine/csv_parse'
+#require 'csv'
+
+module HashEngine
+  module Transform
+    include Format
+    include Actions
+    include AddError
+    include Fetchers
+    include CSVParse
+
+    DEFAULT_INSTRUCTIONS = {'default_value'  => '',
+                            'allow_nil'      => false,
+                            'suppress_nil'   => true,
+                            'allow_blank'    => false,
+                            'suppress_blank' => true,
+                            'long_error'     => true,
+                            'copy_source'    => false,
+                            'delimiter'      => DEFAULT_DELIMITER,
+                            'quiet'          => false }
+
+    def nil_check(instructions, value)
+      instructions['allow_nil'] == false && value.nil?
+    end
+
+    def blank_check(instructions, value)
+      instructions['allow_blank'] == false && value.is_a?(String) && value !~ /\S/
+    end
+
+    def required_check(field_hash)
+      !(field_hash['optional'] == true)
+    end
+
+    def suppress_nil(instructions, value)
+      instructions['suppress_nil'] == true && value.nil?
+    end
+
+    def suppress_blank(instructions, value)
+      instructions['suppress_blank'] == true && value.is_a?(String) && value !~ /\S/
+    end
+
+    def default_or_suppress(value, field_name, field_hash, instructions, result)
+      if (nil_check(instructions, value) || blank_check(instructions, value)) && 
+         required_check(field_hash) then
+        add_error(result[:error], "required field '#{field_name}' missing", field_name)
+        result[field_name] = instructions['default_value']
+      else
+        unless suppress_nil(instructions, value) || suppress_blank(instructions, value)
+          result[field_name] = value
+        end
+      end
+    end
+
+    def transform(data, passed_instructions)
+      instructions = DEFAULT_INSTRUCTIONS.merge(passed_instructions)
+      if instructions['fields']
+        # continue
+        result = if instructions['copy_source']
+                   data.merge(:error => [])
+                 else 
+                   {:error => []}
+                 end
+        result[:error].push(instructions['long_error'] ? :long : :short)
+        instructions['fields'].each_pair do |field_name, field_hash|
+          value = get_value(field_name, field_hash, data, result[:error])
+          default_or_suppress(value, field_name, field_hash, instructions, result)
+        end
+        # remove the :long/:short instruction
+        result[:error].shift
+      else
+        result = {:error => ["Missing instructions"]}
+      end
+      result.delete(:error) if instructions['quiet']
+      result
+    end
+
+
+  # Given String:
+  #     ok|http://www.domain.com|1234567890
+  # Given Instructions:
+  #     deliminator: '|'
+  #     hash_keys:
+  #       - status:
+  #           lookup_map:
+  #             ok: accepted
+  #             decline: reject
+  #             default: error
+  #       - payload:
+  #       - uuid:
+  # Return:
+  #     status: accepted
+  #     payload: http://www.domain.com
+  #     uuid: 1234567890
+
+    def csv_transform(data_string, passed_instructions, additional_data={})
+      instructions = DEFAULT_INSTRUCTIONS.merge(passed_instructions)
+      result = {:error => ["Missing CSV instructions"]}
+      if instructions['header']
+        result = parse_line data_string, instructions['header'], instructions['delimiter']
+        result = transform(result.merge(additional_data), instructions) if result[:error].empty?
+      end
+      result.delete(:error) if instructions['quiet']
+      result
+    end
+
+
+    def simple_instructions(field_name, field_hash, source_data, error_array)
+      instructions = []
+      field_hash.each_pair do |key, value|
+        case
+        when key == 'conditional_eval'
+          instructions.unshift(key => value)
+        when key == 'subgroup'
+          instructions.unshift(key => value)
+        when valid_fetcher?(key)
+          instructions.unshift(key => value)
+        when valid_action?(key)
+          instructions.push(key => value)
+        else
+          add_error(error_array, "Invalid operation '#{key.inspect}' in transform for field '#{field_name}'", field_name)
+          data = nil
+        end
+      end
+      process_instructions(field_name, instructions, source_data, error_array)
+    end
+
+    def concat(data, fetched)
+      if data.nil?
+        fetched
+      elsif data.is_a?(Array) && fetched.is_a?(Array)
+        data + fetched
+      elsif data.is_a?(Array) 
+        data.push fetched
+      elsif fetched.is_a?(Array)
+        fetched.unshift(data)
+      else
+        [data, fetched]
+      end
+    end
+
+    def conditional_eval(field_name, instructions, source_data, error_array)
+      left_operand = get_value("#{field_name}_conditional_eval_left_operand",
+                               instructions['left_operand'], source_data, error_array)
+      right_operand = get_value("#{field_name}_conditional_eval_right_operand",
+                                instructions['right_operand'], source_data, error_array)
+      if conditional(instructions['operator'], left_operand, right_operand)
+        get_value("#{field_name}_conditional_eval_true_instructions",
+                  instructions['true_instructions'], source_data, error_array)
+      else
+        get_value("#{field_name}_conditional_eval_false_instructions",
+                  instructions['false_instructions'], source_data, error_array)
+      end
+    end
+
+    def process_instructions(field_name, instruction_array, source_data, error_array)
+      data = nil
+      instruction_array.each do |instruction_hash|
+        (instruction, instruction_data) = instruction_hash.first
+        # puts "  Evaluating instruction: #{instruction} with instruction_data: #{instruction_data}"
+        case
+        when instruction == 'subgroup'
+          fetched = get_value(field_name, instruction_data, source_data, error_array)
+          data = concat(data, fetched)
+        when instruction == 'conditional_eval'
+          fetched = conditional_eval(field_name, instruction_data, source_data, error_array)
+          data = concat(data, fetched)
+        when valid_fetcher?(instruction)
+          fetched = fetcher(instruction, instruction_data, source_data)
+          data = concat(data, fetched)
+        when valid_action?(instruction)
+          data = action(instruction, instruction_data, data)
+        else
+          add_error(error_array, "Invalid operation '#{instruction_hash.inspect}' in transform for field '#{field_name}'", field_name)
+          data = nil
+          break
+        end
+      end
+      data
+    end
+
+    def get_value(field_name, field_data, source_data, error_array)
+      case field_data
+      when Array
+        process_instructions(field_name, field_data, source_data, error_array)
+      when Hash
+        simple_instructions(field_name, field_data, source_data, error_array)
+      else
+        fetcher('input', field_data, source_data)
+      end
+    end
+  end
+end