csv_decision 0.0.6 → 0.0.7

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Tue Dec 26 21:20:19 2017 by
+  Generated on Sat Dec 30 13:04:04 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.12 (ruby-2.3.0).
 </div>

data/lib/csv_decision.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true\
+# frozen_string_literal: true
 
 require 'active_support/core_ext/object'
 require 'csv_decision/parse'
@@ -13,26 +13,23 @@ module CSVDecision
     File.dirname __dir__
   end
 
-  autoload :Constant,   'csv_decision/constant'
   autoload :Data,       'csv_decision/data'
   autoload :Decide,     'csv_decision/decide'
   autoload :Decision,   'csv_decision/decision'
   autoload :Columns,    'csv_decision/columns'
-  autoload :Function,   'csv_decision/function'
   autoload :Header,     'csv_decision/header'
   autoload :Input,      'csv_decision/input'
   autoload :Load,       'csv_decision/load'
   autoload :Matchers,   'csv_decision/matchers'
-  autoload :Numeric,    'csv_decision/numeric'
   autoload :Options,    'csv_decision/options'
   autoload :Parse,      'csv_decision/parse'
   autoload :ScanRow,    'csv_decision/scan_row'
-  autoload :Symbol,     'csv_decision/symbol'
   autoload :Table,      'csv_decision/table'
 
   class Matchers
     autoload :Constant,      'csv_decision/matchers/constant'
     autoload :Function,      'csv_decision/matchers/function'
+    autoload :Guard,         'csv_decision/matchers/guard'
     autoload :Numeric,       'csv_decision/matchers/numeric'
     autoload :Pattern,       'csv_decision/matchers/pattern'
     autoload :Range,         'csv_decision/matchers/range'

data/lib/csv_decision/columns.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
+# Created December 2017.
+# @author Brett Vickers <brett@phillips-vickers.com>
 # See LICENSE and README.md for details.
 module CSVDecision
   # Dictionary of all this table's columns - inputs, outputs etc.
+  # @api private
   class Columns
     # Value object to hold column dictionary entries.
-    Entry = Struct.new(:name, :text_only)
+    Entry = Struct.new(:name, :eval, :type) do
+      def ins?
+        %i[in guard].member?(type) ? true : false
+      end
+    end
 
     # TODO: Value object used for any columns with defaults
     # Default = Struct.new(:name, :function, :default_if)
@@ -38,15 +44,18 @@ module CSVDecision
       end
     end
 
-    # Dictionary of all data columns
+    # Dictionary of all data columns.
+    # @return [Columns::Dictionary]
     attr_reader :dictionary
 
-    # Input columns
+    # Input columns hash keyed by column index.
+    # @return [Hash{Index=>Entry}]
     def ins
       @dictionary.ins
     end
 
-    # Output columns
+    # Output columns hash keyed by column index.
+    # @return [Hash{Index=>Entry}]
     def outs
       @dictionary.outs
     end

data/lib/csv_decision/data.rb

@@ -3,25 +3,43 @@
 require 'csv'
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
-# See LICENSE and README.md for details.
+# Created December 2017.
+# @author Brett Vickers <brett@phillips-vickers.com>
+# See LICENSE and README.md for details..
 module CSVDecision
+  # All cells starting with this character are comments, and treated as a blank cell.
   COMMENT_CHARACTER = '#'
+  private_constant :COMMENT_CHARACTER
 
-  # Methods to load data from a file, CSV string or array of arrays
+  # Methods to load data from a file, CSV string or an array of arrays.
+  # @api private
   module Data
+    # Options passed to CSV.parse and CSV.read.
     CSV_OPTIONS = { encoding: 'UTF-8', skip_blanks: true }.freeze
+    private_constant :CSV_OPTIONS
 
     # Parse the input data which may either be a file path name, CSV string or
-    # array of arrays. Strips out empty columns/rows and comment cells
+    # array of arrays. Strips out empty columns/rows and comment cells.
+    #
+    # @param data (see Parse.parse)
+    # @return [Array<Array<String>>] Data array stripped of empty rows.
     def self.to_array(data:)
       strip_rows(data: data_array(data))
     end
 
-    def self.input_file?(input)
-      input.is_a?(Pathname) || input.is_a?(File)
+    # If the input is a file name return true, otherwise false.
+    #
+    # @param data (see Parse.parse)
+    # @return [Boolean] Set to true if the input data is passed as a File or Pathname.
+    def self.input_file?(data)
+      data.is_a?(Pathname) || data.is_a?(File)
     end
 
