csv_decision 0.4.1 → 0.5.0

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Jan 28 14:41:48 2018 by
+  Generated on Sun Feb 11 10:26:07 2018 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.12 (ruby-2.4.0).
 </div>

data/lib/csv_decision.rb

@@ -25,11 +25,14 @@ module CSVDecision
   autoload :Matchers,   'csv_decision/matchers'
   autoload :Options,    'csv_decision/options'
   autoload :Parse,      'csv_decision/parse'
+  autoload :Paths,      'csv_decision/paths'
   autoload :Result,     'csv_decision/result'
+  autoload :Scan,       'csv_decision/scan'
   autoload :ScanRow,    'csv_decision/scan_row'
   autoload :Table,      'csv_decision/table'
   autoload :Validate,   'csv_decision/validate'
 
+  # Cell matchers
   class Matchers
     autoload :Constant,      'csv_decision/matchers/constant'
     autoload :Function,      'csv_decision/matchers/function'

data/lib/csv_decision/columns.rb

@@ -115,12 +115,17 @@ module CSVDecision
       #   This is actually just a subset of :outs.
       attr_accessor :ifs
 
+      # @return [Hash{Integer=>Symbol}] All path columns.
+      #   This is actually just a subset of :outs.
+      attr_accessor :paths
+
       def initialize
         @columns = {}
         @defaults = {}
         @ifs = {}
         @ins = {}
         @outs = {}
+        @paths = {}
       end
     end
 
@@ -158,6 +163,12 @@ module CSVDecision
       @dictionary.ifs
     end
 
+    # path: columns hash keyed by column index.
+    # @return [Hash{Index=>Entry}]
+    def paths
+      @dictionary.paths
+    end
+
     # @return [Array<Symbol>] All input column symbols.
     def input_keys
       @dictionary.columns.select { |_k, v| v == :in }.keys

data/lib/csv_decision/decision.rb

@@ -8,7 +8,7 @@ module CSVDecision
   # Accumulate the matching row(s) and calculate the final result.
   # @api private
   class Decision
-    # Main method for making decisions.
+    # Main method for making decisions without a path.
     #
     # @param table [CSVDecision::Table] Decision table.
     # @param input [Hash] Input hash (keys may or may not be symbolized)
@@ -17,66 +17,101 @@ module CSVDecision
     # @return [Hash{Symbol=>Object}] Decision result.
     def self.make(table:, input:, symbolize_keys:)
       # Parse and transform the hash supplied as input
-      input = Input.parse(table: table, input: input, symbolize_keys: symbolize_keys)
+      data = Input.parse(table: table, input: input, symbolize_keys: symbolize_keys)
 
       # The decision object collects the results of the search and
-      # calculates the final result
-      decision = Decision.new(table: table, input: input)
-
-      # Use the table's index if present
-      table.index ? decision.index_scan : decision.table_scan
+      # calculates the final result.
+      Decision.new(table: table).scan(data)
     end
 
+    # @return [Boolean] True if a first match decision table.
+    attr_reader :first_match
+
+    # @return [CSVDecision::Table] Decision table object.
+    attr_reader :table
+
     # @param table [CSVDecision::Table] Decision table being processed.
-    # @param input [Hash{Symbol=>Object}] Input hash data structure.
-    def initialize(table:, input:)
+    def initialize(table:)
       # 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[:hash])
+      @result = Result.new(table: table)
+      @first_match = table.options[:first_match]
+      @table = table
+    end
+
+    # Initialize the input data used to make the decision.
+    #
+    # @param data [Hash{Symbol=>Object}] Input hash data structure.
+    # @return [void]
+    def input(data)
+      @result.input(data[:hash])
 
       # All rows picked by the matching process. An array if +first_match: false+,
       # otherwise a single row.
       @rows_picked = []
 
-      @first_match = table.options[:first_match]
+      @input = data
+    end
 
-      @table = table
-      @input = input
+    # Scan the decision table and produce an output decision.
+    #
+    # @param data [Hash{Symbol=>Object}] Input hash data structure.
+    # @return (see .make)
+    def scan(data)
+      input(data)
+      # Use the table's index if present
+      @table.index ? index_scan : table_scan
     end
 
-    # Scan the decision table up against the input hash.
+    #  Scan the index for a first match result.
     #
-    # @return [Hash{Symbol=>Object}] Decision result.
-    def table_scan
-      hash = @input[:hash]
-      scan_cols = @input[:scan_cols]
+    # @param scan_cols [Hash{Integer=>Object}]
+    # @param hash [Hash{Symbol=>Object}]
+    # @param index_rows [Array<Integer>]
+    # @return [Hash{Symbol=>Object}]
+    def index_scan_first_match(scan_cols:, hash:, index_rows:)
+      index_rows.each do |start_row, end_row|
+        @table.each(start_row, end_row || start_row) do |row, index|
+          next unless @table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
 
