csv_decision2 0.5.1

data/lib/csv_decision/result.rb

@@ -0,0 +1,204 @@
+# 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
+  # Accumulate the matching row(s) into a result hash.
+  # @api private
+  class Result
+    # @return [Hash{Symbol=>Object}, Hash{Integer=>Object}] The decision result hash containing
+    #   both result values and if: columns, which eventually get evaluated and removed.
+    attr_reader :attributes
+
+    # @return [Hash{Index=>Dictionary::Entry}] Output columns.
+    attr_reader :outs
+
+    # @return [nil, true] Set to true if the table has output functions.
+    attr_reader :outs_functions
+
+    # @return [Boolean] Returns true if this is a multi-row result
+    attr_reader :multi_result
+
+    # (see Decision.initialize)
+    def initialize(table:)
+      @outs = table.columns.outs
+      @outs_functions = table.outs_functions
+      @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 = 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
+    # final result hash.
+    # @param row [Array]
+    # @return [void]
+    def add_outs(row)
+      @outs.each_pair { |col, column| @attributes[column.name] = row[col] }
+    end
+
+    # Accumulate the outs into arrays of values.
+    # @param row [Array]
+    # @return [void]
+    def accumulate_outs(row)
+      @outs.each_pair { |col, column| add_cell(column_name: column.name, cell: row[col]) }
+    end
+
+    # Derive the final result.
+    # @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 @table.columns.ifs.empty?
+
+      @multi_result ? multi_row_result : single_row_result
+    end
+
+    # Evaluate the output columns, and use them to start building the final result,
+    # along with the partial result required to evaluate functions.
+    #
+    # @param row [Array]
+    # @return (see #final)
+    def eval_outs(row)
+      # Set the constants first, in case the functions refer to them
+      eval_outs_constants(row: row)
+
+      # Then evaluate the procs, left to right
+      eval_outs_procs(row: row)
+
+      final_result
+    end
+
+    # Evaluate the cell proc using the partial result calculated so far.
+    #
+    # @param proc [Matchers::Pro]
+    # @param column_name [Symbol, Integer]
+    # @param index [Integer]
+    def eval_cell_proc(proc:, column_name:, index:)
+      @attributes[column_name][index] = proc.function[partial_result(index)]
+    end
+
+    private
+
+    # Case where we have a single row result, which either gets returned
+    # or filtered by the if: column conditions.
+    def single_row_result
+      # 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
+
+      false
+    end
+
+    def multi_row_result
+      @table.columns.ifs.each_key { |col| check_if_column(col) }
+
+      normalize_result
+    end
+
+    def check_if_column(col)
+      delete_rows = []
+      @attributes[col].each_with_index { |value, index| delete_rows << index unless value }
+
+      # Remove this if: column from the final result
+      @attributes.delete(col)
+
+      # Adjust the row index as we delete rows in sequence.
+      delete_rows.each_with_index { |index, sequence| delete_row(index - sequence) }
+    end
+
+    # Each result "row", given by the row +index+ is a collection of column arrays.
+    # @param index [Integer] Row index.
+    # @return [{Symbol=>Object}, {Integer=>Object}]
+    def delete_row(index)
+      @attributes.transform_values { |value| value.delete_at(index) }
+    end
+
+    # @return [{Symbol=>Object}] Decision result hash with any if: columns removed.
+    def normalize_result
+      # Peek at the first column's result and see how many rows it contains.
+      count = @attributes.values.first.count
+      @multi_result = count > 1
+
+      return {} if count.zero?
+      return @attributes.transform_values!(&:first) if count == 1
+
+      @attributes
+    end
+
+    def eval_outs_constants(row:)
+      @outs.each_pair do |col, column|
+        cell = row[col]
+        next if cell.is_a?(Matchers::Proc)
+
+        @partial_result[column.name] = cell
+        @attributes[column.name] = cell
+      end
+    end
+
+    def eval_outs_procs(row:)
+      @outs.each_pair do |col, column|
+        cell = row[col]
+        next unless cell.is_a?(Matchers::Proc)
+
+        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, 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.is_a?(Matchers::Proc)
+
+        # Add this constant value to the partial result row built so far.
+        @partial_result[column_name] = value
+      end
+
+      @partial_result
+    end
+
+    def add_cell(column_name:, cell:)
+      case (current = @attributes[column_name])
+      when nil
+        @attributes[column_name] = cell
+
+      when Matchers::Proc
+        @attributes[column_name] = [current, cell]
+        @multi_result = true
+
+      when Array
+        @attributes[column_name] << cell
+
+      else
+        @attributes[column_name] = [current, cell]
+        @multi_result = true
+      end
+    end
+  end
+end

data/lib/csv_decision/scan.rb