+    # Strip the empty columns from the input data rows.
+    #
+    # @param data (see Parse.parse)
+    # @param empty_columns [Array<Index>]
+    # @return [Array<Array<String>>] Data array stripped of empty columns.
     def self.strip_columns(data:, empty_columns:)
       # Adjust column indices as we delete columns the rest shift to the left by 1
       empty_columns.map!.with_index { |col, index| col - index }

data/lib/csv_decision/decide.rb

@@ -1,11 +1,28 @@
 # frozen_string_literal: true
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
+# Created December 2017.
+# @author Brett Vickers <brett@phillips-vickers.com>
 # See LICENSE and README.md for details.
 module CSVDecision
   # Main module for searching the decision table looking for one or more matches
+  # @api private
   module Decide
+    # Match the table row against the input hash.
+    #
+    # @param row [Array] Table row.
+    # @param input [Hash{Symbol=>Object}] Input hash data structure.
+    # @param scan_row [ScanRow]
+    # @return [Boolean] Returns true if a match, false otherwise.
+    def self.matches?(row:, input:, scan_row:)
+      match = scan_row.match_constants?(row: row, scan_cols: input[:scan_cols])
+      return false unless match
+
+      return true if scan_row.procs.empty?
+
+      scan_row.match_procs?(row: row, input: input)
+    end
+
     # Main method for making decisions.
     #
     # @param table [CSVDecision::Table] Decision table.
@@ -24,24 +41,5 @@ module CSVDecision
       # table_scan(table: table, input: parsed_input, decision: decision)
       decision.scan(table: table, input: parsed_input)
     end
-
-    def self.matches?(row:, input:, scan_row:)
-      match = scan_row.match_constants?(row: row, scan_cols: input[:scan_cols])
-      return false unless match
-
-      return true if scan_row.procs.empty?
-
-      scan_row.match_procs?(row: row, input: input)
-    end
-
-    def self.eval_matcher(proc:, value:, hash:)
-      function = proc.function
-
-      # A symbol guard expression just needs to be passed the input hash
-      return function[hash] if proc.type == :expression
-
-      # All other procs can take one or two args
-      function.arity == 1 ? function[value] : function[value, hash]
-    end
   end
 end

data/lib/csv_decision/decision.rb

@@ -1,80 +1,90 @@
 # frozen_string_literal: true
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
+# Created December 2017.
+# @author Brett Vickers <brett@phillips-vickers.com>
 # See LICENSE and README.md for details.
 module CSVDecision
-  # Accumulate the matching row(s) and calculate the final result
+  # Accumulate the matching row(s) and calculate the final result.
+  # @api private
   class Decision
+    # @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
-
-      # TODO: Planned feature
-      # @outs_functions = table.outs_functions
+      @outs_functions = table.outs_functions
 
       # Partial result always includes the input hash for calculating output functions
       @partial_result = input[:hash].dup if @outs_functions
 
-      @row_picked = nil
-      return if @first_match
-
-      # Extra attributes for the accumulate option
       @rows_picked = []
-      @multi_result = nil
     end
 
-    # Is the result set empty? That is, nothing matched?
-    def empty?
-      return @row_picked.nil? if @first_match
-      @rows_picked.empty?
-    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.
+    def scan(table:, input:)
+      table.each do |row, index|
+        return result if row_scan(input: input, row: row, scan_row: table.scan_rows[index])
+      end
 
-    def exist?
-      !empty?
+      result
     end
 
-    def result
-      return {} if empty?
-      return final_result unless @outs_functions
+    private
 
-      nil
+    # Calculate the final result.
+    # @return [nil, Hash{Symbol=>Object}] Final result hash if found, otherwise nil for no result.
+    def result
+      return {} if @rows_picked.blank?
+      @first_match ? final_result : accumulated_result
     end
 
-    def scan(table:, input:)
-      scan_rows = table.scan_rows
-
-      table.each do |row, index|
-        done = row_scan(input: input, row: row, scan_row: scan_rows[index])
-
-        return self if done
-      end
-
-      self
+    def row_scan(input:, row:, scan_row:)
+      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]
     def add(row)
       return add_first_match(row) if @first_match
 
       # Accumulate output rows
       @rows_picked << row