-      if @first_match
-        scan_first_match(hash: hash, scan_cols: scan_cols)
-      else
-        scan_accumulate(hash: hash, scan_cols: scan_cols)
+          return @result.attributes if first_match_found(row)
+        end
       end
+
+      {}
     end
 
-    # Use an index to scan the decision table up against the input hash.
+    #  Scan the index for an accumulated result.
     #
-    # @return [Hash{Symbol=>Object}] Decision result.
-    def index_scan
-      # If the index lookup fails, there's no match.
-      return {} unless (index_rows = Array(@table.index.hash[@input[:key]]))
+    # @param scan_cols [Hash{Integer=>Object}]
+    # @param hash [Hash{Symbol=>Object}]
+    # @param index_rows [Array<Integer>]
+    # @return [Hash{Symbol=>Object}]
+    def index_scan_accumulate(scan_cols:, hash:, index_rows:)
+      index_rows.each do |start_row, end_row|
+        @table.each(start_row, end_row || start_row) do |row, index|
+          next unless @table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
 
-      hash = @input[:hash]
-      scan_cols = @input[:scan_cols]
+          # Accumulate output rows.
+          @rows_picked << row
+          @result.accumulate_outs(row)
+        end
+      end
+
+      @rows_picked.empty? ? {} : accumulated_result
+    end
 
+    private
+
+    # Use an index to scan the decision table up against the input hash.
+    def index_scan_rows(rows:)
       if @first_match
-        index_scan_first_match(scan_cols: scan_cols, hash: hash, index_rows: index_rows)
+        index_scan_first_match(scan_cols: @input[:scan_cols], hash: @input[:hash], index_rows: rows)
       else
-        index_scan_accumulate(scan_cols: scan_cols, hash: hash, index_rows: index_rows)
+        index_scan_accumulate(scan_cols: @input[:scan_cols], hash: @input[:hash], index_rows: rows)
       end
     end
 
-    private
-
     def scan_first_match(hash:, scan_cols:)
       @table.each do |row, index|
         next unless @table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
@@ -99,30 +134,21 @@ module CSVDecision
       @rows_picked.empty? ? {} : accumulated_result
     end
 
-    def index_scan_first_match(scan_cols:, hash:, index_rows:)
-      index_rows.each do |start_row, end_row|
-        @table.each(start_row, end_row || start_row) do |row, index|
-          next unless @table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
-
-          return @result.attributes if first_match_found(row)
-        end
+    # Scan the decision table up against the input hash.
+    def table_scan
+      if @first_match
+        scan_first_match(hash: @input[:hash], scan_cols:  @input[:scan_cols])
+      else
+        scan_accumulate(hash: @input[:hash], scan_cols:  @input[:scan_cols])
       end
-
-      {}
     end
 
-    def index_scan_accumulate(scan_cols:, hash:, index_rows:)
-      index_rows.each do |start_row, end_row|
-        @table.each(start_row, end_row || start_row) do |row, index|
-          next unless @table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
-
-          # Accumulate output rows.
-          @rows_picked << row
-          @result.accumulate_outs(row)
-        end
-      end
+    # Use an index to scan the decision table up against the input hash.
+    def index_scan
+      # If the index lookup fails, there's no match.
+      return {} unless (index_rows = Array(@table.index.hash[@input[:key]]))
 
-      @rows_picked.empty? ? {} : accumulated_result
+      index_scan_rows(rows: index_rows)
     end
 
     def accumulated_result
@@ -141,11 +167,11 @@ module CSVDecision
 
     def eval_procs(col:, column:)
       @rows_picked.each_with_index do |row, index|
-        proc = row[col]
-        next unless proc.is_a?(Matchers::Proc)
+        cell = row[col]
+        next unless cell.is_a?(Matchers::Proc)
 
         # Evaluate the proc and update the result
-        @result.eval_cell_proc(proc: proc, column_name: column.name, index: index)
+        @result.eval_cell_proc(proc: cell, column_name: column.name, index: index)
       end
     end
 

data/lib/csv_decision/dictionary.rb

@@ -33,7 +33,8 @@ module CSVDecision
         out:          { type: :out,   eval: nil },
         'out/text':   { type: :out,   eval: false },
         guard:        { type: :guard, eval: true },
-        if:           { type: :if,    eval: true }
+        if:           { type: :if,    eval: true },
+        path:         { type: :path,  eval: false }
       }.freeze
       private_constant :ENTRY
 
@@ -142,6 +143,9 @@ module CSVDecision
 
       when :out, :if
         output_entry(dictionary: dictionary, entry: entry, index: index)
+
+      when :path
+        dictionary.paths[index] = entry
       end
 
       dictionary

data/lib/csv_decision/header.rb

