csv_decision 0.2.0 → 0.3.0

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jan 13 10:02:46 2018 by
+  Generated on Sat Jan 20 15:44:34 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/columns.rb

@@ -8,6 +8,89 @@ module CSVDecision
   # Dictionary of all this table's columns - inputs, outputs etc.
   # @api private
   class Columns
+    # @param columns [CSVDecision::Columns] Table's columns dictionary.
+    # @param row [Array] Data row.
+    # @return [void]
+    def self.outs_dictionary(columns:, row:)
+      row.each_with_index do |cell, index|
+        outs_check_cell(columns: columns, cell: cell, index: index)
+      end
+    end
+
+    # @param columns [CSVDecision::Columns] Table's columns dictionary.
+    # @param row [Array] Data row.
+    # @return [void]
+    def self.ins_dictionary(columns:, row:)
+      row.each { |cell| ins_cell_dictionary(columns: columns, cell: cell) }
+    end
+
+    # @param columns [CSVDecision::Columns] Table's columns dictionary.
+    # @param cell [Object] Data row cell.
+    # @return [void]
+    def self.ins_cell_dictionary(columns:, cell:)
+      return unless cell.is_a?(Matchers::Proc)
+      return if cell.symbols.nil?
+
+      add_ins_symbols(columns: columns, cell: cell)
+    end
+
+    def self.outs_check_cell(columns:, cell:, index:)
+      return unless cell.is_a?(Matchers::Proc)
+      return if cell.symbols.nil?
+
+      check_outs_symbols(columns: columns, cell: cell, index: index)
+    end
+    private_class_method :outs_check_cell
+
+    def self.check_outs_symbols(columns:, cell:, index:)
+      Array(cell.symbols).each do |symbol|
+        check_outs_symbol(columns: columns, symbol: symbol, index: index)
+      end
+    end
+    private_class_method :check_outs_symbols
+
+    def self.check_outs_symbol(columns:, symbol:, index:)
+      in_out = columns.dictionary[symbol]
+
+      # If its an input column symbol then we're good.
+      return if ins_symbol?(columns: columns, symbol: symbol, in_out: in_out)
+
+      # Check if this output symbol reference is on or after this cell's column
+      invalid_out_ref?(columns, index, in_out)
+    end
+    private_class_method :check_outs_symbol
+
+    # If the symbol exists either as an input or does not exist then we're good.
+    def self.ins_symbol?(columns:, symbol:, in_out:)
+      return true if in_out == :in
+
+      # It must an input symbol, as all the output symbols have been parsed.
+      return columns.dictionary[symbol] = :in if in_out.nil?
+
+      false
+    end
+    private_class_method :ins_symbol?
+
+    def self.invalid_out_ref?(columns, index, in_out)
+      return false if in_out < index
+
+      that_column = if in_out == index
+                      'reference to itself'
+                    else
+                      "an out of order reference to output column '#{columns.outs[in_out].name}'"
+                    end
+      raise CellValidationError,
+            "output column '#{columns.outs[index].name}' makes #{that_column}"
+    end
+    private_class_method :invalid_out_ref?
+
+    def self.add_ins_symbols(columns:, cell:)
+      Array(cell.symbols).each do |symbol|
+        CSVDecision::Dictionary.add_name(columns: columns, name: symbol)
+      end
+    end
+    private_class_method :add_ins_symbols
+
     # Dictionary of all table data columns.
     # The key of each hash is the header cell's array column index.
     # Note that input and output columns may be interspersed, and multiple input columns
@@ -86,8 +169,11 @@ module CSVDecision
       # Return the stripped header row, and remove it from the data array.
       row = Header.strip_empty_columns(rows: table.rows)
 
+      # No header row found?
+      raise TableValidationError, 'table has no header row' unless row
+
       # Build a dictionary of all valid data columns from the header row.
-      @dictionary = CSVDecision::Dictionary.build(header: row, dictionary: Dictionary.new) if row
+      @dictionary = CSVDecision::Dictionary.build(header: row, dictionary: Dictionary.new)
 
       freeze
     end

data/lib/csv_decision/decision.rb

@@ -8,6 +8,28 @@ module CSVDecision
   # Accumulate the matching row(s) and calculate the final result.
   # @api private
   class Decision
