csv_decision2 0.5.1

data/lib/csv_decision/dictionary.rb

@@ -0,0 +1,180 @@
+# 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
+    # 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.
+      ENTRY = {
+        in:           { type: :in,    eval: nil },
+        'in/text':    { type: :in,    eval: false },
+        set:          { type: :set,   eval: nil, set_if: true },
+        'set/nil?':   { type: :set,   eval: nil, set_if: :nil? },
+        'set/blank?': { type: :set,   eval: nil, set_if: :blank? },
+        out:          { type: :out,   eval: nil },
+        'out/text':   { type: :out,   eval: false },
+        guard:        { type: :guard, eval: true },
+        if:           { type: :if,    eval: true },
+        path:         { type: :path,  eval: false }
+      }.freeze
+      private_constant :ENTRY
+
+      # Input column types.
+      INS_TYPES = %i[in guard set].freeze
+      private_constant :INS_TYPES
+
+      # Create a new column dictionary entry defaulting attributes from the column type,
+      # 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],              # 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.
+      def ins?
+        @ins
+      end
+
+      # @return [Symbol] Column name.
+      attr_reader :name
+
+      # @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
+
+      # @return [nil, true, Symbol] Defined for columns of type :set, nil otherwise.
+      #   If true, then default is set unconditionally, otherwise the method symbol
+      #   sent to the input hash value that must evaluate to a truthy value.
+      attr_reader :set_if
+
+      # @return [Matchers::Proc, Object] For a column of type set: gives the proc that must be
+      #   evaluated to set the default value. If not a proc, then it's some type of constant.
+      attr_accessor :function
+
+      # @param name (see #name)
+      # @param type (see #type)
+      # @param eval (see #eval)
+      # @param set_if (see #set_if)
+      # @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.
+      #
+      # @return [Hash{Symbol=>[nil, Boolean, Symbol]}]
+      def to_h
+        {
+          name: @name,
+          type: @type,
+          eval: @eval,
+          set_if: @set_if
+        }
+      end
+    end
+
+    # 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.
+    # @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)
+      end
+
+      dictionary
+    end
+
+    def self.parse_cell(cell:, index:, dictionary:)
+      column_type, column_name = Validate.column(cell: cell, index: index)
+
+      dictionary_entry(dictionary: dictionary,
+                       entry: Entry.create(name: column_name, type: column_type),
+                       index: index)
+    end
+    private_class_method :parse_cell
+
+    def self.dictionary_entry(dictionary:, entry:, index:)
+      case entry.type
+      # A guard column is still added to the ins hash for parsing as an input column.
+      when :in, :guard, :set
+        input_entry(dictionary: dictionary, entry: entry, index: index)
+
+      when :out, :if
+        output_entry(dictionary: dictionary, entry: entry, index: index)
+
+      when :path
+        dictionary.paths[index] = entry
+      end
+
+      dictionary
+    end
+    private_class_method :dictionary_entry
+
+    def self.output_entry(dictionary:, entry:, index:)
+      dictionary.outs[index] = entry
+
+      case entry.type
+      # if: columns are anonymous, even if the user names them
+      when :if
+        dictionary.ifs[index] = entry
+
+      when :out
+        Dictionary.add_name(columns: dictionary.columns, name: entry.name, out: index)
+      end
+    end
+    private_class_method :output_entry
+
+    def self.input_entry(dictionary:, entry:, index:)
+      dictionary.ins[index] = entry
+
+      # Default function will set the input value unconditionally or conditionally.
+      dictionary.defaults[index] = entry if entry.type == :set
+
+      # guard: columns are anonymous
+      Dictionary.add_name(columns: dictionary.columns, name: entry.name) unless entry.type == :guard
+    end
+    private_class_method :input_entry
+  end
+end

data/lib/csv_decision/header.rb