@@ -0,0 +1,117 @@
+# 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
+  # Scan the input hash for all the paths specified in the decision table
+  # @api private
+  class Scan
+    # Main method for making decisions with a table that has paths.
+    #
+    # @param table [CSVDecision::Table] Decision table.
+    # @param input [Hash] Input hash (keys may or may not be symbolized)
+    # @param symbolize_keys [Boolean] 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{Symbol=>Object}] Decision result.
+    def self.table(table:, input:, symbolize_keys:)
+      input = symbolize_keys ? input.deep_symbolize_keys : input
+      decision = Decision.new(table: table)
+      input_hashes = InputHashes.new
+
+      if table.options[:first_match]
+        scan_first_match(input: input, decision: decision, input_hashes: input_hashes)
+      else
+        scan_accumulate(input: input, decision: decision, input_hashes: input_hashes)
+      end
+    end
+
+    def self.scan_first_match(input:, decision:, input_hashes:)
+      decision.table.paths.each do |path, rows|
+        data = input_hashes.data(decision: decision, path: path, input: input)
+        next if data == {}
+
+        # Note that +rows+ must be enclosed in an array for this method to work.
+        result = decision.index_scan_first_match(
+          scan_cols: data[:scan_cols],
+          hash: data[:hash],
+          index_rows: [rows]
+        )
+        return result if result != {}
+      end
+
+      {}
+    end
+    private_class_method :scan_first_match
+
+    def self.scan_accumulate(input:, decision:, input_hashes:)
+      # Final result
+      result = {}
+
+      decision.table.paths.each do |path, rows|
+        data = input_hashes.data(decision: decision, path: path, input: input)
+        next if data == {}
+
+        result = scan(rows: rows, input: data, final: result, decision: decision)
+      end
+
+      result
+    end
+    private_class_method :scan_accumulate
+
+    def self.scan(rows:, input:, final:, decision:)
+      # Note that +rows+ must be enclosed in an array for this method to work.
+      result = decision.index_scan_accumulate(scan_cols: input[:scan_cols],
+                                              hash: input[:hash],
+                                              index_rows: [rows])
+
+      # Accumulate this potentially multi-row result into the final result.
+      final = accumulate(final: final, result: result) if result.present?
+
+      final
+    end
+    private_class_method :scan
+
+    def self.accumulate(final:, result:)
+      return result if final == {}
+
+      final.each_pair { |key, value| final[key] = Array(value) + Array(result[key]) }
+      final
+    end
+    private_class_method :accumulate
+
+    # Derive the parsed input hash, using a cache for speed.
+    class InputHashes
+      def initialize
+        @input_hashes = {}
+      end
+
+      # @param path [Array<Symbol] Path for the input hash.
+      # @param input [Hash{Symbol=>Object}] Input hash.
+      # @return [Hash{Symbol=>Object}] Parsed input hash.
+      def data(decision:, path:, input:)
+        result = input(decision: decision, path: path, input: input)
+
+        decision.input(result) unless result == {}
+
+        result
+      end
+
+      private
+
+      def input(decision:, path:, input:)
+        return @input_hashes[path] if @input_hashes.key?(path)
+
+        # Use the path - an array of symbol keys, to dig out the input sub-hash
+        hash = path.empty? ? input : input.dig(*path)
+
+        # Parse and transform the hash supplied as input
+        data = hash.blank? ? {} : Input.parse_data(table: decision.table, input: hash)
+
+        # Cache the parsed input hash data for this path
+        @input_hashes[path] = data
+      end
+    end
+  end
+end

data/lib/csv_decision/scan_row.rb