+    # Main method for making decisions.
+    #
+    # @param table [CSVDecision::Table] Decision table.
+    # @param input [Hash] Input hash (keys may or may not be symbolized)
+    # @param symbolize_keys [true, false] Set to false if keys are symbolized and it's
+    #   OK to mutate the input hash. Otherwise a copy of the input hash is symbolized.
+    # @return [Hash] 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)
+
+      # The decision object collects the results of the search and
+      # calculates the final result
+      decision = Decision.new(table: table, input: input[:hash])
+
+      if table.index
+        decision.index(table: table, input: input)
+      else
+        decision.scan(table: table, hash: input[:hash], scan_cols: input[:scan_cols])
+      end
+    end
+
     # @param table [CSVDecision::Table] Decision table being processed.
     # @param input [Hash{Symbol=>Object}] Input hash data structure.
     def initialize(table:, input:)
@@ -20,44 +42,47 @@ module CSVDecision
       @rows_picked = []
 
       # Relevant table attributes
-      table_attributes(table)
+      @first_match = table.options[:first_match]
     end
 
     # Scan the decision table up against the input hash.
     #
-    # @param (see #initialize)
-    # @return [{Symbol=>Object}] Decision result.
-    def scan(table:, input:)
+    # @param table (see #initialize)
+    # @param hash [Hash] Input hash.
+    # @param scan_cols [Hash{Index=>Object}] Input column values to scan.
+    # @return [Hash{Symbol=>Object}] Decision result.
+    def scan(table:, hash:, scan_cols:)
       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])
+        next unless table.scan_rows[index].match?(row: row, hash: hash, scan_cols: scan_cols)
+        return @result.attributes if add(row)
       end
 
-      result
+      @rows_picked.empty? ? {} : accumulated_result
     end
 
-    private
+    # Use an index to scan the decision table up against the input hash.
+    #
+    # @param (see #initialize)
+    # @param input [Hash] Hash of parsed input data.
+    # @return [{Symbol=>Object}] Decision result.
+    def index(table:, input:)
+      # If the index lookup fails, there's no match
+      return {} unless (rows = table.index.hash[input[:key]])
 
-    # Record the relevant table attributes.
-    def table_attributes(table)
-      @first_match = table.options[:first_match]
-      @outs = table.columns.outs
-      @outs_functions = table.outs_functions
+      index_scan(table: table, scan_cols: input[:scan_cols], hash: input[:hash], rows: Array(rows))
     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 ? @result.attributes : accumulated_result
-    end
+    private
+
+    def index_scan(table:, scan_cols:, hash:, rows:)
+      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 add(row)
+        end
+      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)
+      @rows_picked.empty? ? {} : accumulated_result
     end
 
     # Add a matched row to the decision object being built.
@@ -76,7 +101,7 @@ module CSVDecision
     end
 
     def accumulated_result
-      return @result.final unless @outs_functions
+      return @result.final unless @result.outs_functions
       return @result.eval_outs(@rows_picked.first) unless @result.multi_result
 
       multi_row_result
@@ -84,12 +109,12 @@ module CSVDecision
 
     def multi_row_result
       # Scan each output column that contains functions
-      @outs.each_pair { |col, column| eval_column_procs(col: col, column: column) if column.eval }
+      @result.outs.each_pair { |col, column| eval_procs(col: col, column: column) if column.eval }
 
       @result.final
     end
 
-    def eval_column_procs(col:, column:)
+    def eval_procs(col:, column:)
       @rows_picked.each_with_index do |row, index|
         proc = row[col]
         next unless proc.is_a?(Matchers::Proc)
@@ -103,7 +128,7 @@ module CSVDecision
       # 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
+      return eval_single_row(row) if @result.outs_functions
 
       # Common case is just copying output column values to the final result.
       @rows_picked = row

data/lib/csv_decision/defaults.rb

@@ -40,7 +40,7 @@ module CSVDecision
       entry.function = cell.function
 
       # Add any referenced input column symbols to the column name dictionary
-      Parse.ins_cell_dictionary(columns: columns, cell: cell)
+      Columns.ins_cell_dictionary(columns: columns, cell: cell)
     end
     private_class_method :parse_cell
   end

data/lib/csv_decision/dictionary.rb

