csv_decision 0.0.8 → 0.0.9

data/lib/csv_decision/decision.rb

@@ -11,26 +11,25 @@ module CSVDecision
     # @param table [CSVDecision::Table] Decision table being processed.
     # @param input [Hash{Symbol=>Object}] Input hash data structure.
     def initialize(table:, input:)
-      @result = {}
-
-      # Relevant table attributes
-      @first_match = table.options[:first_match]
-      @outs = table.columns.outs
-      @outs_functions = table.outs_functions
-
-      # Partial result always includes the input hash for calculating output functions
-      @partial_result = input[:hash].dup if @outs_functions
+      # The result object is a hash of values, and each value will be an array if this is
+      # a multi-row result for the +first_match: false+ option.
+      @result = Result.new(table: table, input: input)
 
+      # All rows picked by the matching process. An array if +first_match: false+, otherwise
+      # a single row.
       @rows_picked = []
+
+      # Relevant table attributes
+      table_attributes(table)
     end
 
     # Scan the decision table up against the input hash.
     #
-    # @param table [CSVDecision::Table] Decision table being processed.
-    # @param input (see #initialize)
-    # @return [self] Decision object built so far.
+    # @param (see #initialize)
+    # @return [{Symbol=>Object}] Decision result.
     def scan(table:, input:)
       table.each do |row, index|
+        # +row_scan+ returns false if more rows need to be scanned, truthy otherwise.
         return result if row_scan(input: input, row: row, scan_row: table.scan_rows[index])
       end
 
@@ -39,133 +38,83 @@ module CSVDecision
 
     private
 
-    # Calculate the final result.
-    # @return [nil, Hash{Symbol=>Object}] Final result hash if found, otherwise nil for no result.
+    # Record the relevant table attributes.
+    def table_attributes(table)
+      @first_match = table.options[:first_match]
+      @outs = table.columns.outs
+      @outs_functions = table.outs_functions
+    end
+
+    # Derive the final result.
+    #
+    # @return [nil, Hash{Symbol=>Object}] Final result hash if matches found,
+    #   otherwise the empty hash for no result.
     def result
       return {} if @rows_picked.blank?
-      @first_match ? final_result : accumulated_result
+      @first_match ? @result.attributes : accumulated_result
     end
 
+    # Scan the row for matches against the input conditions.
     def row_scan(input:, row:, scan_row:)
+      # +add+ returns false if more rows need to be scanned, truthy otherwise.
       add(row) if Decide.matches?(row: row, input: input, scan_row: scan_row)
     end
 
     # Add a matched row to the decision object being built.
     #
-    # @param row [Array]
+    # @param row [Array] Data row.
+    # @return [false, Hash]
     def add(row)
       return add_first_match(row) if @first_match
 
       # Accumulate output rows
       @rows_picked << row
-      @outs.each_pair { |col, column| accumulate_outs(column_name: column.name, cell: row[col]) }
+      @result.accumulate_outs(row)
 
       # Not done
       false
     end
 
     def accumulated_result
-      return final_result unless @outs_functions
-      return eval_outs(@rows_picked.first) unless @multi_result
+      return @result.final unless @outs_functions
+      return @result.eval_outs(@rows_picked.first) unless @result.multi_result
 
       multi_row_result
     end
 
     def multi_row_result
       # Scan each output column that contains functions
-      @outs.each_pair do |col, column|
-        # Does this column have any functions defined?
-        next unless column.eval
-
-        eval_column_procs(col, column)
-      end
-
-      final_result
-    end
-
-    def accumulate_outs(column_name:, cell:)
-      case (current = @result[column_name])
-      when nil
-        @result[column_name] = cell
-
-      when Array
-        @result[column_name] << cell
+      @outs.each_pair { |col, column| eval_column_procs(col: col, column: column) if column.eval }
 
-      else
-        @result[column_name] = [current, cell]
-        @multi_result ||= true
-      end
+      @result.final
     end
 