@@ -0,0 +1,83 @@
+# 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 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|path)
+      \s*:\s*(?<name>\S?.*)\z
+    }xi
+
+    # 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:/!?]*"
+
+    # Regular expression for matching a column name.
+    COLUMN_NAME_RE = Matchers.regexp(Header::COLUMN_NAME)
+    private_constant :COLUMN_NAME_RE
+
+    # Return true if column name is valid.
+    #
+    # @param column_name [String]
+    # @return [Boolean]
+    def self.column_name?(column_name)
+      COLUMN_NAME_RE.match?(column_name)
+    end
+
+    # 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.any? { |cell| COLUMN_TYPE.match?(cell) }
+    end
+
+    # Strip empty columns from all data rows.
+    #
+    # @param rows [Array<Array<String>>] Data rows.
+    # @return [Array<Array<String>>] Data array after removing any empty columns
+    #   and the header row.
+    def self.strip_empty_columns(rows:)
+      empty_cols = empty_columns?(row: rows.first)
+      Data.strip_columns(data: rows, empty_columns: empty_cols) if empty_cols
+
+      # Remove header row from the data array.
+      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>]
+    def self.empty_columns?(row:)
+      result = []
+      row&.each_with_index { |cell, index| result << index if cell == '' }
+
+      result.empty? ? false : result
+    end
+    private_class_method :empty_columns?
+  end
+end

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

@@ -0,0 +1,121 @@
+# 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 input hash.
+  # @api private
+  module Input
+    # @param (see Decision.make)
+    # @return [Hash{Symbol=>Object}]
+    def self.parse(table:, input:, symbolize_keys:)
+      validate(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
+
+      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]
+
+        hash[column.name]
+      end
+    end
+    private_class_method :scan_keys
+
+    def self.validate(input)
+      return if input.is_a?(Hash) && !input.empty?
+      raise ArgumentError, 'input must be a non-empty hash'
+    end
+    private_class_method :validate
+
+    def self.parse_cells(table:, input:)
+      scan_cols = {}
+      table.columns.ins.each_pair do |col, column|
+        next if column.type == :guard
+
+        scan_cols[col] = input[column.name]
+      end
+
+      { hash: input, scan_cols: scan_cols }
+    end
+    private_class_method :parse_cells
+
+    def self.parse_defaulted(table:, input:, defaulted_columns:)
+      scan_cols = {}
+
+      table.columns.ins.each_pair do |col, column|
+        next if column.type == :guard
+
+        scan_cols[col] =
+          default_value(default: defaulted_columns[col], input: input, column: column)
+
+        # Also update the input hash with the default value.
+        input[column.name] = scan_cols[col]
+      end
+
+      { hash: input, scan_cols: scan_cols }
+    end
+    private_class_method :parse_defaulted
+
+    def self.default_value(default:, input:, column:)
+      value = input[column.name]
+
+      # Do we even have a default entry for this column?
+      return value if default.nil?
+
+      # Has the set condition been met, or is it unconditional?
+      return value unless default_if?(default.set_if, value)
+
+      # Expression may be a Proc that needs evaluating against the input hash,
+      # 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,
+    # or else a constant.
+    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/load.rb

@@ -0,0 +1,36 @@
+# 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
+  # Load all the CSV files located in the designated folder path.
+  #
+  # @param path [Pathname] Directory containing CSV decision table files.
+  # @param options (see CSVDecision.parse)
+  # @return [Hash{Symbol=><CSVDecision::Table>}] Hash of decision tables keyed by the CSV
+  #   file's symbolized base name.
+  # @raise [ArgumentError] Invalid path name or folder.
+  def self.load(path, options = {})
+    Load.path(path: path, options: options)
+  end
+
+  # Load all CSV files located in the specified folder.
+  # @api private
+  module Load
+    # (see CSVDecision.load)
+    def self.path(path:, options:)
+      raise ArgumentError, 'path argument must be a Pathname' unless path.is_a?(Pathname)
+      raise ArgumentError, 'path argument not a valid folder' unless path.directory?
+
+      tables = {}
+      Dir[path.join('*.csv')].each do |file_name|
+        table_name = File.basename(file_name, '.csv').to_sym
+        tables[table_name] = CSVDecision.parse(Pathname(file_name), options)
+      end
+
+      tables.freeze
+    end
+  end
+end