@@ -10,7 +10,7 @@ module CSVDecision
   module Header
     # Column types recognised in the header row.
     COLUMN_TYPE = %r{
-      \A(?<type>in/text|in|out/text|out|guard|if|set/nil\?|set/blank\?|set)
+      \A(?<type>in/text|in|out/text|out|guard|if|set/nil\?|set/blank\?|set|path)
       \s*:\s*(?<name>\S?.*)\z
     }xi
 

data/lib/csv_decision/input.rb

@@ -13,12 +13,25 @@ module CSVDecision
     def self.parse(table:, input:, symbolize_keys:)
       validate(input)
 
-      parsed_input = parse_input(table: table, input: symbolize_keys ? input.symbolize_keys : input)
+      parsed_input =
+        parse_data(table: table, input: symbolize_keys ? input.symbolize_keys : input)
 
       parsed_input[:key] = parse_key(table: table, hash: parsed_input[:hash]) if table.index
       parsed_input
     end
 
+    # @param table [CSVDecision::Table] Decision table.
+    # @param input [Hash] Input hash (keys may or may not be symbolized)
+    # @return [Hash{Symbol=>Object}]
+    def self.parse_data(table:, input:)
+      defaulted_columns = table.columns.defaults
+
+      # Code path optimized for no defaults
+      return parse_cells(table: table, input: input) if defaulted_columns.empty?
+
+      parse_defaulted(table: table, input: input, defaulted_columns: defaulted_columns)
+    end
+
     def self.parse_key(table:, hash:)
       return scan_key(table: table, hash: hash) if table.index.columns.count == 1
 
@@ -49,16 +62,6 @@ module CSVDecision
     end
     private_class_method :validate
 
-    def self.parse_input(table:, input:)
-      defaulted_columns = table.columns.defaults
-
-      # Code path optimized for no defaults
-      return parse_cells(table: table, input: input) if defaulted_columns.empty?
-
-      parse_defaulted(table: table, input: input, defaulted_columns: defaulted_columns)
-    end
-    private_class_method :parse_input
-
     def self.parse_cells(table:, input:)
       scan_cols = {}
       table.columns.ins.each_pair do |col, column|

data/lib/csv_decision/parse.rb

@@ -28,7 +28,8 @@ module CSVDecision
   #
   # @param data [Pathname, File, Array<Array<String>>, String] input data given as
   #   a CSV file, array of arrays or CSV string.
-  # @param options [Hash{Symbol=>Object}] Options hash controlling how the table is parsed and interpreted.
+  # @param options [Hash{Symbol=>Object}] Options hash controlling how the table is parsed and
+  #   interpreted.
   #
   # @option options [Boolean] :first_match Stop scanning after finding the first row match.
   # @option options [Boolean] :regexp_implicit Make regular expressions implicit rather than
@@ -88,8 +89,11 @@ module CSVDecision
       # Parse table header and data rows with special cell matchers.
       parse_with_matchers(table: table, matchers: CSVDecision::Matchers.new(options))
 
-      # Build the index if one is indicated
+      # Build the data index if one is indicated
       Index.build(table: table)
+
+      # Build a paths index if one is indicated
+      Paths.scan(table: table)
     end
     private_class_method :parse_table
 

data/lib/csv_decision/paths.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017.
+# @author Brett Vickers.
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Build an index for a decision table with one or more input columns
+  # designated as keys
+  # @api private
+  class Paths
+    # Build the index of paths
+    #
+    # @param table [CSVDecision::Table] Decision table being indexed.
+    # @return [CSVDecision::Paths] The built index of paths.
+    def self.scan(table:)
+      # Do we even have paths?
+      columns = table.columns.paths.keys
+      return [] if columns.empty?
+
+      table.paths = Paths.new(table: table, columns: columns).paths
+    end
+
+    # @param current_value [Integer, Array] Current path value.
+    # @param index [Integer] Array row index to be included in the path entry.
+    # @return [Integer, Array] New path key value.
+    def self.value(current_value, index)
+      return [current_value, index] if current_value.is_a?(Integer)
+
+      current_value[-1] = index
+      current_value
+    end
+
+    # @param value [String] Cell value for the path: column.
+    # @return [nil, Symbol] Non-empty string converted to a symbol.
+    def self.symbol(value)
+      value.blank? ? nil : value.to_sym
+    end
+
+    # @return [Hash] The index hash mapping in input values to one or more data array row indexes.
+    attr_reader :paths
+
+    # @param table [CSVDecision::Table] Decision table.
+    # @param columns [Array<Index>] Array of column indexes to be indexed.
+    def initialize(table:, columns:)
+      @paths = []
+      @columns = columns
+
+      build(table)
+
+      freeze
+    end
+
+    private
+
+    def build(table)
+      last_path = nil
+      key = -1
+      rows = nil
+      table.each do |row, index|
+        path = build_path(row: row)
+        if path == last_path
+          rows = Paths.value(rows, index)
+        else
+          rows = index
+          key += 1
+          last_path = path
+        end
+
+        @paths[key] = [path, rows]
+      end
+    end
+
+    def build_path(row:)
+      @columns.map { |col| Paths.symbol(row[col]) }.compact
+    end
+  end
+end