-    def eval_column_procs(col, column)
+    def eval_column_procs(col:, column:)
       @rows_picked.each_with_index do |row, index|
         proc = row[col]
         next unless proc.is_a?(Matchers::Proc)
 
         # Evaluate the proc and update the result
-        eval_cell_proc(proc: proc, column_name: column.name, index: index)
+        @result.eval_cell_proc(proc: proc, column_name: column.name, index: index)
       end
     end
 
-    # Update the partial result calculated so far and call the function
-    def eval_cell_proc(proc:, column_name:, index:)
-      value = proc.function[partial_result(index)]
-      @multi_result ? @result[column_name][index] = value : @result[column_name] = value
-    end
-
-    def partial_result(index)
-      @result.each_pair do |column_name, value|
-        # Delete this column from the partial result in case there is data from a prior result row
-        next @partial_result.delete(column_name) if value[index].is_a?(Matchers::Proc)
-        @partial_result[column_name] = value[index]
-      end
-
-      @partial_result
-    end
-
-    def final_result
-      @result
-    end
-
     def add_first_match(row)
-      @rows_picked = row
-
-      return eval_outs(row) if @outs_functions
-
-      # Common case is just copying output column values to the final result
-      @outs.each_pair { |col, column| @result[column.name] = row[col] }
-    end
-
-    def eval_outs(row)
-      # Set the constants first, in case the functions refer to them
-      eval_outs_constants(row)
-
-      # Then evaluate the functions, left to right
-      eval_outs_procs(row)
+      # This decision row may contain procs, which if present will need to be evaluated.
+      # If this row contains if: columns then this row may be filtered out, in which case
+      # this method call will return false.
+      return eval_single_row(row) if @outs_functions
 
-      final_result
+      # Common case is just copying output column values to the final result.
+      @rows_picked = row
+      @result.add_outs(row)
     end
 
-    def eval_outs_constants(row)
-      @outs.each_pair do |col, column|
-        value = row[col]
-        next if value.is_a?(Matchers::Proc)
-
-        @partial_result[column.name] = value
-        @result[column.name] = value
-      end
-    end
+    def eval_single_row(row)
+      return false unless (result = @result.eval_outs(row))
 
-    def eval_outs_procs(row)
-      @outs.each_pair do |col, column|
-        proc = row[col]
-        next unless proc.is_a?(Matchers::Proc)
-
-        value = proc.function[@partial_result]
-
-        @partial_result[column.name] = value
-        @result[column.name] = value
-      end
+      @rows_picked = row
+      result
     end
   end
 end