@@ -8,6 +8,19 @@ module CSVDecision
   # Parse the CSV file's header row. These methods are only required at table load time.
   # @api private
   module Dictionary
+    # Add a new symbol to the dictionary of named input and output columns.
+    #
+    # @param columns [{Symbol=>Symbol}] Hash of column names with key values :in or :out.
+    # @param name [Symbol] Symbolized column name.
+    # @param out [false, Index] False if an input column, otherwise the index of the output column.
+    # @return [Hash{Symbol=>[:in, Integer]}] Column dictionary updated with the new name.
+    def self.add_name(columns:, name:, out: false)
+      Validate.name(columns: columns, name: name, out: out)
+
+      columns[name] = out ? out : :in
+      columns
+    end
+
     # Column dictionary entries.
     class Entry
       # Table used to build a column dictionary entry.
@@ -29,14 +42,18 @@ module CSVDecision
       private_constant :INS_TYPES
 
       # Create a new column dictionary entry defaulting attributes from the column type,
-      # which is looked up in +ENTRY+ table.
+      # which is looked up in the above table.
       #
       # @param name [Symbol] Column name.
       # @param type [Symbol] Column type.
       # @return [Entry] Column dictionary entry.
       def self.create(name:, type:)
         entry = ENTRY[type]
-        new(name: name, eval: entry[:eval], type: entry[:type], set_if: entry[:set_if])
+        new(name: name,
+            eval: entry[:eval],              # Set if the column requires functions evaluated
+            type: entry[:type],              # Column type
+            set_if: entry[:set_if],          # Set if the column has a conditional default
+            indexed: entry[:type] != :guard) # A guard column cannot be indexed.
       end
 
       # @return [Boolean] Return true is this is an input column, false otherwise.
@@ -50,6 +67,9 @@ module CSVDecision
       # @return [Symbol] Column type.
       attr_reader :type
 
+      # @return [Boolean] Returns true if this column is indexed
+      attr_accessor :indexed
+
       # @return [nil, Boolean] If set to true then this column has procs that
       #   need evaluating, otherwise it only contains constants.
       attr_accessor :eval
@@ -67,13 +87,15 @@ module CSVDecision
       # @param type (see #type)
       # @param eval (see #eval)
       # @param set_if (see #set_if)
-      def initialize(name:, type:, eval: nil, set_if: nil)
+      # @param indexed (see #indexed)
+      def initialize(name:, type:, eval: nil, set_if: nil, indexed: nil)
         @name = name
         @type = type
         @eval = eval
         @set_if = set_if
         @function = nil
         @ins = INS_TYPES.member?(type)
+        @indexed = indexed
       end
 
       # Convert the object's attributes to a hash.
@@ -93,7 +115,8 @@ module CSVDecision
     # 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.
+    # @param dictionary [Columns::Dictionary] Table's columns dictionary.
+    # @return [Columns::Dictionary] Table's columns dictionary.
     def self.build(header:, dictionary:)
       header.each_with_index do |cell, index|
         dictionary = parse_cell(cell: cell, index: index, dictionary: dictionary)
@@ -102,19 +125,6 @@ module CSVDecision
       dictionary
     end
 
-    # Add a new symbol to the dictionary of named input and output columns.
-    #
-    # @param columns [{Symbol=>Symbol}] Hash of column names with key values :in or :out.
-    # @param name [Symbol] Symbolized column name.
-    # @param out [false, Index] False if an input column, otherwise the index of the output column.
-    # @return [Hash{Symbol=>[:in, Integer]}] Column dictionary updated with the new name.
-    def self.add_name(columns:, name:, out: false)
-      Validate.name(columns: columns, name: name, out: out)
-
-      columns[name] = out ? out : :in
-      columns
-    end
-
     def self.parse_cell(cell:, index:, dictionary:)
       column_type, column_name = Validate.column(cell: cell, index: index)
 
@@ -139,16 +149,16 @@ module CSVDecision
     private_class_method :dictionary_entry
 
     def self.output_entry(dictionary:, entry:, index:)
+      dictionary.outs[index] = entry
+
       case entry.type
-      # if: columns are anonymous
+      # if: columns are anonymous, even if the user names them
       when :if
         dictionary.ifs[index] = entry
 
       when :out