data/lib/csv_decision/result.rb

@@ -22,20 +22,26 @@ module CSVDecision
     attr_reader :multi_result
 
     # (see Decision.initialize)
-    def initialize(table:, input:)
-      # Attributes hash contains the output decision key value pairs
-      @attributes = {}
-
+    def initialize(table:)
       @outs = table.columns.outs
       @outs_functions = table.outs_functions
-      @if_columns = table.columns.ifs
+      @table = table
+    end
 
+    # Initialize the object for new input data.
+    #
+    # @param data [Hash{Symbol=>Object}] Input data hash.
+    # @return [void]
+    def input(data)
+      # Attributes hash contains the output decision key value pairs
+      @attributes = {}
+      @multi_result = false
       # Partial result always copies in the input hash for calculating output functions.
       # Note that these input key values will not be mutated, as output columns can never
       # have the same symbol as an input hash key.
       # However, the rest of this hash is mutated as output column evaluation results
       # are accumulated.
-      @partial_result = input.slice(*table.columns.input_keys) if @outs_functions
+      @partial_result = data.slice(*@table.columns.input_keys) if @outs_functions
     end
 
     # Common case for building a single row result is just copying output column values to the
@@ -57,7 +63,7 @@ module CSVDecision
     # @return [Hash{Symbol=>Object}]
     def final_result
       # If there are no if: columns, then nothing needs to be filtered out of this result hash.
-      return @attributes if @if_columns.empty?
+      return @attributes if @table.columns.ifs.empty?
 
       @multi_result ? multi_row_result : single_row_result
     end
@@ -91,18 +97,18 @@ module CSVDecision
     # Case where we have a single row result, which either gets returned
     # or filtered by the if: column conditions.
     def single_row_result
-      @if_columns.each_key do |col|
-        return false unless @attributes[col]
-
-        # Remove the if: column from the final result hash.
-        @attributes.delete(col)
+      # All if: columns must evaluate to true
+      if @table.columns.ifs.keys.all? { |col| @attributes[col] }
+        # Delete if: columns from final result
+        @table.columns.ifs.each_key { |col| @attributes.delete(col) }
+        return @attributes
       end
 
-      @attributes
+      false
     end
 
     def multi_row_result
-      @if_columns.each_key { |col| check_if_column(col) }
+      @table.columns.ifs.each_key { |col| check_if_column(col) }
 
       normalize_result
     end
@@ -131,46 +137,47 @@ module CSVDecision
       count = @attributes.values.first.count
       @multi_result = count > 1
 
-      case count
-      when 0
-        {}
-
-      # Single row array values do not require arrays.
-      when 1
-        @attributes.transform_values!(&:first)
+      return {} if count.zero?
+      return @attributes.transform_values!(&:first) if count == 1
 
-      else
-        @attributes
-      end
+      @attributes
     end
 
     def eval_outs_constants(row:)
       @outs.each_pair do |col, column|
-        value = row[col]
-        next if value.is_a?(Matchers::Proc)
+        cell = row[col]
+        next if cell.is_a?(Matchers::Proc)
 
-        @partial_result[column.name] = value
-        @attributes[column.name] = value
+        @partial_result[column.name] = cell
+        @attributes[column.name] = cell
       end
     end
 
     def eval_outs_procs(row:)
       @outs.each_pair do |col, column|
-        proc = row[col]
-        next unless proc.is_a?(Matchers::Proc)
+        cell = row[col]
+        next unless cell.is_a?(Matchers::Proc)
 
-        @attributes[column.name] = proc.function[@partial_result]
-        @partial_result[column.name] = @attributes[column.name]
+        eval_out_proc(cell: cell, column_name: column.name, column_type: column.type)
       end
     end
 
+    def eval_out_proc(cell:, column_name:, column_type:)
+      @attributes[column_name] = cell.function[@partial_result]
+
+      # Do not add if: columns to the partial result
+      return if column_type == :if
+      @partial_result[column_name] = @attributes[column_name]
+    end
+
     def partial_result(index)
-      @attributes.each_pair do |column_name, value|
+      @attributes.each_pair do |column_name, values|
+        value = values[index]
         # 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)
+        next @partial_result.delete(column_name) if value.is_a?(Matchers::Proc)
 
         # Add this constant value to the partial result row built so far.
-        @partial_result[column_name] = value[index]
+        @partial_result[column_name] = value
       end
 
       @partial_result