-      @outs.each_pair do |col, column|
-        accumulate_outs(column_name: column.name, cell: row[col])
-      end
+      @outs.each_pair { |col, column| accumulate_outs(column_name: column.name, cell: row[col]) }
 
       # Not done
       false
     end
 
-    private
+    def accumulated_result
+      return final_result unless @outs_functions
+      return eval_outs(@rows_picked.first) unless @multi_result
 
-    def accumulate_outs(column_name:, cell:)
-      current = @result[column_name]
+      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
 
-      case current
+      final_result
+    end
+
+    def accumulate_outs(column_name:, cell:)
+      case (current = @result[column_name])
       when nil
         @result[column_name] = cell
 
@@ -87,10 +97,30 @@ module CSVDecision
       end
     end
 
-    def row_scan(input:, row:, scan_row:)
-      return unless Decide.matches?(row: row, input: input, scan_row: scan_row)
+    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)
+      end
+    end
 
-      add(row)
+    # 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
@@ -98,10 +128,44 @@ module CSVDecision
     end
 
     def add_first_match(row)
-      @row_picked = 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)
+
+      final_result
+    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_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
+    end
   end
 end

data/lib/csv_decision/header.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
+# 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 Header
     # TODO: implement all column types
     # COLUMN_TYPE = %r{
@@ -12,22 +14,26 @@ module CSVDecision
     #   \s*:\s*(?<name>\S?.*)\z
     # }xi
 
-    # Column types recognise din the header row.
+    # Column types recognised in the header row.
     COLUMN_TYPE = %r{
-      \A(?<type>in|out|in/text|out/text)
+      \A(?<type>in|out|in/text|out/text|guard)
       \s*:\s*(?<name>\S?.*)\z
     }xi
 
-    # These column types do not need a name
-    # TODO: implement anonymous column types
+    # 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.
+    # 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
 
     # Check if the given row contains a recognisable header cell.
     #
@@ -61,8 +67,26 @@ module CSVDecision
         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_header_column(cell:)
       match = COLUMN_TYPE.match(cell)
@@ -73,8 +97,7 @@ module CSVDecision
 
       [column_type, column_name]
     rescue CellValidationError => exp
-      raise CellValidationError,
-            "header column '#{cell}' is not valid as the #{exp.message}"
+      raise CellValidationError, "header column '#{cell}' is not valid as the #{exp.message}"
     end
     private_class_method :validate_header_column
 
@@ -90,8 +113,7 @@ module CSVDecision
     def self.column_name(type:, name:)
       return format_column_name(name) if name.present?
 
-      # TODO: implement anonymous column types
-      # return if COLUMN_TYPE_ANONYMOUS.member?(type)
+      return if COLUMN_TYPE_ANONYMOUS.member?(type)
 
       raise CellValidationError, 'column name is missing'
     end
@@ -107,22 +129,21 @@ module CSVDecision
     private_class_method :format_column_name
 
     # Returns the normalized column type, along with an indication if
-    # the column is text only
-    def self.column_type(type)
+    # the column requires evaluation
+    def self.column_type(column_name, type)
       case type
       when :'in/text'
-        [:in, true]
+        Columns::Entry.new(column_name, false, :in)
 
-      # TODO: planned feature
-      # when :guard
-      #   [:in, false]
+      when :guard
+        Columns::Entry.new(column_name, true, :guard)
 
       when :'out/text'
-        [:out, true]
+        Columns::Entry.new(column_name, false, :out)
 
-      # Column may turn out to be text-only, or not
+      # Column may turn out to be constants only, or not
       else
-        [type, nil]
+        Columns::Entry.new(column_name, nil, type.to_sym)
       end
     end
     private_class_method :column_type
@@ -130,11 +151,11 @@ module CSVDecision
     def self.parse_cell(cell:, index:, dictionary:)
       column_type, column_name = validate_header_column(cell: cell)
 
-      type, text_only = column_type(column_type)
+      entry = column_type(column_name, column_type)
 
       dictionary_entry(dictionary: dictionary,
-                       type: type,
-                       entry: Columns::Entry.new(column_name, text_only),
+                       type: entry.type,
+                       entry: entry,
                        index: index)
     end
     private_class_method :parse_cell
@@ -150,7 +171,7 @@ module CSVDecision
       #   # Treat set: as an in: column
       #   dictionary.ins[index] = entry
 
-      when :in
+      when :in, :guard
         dictionary.ins[index] = entry
 
       when :out