-        add_name(columns: dictionary.columns, name: entry.name, out: index)
+        Dictionary.add_name(columns: dictionary.columns, name: entry.name, out: index)
       end
-
-      dictionary.outs[index] = entry
     end
     private_class_method :output_entry
 
@@ -159,7 +169,7 @@ module CSVDecision
       dictionary.defaults[index] = entry if entry.type == :set
 
       # guard: columns are anonymous
-      add_name(columns: dictionary.columns, name: entry.name) unless entry.type == :guard
+      Dictionary.add_name(columns: dictionary.columns, name: entry.name) unless entry.type == :guard
     end
     private_class_method :input_entry
   end

data/lib/csv_decision/header.rb

@@ -52,6 +52,23 @@ module CSVDecision
       rows.shift
     end
 
+    # Parse the header row, and the defaults row if present.
+    # @param table [CSVDecision::Table] Decision table being parsed.
+    # @param matchers [Array<Matchers::Matcher>] Array of special cell matchers.
+    # @return [CSVDecision::Columns] Table columns object.
+    def self.parse(table:, matchers:)
+      # Parse the header row
+      table.columns = CSVDecision::Columns.new(table)
+
+      # Parse the defaults row if present
+      return table.columns if table.columns.defaults.blank?
+
+      table.columns.defaults =
+        Defaults.parse(columns: table.columns, matchers: matchers.outs, row: table.rows.shift)
+
+      table.columns
+    end
+
     # Build an array of all empty column indices.
     # @param row [Array]
     # @return [false, Array<Integer>]

data/lib/csv_decision/index.rb

@@ -0,0 +1,107 @@
+# 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 Index
+    # Build the index on the designated number of input columns.
+    #
+    # @param table [CSVDecision::Table] Decision table being indexed.
+    # @return [CSVDecision::Index] The built index.
+    def self.build(table:)
+      # Do we even have an index?
+      key_cols = index_columns(columns: table.columns.ins)
+      return if key_cols.empty?
+
+      table.index = Index.new(table: table, columns: key_cols)
+
+      # Indexed columns do not need to be scanned
+      trim_scan_rows(scan_rows: table.scan_rows, index_columns: table.index.columns)
+
+      table
+    end
+
+    # @param current_value [Integer, Array] Current index key value.
+    # @param index [Integer] Array row index to be included in the table index entry.
+    # @return [Integer, Array] New index key value.
+    def self.value(current_value, index)
+      return integer_value(current_value, index) if current_value.is_a?(Integer)
+
+      array_value(current_value, index)
+
+      current_value
+    end
+
+    def self.trim_scan_rows(scan_rows:, index_columns:)
+      scan_rows.each { |scan_row| scan_row.constants = scan_row.constants - index_columns }
+    end
+    private_class_method :trim_scan_rows
+
+    def self.index_columns(columns:)
+      key_cols = []
+      columns.each_pair { |col, column| key_cols << col if column.indexed }
+
+      key_cols
+    end
+    private_class_method :index_columns
+
+    # Current value is a row index integer
+    def self.integer_value(current_value, index)
+      # Is the new row index contiguous with the last start row/end row range?
+      current_value + 1 == index ? [[current_value, index]] : [current_value, index]
+    end
+    private_class_method :integer_value
+
+    # Current value is an array of row indexes
+    def self.array_value(current_value, index)
+      start_row, end_row = current_value.last
+
+      end_row = start_row if end_row.nil?
+
+      # Is the new row index contiguous with the last start row/end row range?
+      end_row + 1 == index ? current_value[-1] = [start_row, index] : current_value << index
+    end
+    private_class_method :array_value
+
+    # @return [Hash] The index hash mapping in input values to one or more data array row indexes.
+    attr_reader :hash
+
+    # @return [Array<Integer>] Array of column indices
+    attr_reader :columns
+
+    # @param table [CSVDecision::Table] Decision table.
+    # @param columns [Array<Index>] Array of column indexes to be indexed.
+    def initialize(table:, columns:)
+      @columns = columns
+      @hash = {}
+
+      build(table)
+
+      freeze
+    end
+
+    private
+
+    def build(table)
+      table.each do |row, index|
+        key = build_key(row: row)
+
+        current_value = @hash.key?(key)
+        @hash[key] = current_value ? Index.value(@hash[key], index) : index
+      end
+    end
+
+    def build_key(row:)
+      if @columns.count == 1
+        row[@columns[0]]
+      else
+        @columns.map { |col| row[col] }
+      end
+    end
+  end
+end