data/lib/csv_decision/matchers/constant.rb

@@ -0,0 +1,74 @@
+# 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
+  # Methods to assign a matcher to data cells
+  # @api private
+  class Matchers
+    # Cell constant matcher - e.g., := true, = nil.
+    class Constant < Matcher
+      # Cell constant expression specified by prefixing the value with one of the three
+      # equality symbols.
+      EXPRESSION = Matchers.regexp("(?<operator>#{Matchers::EQUALS})\\s*(?<value>\\S.*)")
+      private_constant :EXPRESSION
+
+      # rubocop: disable Lint/BooleanSymbol
+      # Non-numeric constants recognised by CSV Decision.
+      NON_NUMERIC = {
+        nil: nil,
+        true: true,
+        false: false
+      }.freeze
+      private_constant :NON_NUMERIC
+      # rubocop: enable Lint/BooleanSymbol
+
+      # @param (see Matchers::Matcher#matches?)
+      # @return (see Matchers::Matcher#matches?)
+      # @api private
+      def self.matches?(cell)
+        return false unless (match = EXPRESSION.match(cell))
+
+        proc = non_numeric?(match)
+        return proc if proc
+
+        numeric?(match)
+      end
+
+      def self.proc(function:)
+        Matchers::Proc.new(type: :constant, function: function)
+      end
+      private_class_method :proc
+
+      def self.numeric?(match)
+        return false unless (value = Matchers.to_numeric(match['value']))
+
+        proc(function: value)
+      end
+      private_class_method :numeric?
+
+      def self.non_numeric?(match)
+        name = match['value'].to_sym
+        return false unless NON_NUMERIC.key?(name)
+
+        proc(function: NON_NUMERIC[name])
+      end
+      private_class_method :non_numeric?
+
+      # If a constant expression returns a Proc of type :constant,
+      #   otherwise return false.
+      #
+      # (see Matcher#matches?)
+      def matches?(cell)
+        Matchers::Constant.matches?(cell)
+      end
+
+      # (see Matcher#outs?)
+      def outs?
+        true
+      end
+    end
+  end
+end

data/lib/csv_decision/matchers/function.rb

@@ -0,0 +1,56 @@
+# 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
+  # Methods to assign a matcher to data cells
+  # @api private
+  class Matchers
+    # Match cell against a function call
+    #   * no arguments - e.g., := present?
+    #   * with arguments - e.g., :=lookup?(:table)
+    # TODO: fully implement
+    class Function < Matcher
+      # Looks like a function call or symbol expressions, e.g.,
+      # == true
+      # := function(arg: symbol)
+      # == :column_name
+      FUNCTION_CALL =
+        "(?<operator>=|:=|==|=|<|>|!=|>=|<=|:|!\\s*:)\\s*" \
+        "(?<negate>!?)\\s*" \
+        "(?<name>#{Header::COLUMN_NAME}|:)(?<args>.*)"
+      private_constant :FUNCTION_CALL
+
+      # Function call regular expression.
+      FUNCTION_RE = Matchers.regexp(FUNCTION_CALL)
+
+      def self.matches?(cell)
+        match = FUNCTION_RE.match(cell)
+        return false unless match
+
+        # operator = match['operator']&.gsub(/\s+/, '')
+        # name = match['name'].to_sym
+        # args = match['args'].strip
+        # negate = match['negate'] == Matchers::NEGATE
+      end
+
+      # @param options (see Parse.parse)
+      def initialize(options = {})
+        @options = options
+      end
+
+      # @param (see Matchers::Matcher#matches?)
+      # @return (see Matchers::Matcher#matches?)
+      def matches?(cell)
+        Function.matches?(cell)
+      end
+
+      # (see Matcher#outs?)
+      # def outs?
+      #   true
+      # end
+    end
+  end
+end