data/lib/csv_decision/dictionary.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017.
+# @author Brett Vickers <brett@phillips-vickers.com>
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Parse the CSV file's header row. These methods are only required at table load time.
+  # @api private
+  module Dictionary
+    # Table used to build a column dictionary entry.
+    ENTRY = {
+      in:         { type: :in,    eval: nil },
+      'in/text':  { type: :in,    eval: false },
+      out:        { type: :out,   eval: nil },
+      'out/text': { type: :out,   eval: false },
+      guard:      { type: :guard, eval: true },
+      if:         { type: :if,    eval: true }
+    }.freeze
+    private_constant :ENTRY
+
+    # Value object to hold column dictionary entries.
+    Entry = Struct.new(:name, :eval, :type) do
+      def ins?
+        %i[in guard].member?(type) ? true : false
+      end
+    end
+
+    # TODO: implement all anonymous column types
+    # COLUMN_TYPE_ANONYMOUS = Set.new(%i[path if guard]).freeze
+    # These column types do not need a name
+    COLUMN_TYPE_ANONYMOUS = Set.new(%i[guard if]).freeze
+    private_constant :COLUMN_TYPE_ANONYMOUS
+
+    # Classify and build a dictionary of all input and output columns by
+    # parsing the header row.
+    #
+    # @param header [Array<String>] The header row after removing any empty columns.
+    # @return [Hash<Hash>] Column dictionary is a hash of hashes.
+    def self.build(header:, dictionary:)
+      header.each_with_index do |cell, index|
+        dictionary = parse_cell(cell: cell, index: index, dictionary: dictionary)
+      end
+
+      validate(dictionary)
+    end
+
+    def self.validate(dictionary)
+      dictionary.outs.each_pair do |col, column|
+        validate_out(dictionary: dictionary, column_name: column.name, col: col)
+      end
+
+      dictionary
+    end
+    private_class_method :validate
+
+    def self.validate_out(dictionary:, column_name:, col:)
+      if dictionary.ins.any? { |_, column| column_name == column.name }
+        raise CellValidationError, "output column name '#{column_name}' is also an input column"
+      end
+
+      return unless dictionary.outs.any? { |key, column| column_name == column.name && col != key }
+      raise CellValidationError, "output column name '#{column_name}' is duplicated"
+    end
+    private_class_method :validate_out
+
+    def self.validate_column(cell:, index:)
+      match = Header::COLUMN_TYPE.match(cell)
+      raise CellValidationError, 'column name is not well formed' unless match
+
+      column_type = match['type']&.downcase&.to_sym
+      column_name = column_name(type: column_type, name: match['name'], index: index)
+
+      [column_type, column_name]
+    rescue CellValidationError => exp
+      raise CellValidationError, "header column '#{cell}' is not valid as the #{exp.message}"
+    end
+    private_class_method :validate_column
+
+    def self.column_name(type:, name:, index:)
+      # if: columns are named after their index, which is an integer and so cannot
+      # clash with other column name types, which are symbols.
+      return index if type == :if
+
+      return format_column_name(name) if name.present?
+
+      return if COLUMN_TYPE_ANONYMOUS.member?(type)
+      raise CellValidationError, 'column name is missing'
+    end
+    private_class_method :column_name
+
+    def self.format_column_name(name)
+      column_name = name.strip.tr("\s", '_')
+
+      return column_name.to_sym if Header::COLUMN_NAME_RE.match(column_name)
+      raise CellValidationError, "column name '#{name}' contains invalid characters"
+    end
+    private_class_method :format_column_name
+
+    # Returns the normalized column type, along with an indication if
+    # the column requires evaluation
+    def self.column_type(column_name, entry)
+      Entry.new(column_name, entry[:eval], entry[:type])
+    end
+    private_class_method :column_type
+
+    def self.parse_cell(cell:, index:, dictionary:)
+      column_type, column_name = validate_column(cell: cell, index: index)
+
+      entry = column_type(column_name, ENTRY[column_type])
+
+      dictionary_entry(dictionary: dictionary, entry: entry, index: index)
+    end
+    private_class_method :parse_cell
+
+    def self.dictionary_entry(dictionary:, entry:, index:)
+      case entry.type
+      # Header column that has a function for setting the value (planned feature)
+      # when :set, :'set/nil?', :'set/blank?'
+      #   # Default function will set the input value unconditionally or conditionally
+      #   dictionary.defaults[index] =
+      #     Columns::Default.new(entry.name, nil, default_if(type))
+      #
+      #   # Treat set: as an in: column
+      #   dictionary.ins[index] = entry
+
+      when :in, :guard
+        dictionary.ins[index] = entry
+
+      when :out
+        dictionary.outs[index] = entry
+
+      when :if
+        dictionary.outs[index] = entry
+        dictionary.ifs[index] = entry
+      end
+
+      dictionary
+    end
+    private_class_method :dictionary_entry
+
+    # def self.default_if(type)
+    #   return nil if type == :set
+    #   return :nil? if type == :'set/nil'
+    #   :blank?
+    # end
+    # private_class_method :default_if
+  end
+end

data/lib/csv_decision/header.rb

@@ -20,37 +20,20 @@ module CSVDecision
       \s*:\s*(?<name>\S?.*)\z
     }xi
 