data/lib/csv_decision/input.rb

@@ -17,24 +17,48 @@ module CSVDecision
     def self.parse(table:, input:, symbolize_keys:)
       validate(input)
 
-      parsed_input =
-        parse_input(table: table, input: input(table, input, symbolize_keys))
+      parsed_input = parse_input(table: table, input: symbolize_keys ? input.symbolize_keys : input)
 
-      # We can freeze it as we made our own copy
-      parsed_input[:hash].freeze if symbolize_keys
+      key = table.index ? parse_key(table: table, hash: parsed_input[:hash]) : nil
 
-      parsed_input.freeze
+      result(symbolize_keys: symbolize_keys, input: parsed_input, key: key)
     end
 
-    def self.input(table, input, symbolize_keys)
-      return input unless symbolize_keys
+    def self.result(symbolize_keys:, input:, key:)
+      hash = input[:hash]
+      {
+        # We can freeze the input hash for safety if we made our own copy.
+        hash: symbolize_keys ? hash.freeze : hash,
+        scan_cols:  input[:scan_cols].freeze,
+        # Build the index key if this table is indexed.
+        key: key
+      }
+    end
+    private_class_method :result
+
+    def self.parse_key(table:, hash:)
+      return scan_key(table: table, hash: hash) if table.index.columns.count == 1
+
+      scan_keys(table: table, hash: hash).freeze
+    end
+    private_class_method :parse_key
+
+    def self.scan_key(table:, hash:)
+      col = table.index.columns[0]
+      column = table.columns.ins[col]
+
+      hash[column.name]
+    end
+    private_class_method :scan_key
+
+    def self.scan_keys(table:, hash:)
+      table.index.columns.map do |col|
+        column = table.columns.ins[col]
 
-      # For safety the default is to symbolize the keys of a copy of the input hash.
-      input = input.symbolize_keys
-      input.slice!(*table.columns.input_keys)
-      input
+        hash[column.name]
+      end
     end
-    private_class_method :input
+    private_class_method :scan_keys
 
     def self.validate(input)
       return if input.is_a?(Hash) && !input.empty?
@@ -44,10 +68,13 @@ module CSVDecision
 
     def self.parse_input(table:, input:)
       defaulted_columns = table.columns.defaults
-      parse_cells(table: table, input: input) if defaulted_columns.empty?
+
+      # 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:)
@@ -60,6 +87,7 @@ module CSVDecision
 
       { hash: input, scan_cols: scan_cols }
     end
+
     private_class_method :parse_cells
 
     def self.parse_defaulted(table:, input:, defaulted_columns:)
@@ -77,6 +105,7 @@ module CSVDecision
 
       { hash: input, scan_cols: scan_cols }
     end
+
     private_class_method :parse_defaulted
 
     def self.default_value(default:, input:, column:)
@@ -92,11 +121,13 @@ module CSVDecision
       # or else a constant.
       eval_default(default.function, input)
     end
+
     private_class_method :default_value
 
     def self.default_if?(set_if, value)
       set_if == true || (value.respond_to?(set_if) && value.send(set_if))
     end
+
     private_class_method :default_if?
 
     # Expression may be a Proc that needs evaluating against the input hash,
@@ -104,6 +135,7 @@ module CSVDecision
     def self.eval_default(expression, input)
       expression.is_a?(::Proc) ? expression[input] : expression
     end
+
     private_class_method :eval_default
   end
 end

data/lib/csv_decision/matchers/guard.rb

@@ -46,12 +46,14 @@ module CSVDecision
       def self.symbol_function(symbol, method, hash)
         hash[symbol].respond_to?(method) && hash[symbol].send(method)
       end
+      private_class_method :symbol_function
 
       def self.regexp_match(symbol, value, hash)
         return false unless value.is_a?(String)
         data = hash[symbol]
         data.is_a?(String) && Matchers.regexp(value).match?(data)
       end
+      private_class_method :regexp_match
 
       FUNCTION = {
         '.'  => proc { |symbol, method, hash|  symbol_function(symbol, method, hash) },