@@ -0,0 +1,142 @@
+# 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
+  # Data row object indicating which columns are constants versus procs.
+  # @api private
+  class ScanRow
+    # These column types cannot have constants in their data cells.
+    NO_CONSTANTS = Set.new(%i[guard if]).freeze
+    private_constant :NO_CONSTANTS
+
+    # Scan the table cell against all matches.
+    #
+    # @param column [Dictionary::Entry] Column dictionary entry.
+    # @param matchers [Array<Matchers::Matcher>]
+    # @param cell [String]
+    # @return [false, Matchers::Proc]
+    def self.scan(column:, matchers:, cell:)
+      return false if cell == ''
+
+      proc = scan_matchers(column: column, matchers: matchers, cell: cell)
+      return proc if proc
+
+      # Must be a simple string constant - this is OK except for a certain column types.
+      invalid_constant?(type: :constant, column: column)
+    end
+
+    def self.scan_matchers(column:, matchers:, cell:)
+      matchers.each do |matcher|
+        # Guard function only accepts the same matchers as an output column.
+        next if guard_ins_matcher?(column, matcher)
+
+        proc = scan_proc(column: column, cell: cell, matcher: matcher)
+        return proc if proc
+      end
+
+      # Must be a string constant
+      false
+    end
+    private_class_method :scan_matchers
+
+    # A guard column can only use output matchers
+    def self.guard_ins_matcher?(column, matcher)
+      column.type == :guard && !matcher.outs?
+    end
+    private_class_method :guard_ins_matcher?
+
+    def self.scan_proc(column:, cell:, matcher:)
+      proc = matcher.matches?(cell)
+      invalid_constant?(type: proc.type, column: column) if proc
+
+      proc
+    end
+    private_class_method :scan_proc
+
+    def self.invalid_constant?(type:, column:)
+      return false unless type == :constant && NO_CONSTANTS.member?(column.type)
+
+      raise CellValidationError, "#{column.type}: column cannot contain constants"
+    end
+    private_class_method :invalid_constant?
+
+    # @return [Array<Integer>] Column indices for simple constants.
+    attr_accessor :constants
+
+    # @return [Array<Integer>] Column indices for Proc objects.
+    attr_reader :procs
+
+    def initialize
+      @constants = []
+      @procs = []
+    end
+
+    # Scan all the specified +columns+ (e.g., inputs) in the given +data+ row using the +matchers+
+    # array supplied.
+    #
+    # @param row [Array<String>] Data row - still just all string constants.
+    # @param columns [Array<Columns::Entry>] Array of column dictionary entries.
+    # @param matchers [Array<Matchers::Matcher>] Array of table cell matchers.
+    # @return [Array] Data row with anything not a string constant replaced with a Proc or a
+    #   non-string constant.
+    def scan_columns(row:, columns:, matchers:)
+      columns.each_pair do |col, column|
+        cell = row[col]
+
+        # An empty input cell matches everything, and so never needs to be scanned,
+        # but it cannot be indexed either.
+        next column.indexed = false if cell == '' && column.ins?
+
+        # If the column is text only then no special matchers need be used.
+        next @constants << col if column.eval == false
+
+        # Need to scan the cell against all matchers, and possibly overwrite
+        # the cell contents with a Matchers::Proc value.
+        row[col] = scan_cell(column: column, col: col, matchers: matchers, cell: cell)
+      end
+
+      row
+    end
+
+    # Match cells in the input hash against a decision table row.
+    # @param row (see ScanRow.scan_columns)
+    # @param hash (see Decision#row_scan)
+    # @return [Boolean] True for a match, false otherwise.
+    def match?(row:, scan_cols:, hash:)
+      # Check any table row cell constants first, and maybe fail fast...
+      return false if @constants.any? { |col| row[col] != scan_cols[col] }
+
+      # These table row cells are Proc objects which need evaluating and
+      # must all return a truthy value.
+      @procs.all? { |col| row[col].call(value: scan_cols[col], hash: hash) }
+    end
+
+    private
+
+    def scan_cell(column:, col:, matchers:, cell:)
+      # Scan the cell against all the matchers
+      proc = ScanRow.scan(column: column, matchers: matchers, cell: cell)
+
+      return set(proc: proc, col: col, column: column) if proc
+
+      # Just a plain constant
+      @constants << col
+      cell
+    end
+
+    def set(proc:, col:, column:)
+      # Unbox a constant
+      if proc.type == :constant
+        @constants << col
+        return proc.function
+      end
+
+      @procs << col
+      column.indexed = false
+      proc
+    end
+  end
+end

data/lib/csv_decision/table.rb