-    COLUMN_ENTRY = {
-      in:         { type: :in,    eval: nil },
-      'in/text':  { type: :in,    eval: false },
-      out:        { type: :out,   eval: nil },
-      'out/text': { type: :out,   eval: false },
-      guard:      { type: :guard, eval: true },
-      if:         { type: :if,    eval: true }
-    }.freeze
-    private_constant :COLUMN_ENTRY
-
-    # TODO: implement all anonymous column types
-    # COLUMN_TYPE_ANONYMOUS = Set.new(%i[path if guard]).freeze
-    # These column types do not need a name
-    COLUMN_TYPE_ANONYMOUS = Set.new(%i[guard]).freeze
-    private_constant :COLUMN_TYPE_ANONYMOUS
-
     # Regular expression string for a column name.
     # More lenient than a Ruby method name - note any spaces will have been replaced with
     # underscores.
     COLUMN_NAME = "\\w[\\w:/!?]*"
 
-    # Column name regular expression.
-    COLUMN_NAME_RE = Matchers.regexp(COLUMN_NAME)
-    private_constant :COLUMN_NAME_RE
+    # Regular expression for matching a column name.
+    COLUMN_NAME_RE = Matchers.regexp(Header::COLUMN_NAME)
 
     # Check if the given row contains a recognisable header cell.
     #
     # @param row [Array<String>] Header row.
     # @return [Boolean] Return true if the row looks like a header.
     def self.row?(row)
-      row.find { |cell| cell.match(COLUMN_TYPE) }
+      row.any? { |cell| cell.match(COLUMN_TYPE) }
     end
 
     # Strip empty columns from all data rows.
@@ -66,52 +49,9 @@ module CSVDecision
       rows.shift
     end
 
-    # Classify and build a dictionary of all input and output columns.
-    #
-    # @param row [Array<String>] The header row after removing any empty columns.
-    # @return [Hash<Hash>] Column dictionary is a hash of hashes.
-    def self.dictionary(row:)
-      dictionary = Columns::Dictionary.new
-
-      row.each_with_index do |cell, index|
-        dictionary = parse_cell(cell: cell, index: index, dictionary: dictionary)
-      end
-
-      validate(dictionary: dictionary)
-    end
-
-    def self.validate(dictionary:)
-      dictionary.outs.each_value do |column|
-        next unless input_column?(dictionary: dictionary, column_name: column.name)
-
-        raise CellValidationError, "output column name '#{column.name}' is also an input column"
-      end
-
-      dictionary
-    end
-    private_class_method :validate
-
-    def self.input_column?(dictionary:, column_name:)
-      dictionary.ins.each_value { |column| return true if column_name == column.name }
-
-      false
-    end
-    private_class_method :input_column?
-
-    def self.validate_column(cell:)
-      match = COLUMN_TYPE.match(cell)
-      raise CellValidationError, 'column name is not well formed' unless match
-
-      column_type = match['type']&.downcase&.to_sym
-      column_name = column_name(type: column_type, name: match['name'])
-
-      [column_type, column_name]
-    rescue CellValidationError => exp
-      raise CellValidationError, "header column '#{cell}' is not valid as the #{exp.message}"
-    end
-    private_class_method :validate_column
-
-    # Array of all empty column indices.
+    # Build an array of all empty column indices.
+    # @param row [Array]
+    # @return [false, Array<Integer>]
     def self.empty_columns?(row:)
       result = []
       row&.each_with_index { |cell, index| result << index if cell == '' }
@@ -119,72 +59,5 @@ module CSVDecision
       result.empty? ? false : result
     end
     private_class_method :empty_columns?
-
-    def self.column_name(type:, name:)
-      return format_column_name(name) if name.present?
-
-      return if COLUMN_TYPE_ANONYMOUS.member?(type)
-
-      raise CellValidationError, 'column name is missing'
-    end
-    private_class_method :column_name
-
-    def self.format_column_name(name)
-      column_name = name.strip.tr("\s", '_')
-
-      return column_name.to_sym if COLUMN_NAME_RE.match(column_name)
-
-      raise CellValidationError, "column name '#{name}' contains invalid characters"
-    end
-    private_class_method :format_column_name
-
-    # Returns the normalized column type, along with an indication if
-    # the column requires evaluation
-    def self.column_type(column_name, type)
-      entry = COLUMN_ENTRY[type]
-      Columns::Entry.new(column_name, entry[:eval], entry[:type])
-    end
-    private_class_method :column_type
-
-    def self.parse_cell(cell:, index:, dictionary:)
-      column_type, column_name = validate_column(cell: cell)
-
-      entry = column_type(column_name, column_type)
-
-      dictionary_entry(dictionary: dictionary,
-                       type: entry.type,
-                       entry: entry,
-                       index: index)
-    end
-    private_class_method :parse_cell
-
-    def self.dictionary_entry(dictionary:, type:, entry:, index:)
-      case type
-      # Header column that has a function for setting the value (planned feature)
-      # when :set, :'set/nil', :'set/blank'
-      #   # Default function will set the input value unconditionally or conditionally
-      #   dictionary.defaults[index] =
-      #     Columns::Default.new(entry.name, nil, default_if(type))
-      #
-      #   # Treat set: as an in: column
-      #   dictionary.ins[index] = entry
-
-      when :in, :guard
-        dictionary.ins[index] = entry
-
-      when :out
-        dictionary.outs[index] = entry
-      end
-
-      dictionary
-    end
-    private_class_method :dictionary_entry
-
-    # def self.default_if(type)
-    #   return nil if type == :set
-    #   return :nil? if type == :'set/nil'
-    #   :blank?
-    # end
-    # private_class_method :default_if
   end
 end

data/lib/csv_decision/matchers.rb

@@ -124,8 +124,7 @@ module CSVDecision
       Matchers.parse(columns: columns, matchers: @outs, row: row)
     end
 
-    # @abstract Subclass and override {#matches?} to implement
-    #   a custom Matcher class.
+    # Subclass and override {#matches?} to implement a custom Matcher class.
     class Matcher
       def initialize(_options = nil); end
 

data/lib/csv_decision/parse.rb

@@ -14,7 +14,7 @@ module CSVDecision
   # Error validating a cell when parsing input table data.
   class CellValidationError < Error; end
 
-  # Table parsing error message enhanced to include the file being processed
+  # Table parsing error message enhanced to include the file being processed.
   class FileError < Error; end
 
   # Builds a decision table from the input data - which may either be a file, CSV string
@@ -62,6 +62,7 @@ module CSVDecision
 
       parse_table(table: table, input: data, options: options)
 
+      # The table object is now immutable.
       table.columns.deep_freeze
       table.freeze
     rescue CSVDecision::Error => exp
@@ -93,25 +94,35 @@ module CSVDecision
 
     def self.parse_data(table:, matchers:)
       table.rows.each_with_index do |row, index|
-        row, table.scan_rows[index] = matchers.parse_ins(columns: table.columns.ins, row: row)
-        row, table.outs_rows[index] = matchers.parse_outs(columns: table.columns.outs, row: row)
+        # Mutate the row if we find anything other than a simple string constant in its
+        # data cells.
+        row = parse_row(table: table, matchers: matchers, row: row, index: index)
 
-        # Does the table have any output functions?
+        # Does the row have any output functions?
         outs_functions(table: table, index: index)
 
+        # No more mutations required for this row.
         row.freeze
       end
     end
     private_class_method :parse_data
 
+    def self.parse_row(table:, matchers:, row:, index:)
+      row, table.scan_rows[index] = matchers.parse_ins(columns: table.columns.ins, row: row)
+      row, table.outs_rows[index] = matchers.parse_outs(columns: table.columns.outs, row: row)
+
+      row
+    end
+    private_class_method :parse_row
+
     def self.outs_functions(table:, index:)
       return if table.outs_rows[index].procs.empty?
 
       # Set this flag as the table has output functions
-      table.outs_functions ||= true
+      table.outs_functions = true
 
-      outs = table.columns.outs
-      table.outs_rows[index].procs.each { |col| outs[col].eval = true }
+      # Update the output columns that contain functions needing evaluation.
+      table.outs_rows[index].procs.each { |col| table.columns.outs[col].eval = true }
     end
     private_class_method :outs_functions
   end