@@ -0,0 +1,101 @@
+# 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
+  # Decision table that accepts an input hash and outputs a decision (hash).
+  class Table
+    # Make a decision based off an input hash.
+    #
+    # @note Input hash keys may or may not be symbolized.
+    # @param input [Hash] Input hash.
+    # @return [{Symbol => Object, Array<Object>}] Decision hash.
+    def decide(input)
+      decision(input: input, symbolize_keys: true)
+    end
+
+    # Unsafe version of decide - may mutate the input hash and assumes the input
+    # hash is symbolized.
+    #
+    # @param input (see #decide)
+    # @note Input hash must have its keys symbolized.
+    #   Input hash will be mutated by any functions that have side effects.
+    # @return (see #decide)
+    def decide!(input)
+      decision( input: input, symbolize_keys: false)
+    end
+
+    # @return [CSVDecision::Columns] Dictionary of all input and output columns.
+    attr_accessor :columns
+
+    # @return [File, Pathname, nil] File path name if decision table was loaded from a
+    # CSV file.
+    attr_accessor :file
+
+    # @return [CSVDecision::Index] The index built on one or more input columns.
+    attr_accessor :index
+
+    # @return [CSVDecision::Path] The array of paths built on one or more input columns.
+    attr_accessor :paths
+
+    # @return [Hash] All options, explicitly set or defaulted, used to parse the table.
+    attr_accessor :options
+
+    # Set if the table row has any output functions (planned feature)
+    # @api private
+    attr_accessor :outs_functions
+
+    # @return [Array<Array>] Data rows after parsing.
+    # @api private
+    attr_accessor :rows
+
+    # @return [Array<CSVDecision::ScanRow>] Scanning objects used to implement input
+    #   matching logic.
+    # @api private
+    attr_accessor :scan_rows
+
+    # @return [Array<CSVDecision::ScanRow>] Used to implement outputting of final results.
+    # @api private
+    attr_accessor :outs_rows
+
+    # @return [Array<CSVDecision::ScanRow>] Used to implement filtering of final results.
+    # @api private
+    attr_accessor :if_rows
+
+    # Iterate through all data rows of the decision table, with an optional
+    # first and last row index given.
+    #
+    # @param first [Integer] Start row.
+    # @param last [Integer, nil] Last row.
+    # @api private
+    def each(first = 0, last = @rows.count - 1)
+      index = first
+      while index <= last
+        yield(@rows[index], index)
+
+        index += 1
+      end
+    end
+
+    # @api private
+    def initialize
+      @paths = []
+      @outs_rows = []
+      @if_rows = []
+      @rows = []
+      @scan_rows = []
+    end
+
+    private
+
+    def decision(input:, symbolize_keys:)
+      if columns.paths.empty?
+        Decision.make(table: self, input: input, symbolize_keys: symbolize_keys)
+      else
+        Scan.table(table: self, input: input, symbolize_keys: symbolize_keys)
+      end
+    end
+  end
+end

data/lib/csv_decision/validate.rb

@@ -0,0 +1,85 @@
+# 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 and validate the column names in the header row.
+  # These methods are only required at table load time.
+  # @api private
+  module Validate
+    # These column types do not need a name.
+    COLUMN_TYPE_ANONYMOUS = Set.new(%i[guard if path]).freeze
+    private_constant :COLUMN_TYPE_ANONYMOUS
+
+    # Validate a column header cell and return its type and name.
+    #
+    # @param cell [String] Header cell.
+    # @param index [Integer] The header column's index.
+    # @return [Array<(Symbol, Symbol)>] Column type and column name symbols.
+    def self.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
+
+    # Validate the column name against the dictionary of column names.
+    #
+    # @param columns [Symbol=>[false, Integer]] Column name dictionary.
+    # @param name [Symbol] Column name.
+    # @param out [false, Integer] False if an input column, otherwise the column index of
+    #   the output column.
+    # @return [void]
+    # @raise [CellValidationError] Column name invalid.
+    def self.name(columns:, name:, out:)
+      return unless (in_out = columns[name])
+
+      return validate_out_name(in_out: in_out, name: name) if out
+      validate_in_name(in_out: in_out, name: name)
+    end
+
+    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?(column_name)
+      raise CellValidationError, "column name '#{name}' contains invalid characters"
+    end
+    private_class_method :format_column_name
+
+    def self.validate_out_name(in_out:, name:)
+      if in_out == :in
+        raise CellValidationError, "output column name '#{name}' is also an input column"
+      end
+
+      raise CellValidationError, "output column name '#{name}' is duplicated"
+    end
+    private_class_method :validate_out_name
+
+    def self.validate_in_name(in_out:, name:)
+      # in: columns may be duped
+      return if in_out == :in
+
+      raise CellValidationError, "output column name '#{name}' is also an input column"
+    end
+    private_class_method :validate_in_name
+  end
+end

data/lib/csv_decision.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object'
+require 'csv_decision/parse'
+
+# 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
+  # @return [String] gem project's root directory
+  def self.root
+    File.dirname __dir__
+  end
+
+  autoload :Columns,    'csv_decision/columns'
+  autoload :Data,       'csv_decision/data'
+  autoload :Decision,   'csv_decision/decision'
+  autoload :Defaults,   'csv_decision/defaults'
+  autoload :Dictionary, 'csv_decision/dictionary'
+  autoload :Header,     'csv_decision/header'
+  autoload :Index,      'csv_decision/index'
+  autoload :Input,      'csv_decision/input'
+  autoload :Load,       'csv_decision/load'
+  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'
+    autoload :Guard,         'csv_decision/matchers/guard'
+    autoload :Numeric,       'csv_decision/matchers/numeric'
+    autoload :Pattern,       'csv_decision/matchers/pattern'
+    autoload :Range,         'csv_decision/matchers/range'
+    autoload :Symbol,        'csv_decision/matchers/symbol'
+  end
+end