csv_decision2 0.5.1

data/lib/csv_decision/matchers.rb

@@ -0,0 +1,220 @@
+# 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
+  # Match table data cells against a valid decision table expression or a simple constant.
+  # @api private
+  class Matchers
+    # Composite object for a data cell proc. Note that we do not need it to be comparable.
+    # Implemented as an immutable array of 2 or 3 entries for memory compactness and speed.
+    # @api private
+    class Proc < Array
+      # @param type [Symbol] Type of the function value - e.g., :constant or :guard.
+      # @param function [Object] Either a lambda function,
+      #   or some kind of constant such as an Integer.
+      # @param symbols [nil, Symbol, Array<Symbol>] The symbol or list of symbols
+      #   that the function uses to reference input hash keys (which are always symbolized).
+      def initialize(type:, function:, symbols: nil)
+        super()
+
+        self << type
+
+        # Function values should always be frozen
+        self << function.freeze
+
+        # Some function values, such as constants or 0-arity functions, do not reference symbols.
+        self << symbols if symbols
+
+        freeze
+      end
+
+      # @param hash [Hash] Input hash to function call.
+      # @param value [Object] Input value to function call.
+      # @return [Object] Value returned from function call.
+      def call(hash:, value: nil)
+        func = fetch(1)
+
+        return func.call(hash) if fetch(0) == :guard
+
+        # All other procs can take one or two args
+        func.arity == 1 ? func.call(value) : func.call(value, hash)
+      end
+
+      # @return [Symbol] Type of the function value - e.g., :constant or :guard.
+      def type
+        fetch(0)
+      end
+
+      # @return [Object] Either a lambda function, or some kind of constant such as an Integer.
+      def function
+        fetch(1)
+      end
+
+      # @return [nil, Symbol, Array<Symbol>] The symbol or list of symbols
+      #   that the function uses to reference input hash keys (which are always symbolized).
+      def symbols
+        fetch(2, nil)
+      end
+    end
+
+    # Negation sign prefixed to ranges and functions.
+    NEGATE = '!'
+
+    # All regular expressions used for matching are anchored inside their own
+    # non-capturing group.
+    #
+    # @param value [String] String used to form an anchored regular expression.
+    # @return [Regexp] Anchored, frozen regular expression.
+    def self.regexp(value)
+      Regexp.new("\\A(?:#{value})\\z").freeze
+    end
+
+    # Symbols used for inequality
+    INEQUALITY = '!=|!'
+
+    # Match Regexp for inequality
+    INEQUALITY_RE = regexp(INEQUALITY)
+
+    # Equality, cell constants and functions specified by prefixing the value with
+    # one of these 3 symbols.
+    EQUALS = '==|:=|='
+
+    # Match Regexp for equality
+    EQUALS_RE = regexp(EQUALS)
+
+    # Method names are stricter than CSV column names.
+    METHOD_NAME_RE = /\A[_a-z][_a-z0-9]*[?!=]?\z/
+
+    # Normalize the operators which are a variation on equals/assignment.
+    #
+    # @param operator [String]
+    # @return [String]
+    def self.normalize_operator(operator)
+      EQUALS_RE.match?(operator) ? '==' : operator
+    end
+
+    # Regular expression used to recognise a numeric string with or without a decimal point.
+    NUMERIC = '[-+]?\d*(?<decimal>\.?)\d*'
+
+    NUMERIC_RE = regexp(NUMERIC)
+    private_constant :NUMERIC_RE
+
+    # Validate a numeric value and convert it to an Integer or BigDecimal if a valid numeric string.
+    #
+    # @param value [nil, String, Integer, BigDecimal]
+    # @return [nil, Integer, BigDecimal]
+    def self.numeric(value)
+      return value if value.is_a?(Integer) || value.is_a?(BigDecimal)
+      return unless value.is_a?(String)
+
+      to_numeric(value)
+    end
+
+    # Convert a numeric string into an Integer or BigDecimal, otherwise return nil.
+    #
+    # @param value [String]
+    # @return [nil, Integer, BigDecimal]
+    def self.to_numeric(value)
+      return unless (match = NUMERIC_RE.match(value))
+
+      return value.to_i if match['decimal'] == ''
+      BigDecimal(value.chomp('.'))
+    end
+
+    # Compare one object with another if they both respond to the compare method.
+    #
+    # @param lhs [Object]
+    # @param compare [Object]
+    # @param rhs [Object]
+    # @return [nil, Boolean]
+    def self.compare?(lhs:, compare:, rhs:)
+      # Is the rhs the same class or a superclass of lhs, and does rhs respond to the
+      # compare method?
+      return lhs.send(compare, rhs) if lhs.is_a?(rhs.class) && rhs.respond_to?(compare)
+
+      nil
+    end
+
+    # Parse the supplied input columns for the row supplied using an array of matchers.
+    #
+    # @param columns [Hash{Integer=>Columns::Entry}] Input columns hash.
+    # @param matchers [Array<Matchers::Matcher>]
+    # @param row [Array<String>] Data row being parsed.
+    # @return [Array<(Array, ScanRow)>] Used to scan a table row against an input hash for matches.
+    def self.parse(columns:, matchers:, row:)
+      # Build an array of column indexes requiring simple constant matches,
+      # and a second array of columns requiring special matchers.
+      scan_row = ScanRow.new
+
+      # Scan the columns in the data row, and build an object to scan this row against
+      # an input hash.
+      # Convert values in the data row if not just a simple constant.
+      row = scan_row.scan_columns(columns: columns, matchers: matchers, row: row)
+
+      [row, scan_row]
+    end
+
+    # @return [Array<Matchers::Matcher>] Matchers for the input columns.
+    attr_reader :ins
+
+    # @return [Array<Matchers::Matcher>] Matchers for the output columns.
+    attr_reader :outs
+
+    # @param options (see CSVDecision.parse)
+    def initialize(options)
+      matchers = options[:matchers].collect { |klass| klass.new(options) }
+      @ins = matchers.select(&:ins?)
+      @outs = matchers.select(&:outs?)
+    end
+
+    # Parse the row's input columns using the input matchers.
+    #
+    # @param columns (see Matchers.parse)
+    # @param row (see Matchers.parse)
+    # @return (see Matchers.parse)
+    def parse_ins(columns:, row:)
+      Matchers.parse(columns: columns, matchers: @ins, row: row)
+    end
+
+    # Parse the row's output columns using the output matchers.
+    #
+    # @param columns (see Matchers.parse)
+    # @param row (see Matchers.parse)
+    # @return (see Matchers.parse)
+    def parse_outs(columns:, row:)
+      Matchers.parse(columns: columns, matchers: @outs, row: row)
+    end
+
+    # Subclass and override {#matches?} to implement a custom Matcher class.
+    class Matcher
+      def initialize(_options = nil); end
+
+      # Determine if the input cell string is recognised by this Matcher.
+      #
+      # @param cell [String] Data row cell.
+      # @return [false, CSVDecision::Proc] Returns false if this cell is not a match; otherwise
+      #   returns the +CSVDecision::Proc+ object indicating if this is a constant or some type of
+      #   function.
+      def matches?(cell); end
+
+      # Does this matcher apply to output cells?
+      #
+      # @return [Boolean] Return true if this matcher applies to output cells,
+      #   false otherwise.
+      def outs?
+        false
+      end
+
+      # Does this matcher apply to output cells?
+      #
+      # @return [Boolean] Return true if this matcher applies to input cells,
+      #   false otherwise.
+      def ins?
+        true
+      end
+    end
+  end
+end

data/lib/csv_decision/options.rb

@@ -0,0 +1,124 @@
+# 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
+  # Validate and normalize the options values supplied.
+  # @api private
+  module Options
+    # Specialized cell value matchers beyond simple string compares.
+    # By default all these matchers are tried in the specified order on all
+    # input data cells.
+    DEFAULT_MATCHERS = [
+      Matchers::Range,
+      Matchers::Numeric,
+      Matchers::Pattern,
+      Matchers::Constant,
+      Matchers::Symbol,
+      Matchers::Guard
+    ].freeze
+
+    # All valid CSVDecision::parse options with their default values.
+    VALID = {
+      first_match: true,
+      regexp_implicit: false,
+      text_only: false,
+      matchers: DEFAULT_MATCHERS
+    }.freeze
+    private_constant :VALID
+
+    # These options may appear in the CSV file before the header row.
+    # They get converted to a normalized option key value pair.
+    CSV_NAMES = {
+      first_match: [:first_match, true], accumulate: [:first_match, false],
+      regexp_implicit: [:regexp_implicit, true],
+      text_only: [:text_only, true], string_search: [:text_only, true]
+    }.freeze
+    private_constant :CSV_NAMES
+
+    # Validate options and supply default values for any options not explicitly set.
+    #
+    # @param options [Hash] Input options hash supplied by the user.
+    # @return [Hash] Options hash filled in with all required values, defaulted if necessary.
+    # @raise [CellValidationError] For invalid option keys.
+    def self.normalize(options)
+      validate(options)
+      default(options)
+    end
+
+    # Read any options supplied in the CSV file placed before the header row.
+    #
+    # @param rows [Array<Array<String>>] Table data rows.
+    # @param options [Hash] Input options hash built so far.
+    # @return [Hash] Options hash overridden with any values found in the CSV file.
+    def self.from_csv(rows:, options:)
+      row = rows.first
+      return options if row.nil?
+
+      # Have we hit the header row?
+      return options if Header.row?(row)
+
+      # Scan each cell looking for valid option values
+      options = scan_cells(row: row, options: options)
+
+      rows.shift
+      from_csv(rows: rows, options: options)
+    end
+
+    def self.scan_cells(row:, options:)
+      # Scan each cell looking for valid option values
+      row.each do |cell|
+        next if cell == ''
+
+        key, value = option?(cell)
+        options[key] = value if key
+      end
+
+      options
+    end
+    private_class_method :scan_cells
+
+    def self.default(options)
+      result = options.dup
+
+      # The user may override the list of matchers to be used
+      result[:matchers] = matchers(result)
+
+      # Supply any missing options with default values
+      VALID.each_pair do |key, value|
+        next if result.key?(key)
+        result[key] = value
+      end
+
+      result
+    end
+    private_class_method :default
+
+    def self.matchers(options)
+      return [] if options.key?(:matchers) && !options[:matchers]
+      return [] if options[:text_only]
+      return DEFAULT_MATCHERS unless options.key?(:matchers)
+
+      options[:matchers]
+    end
+    private_class_method :matchers
+
+    def self.option?(cell)
+      key = cell.strip.downcase.to_sym
+
+      CSV_NAMES[key]
+    end
+    private_class_method :option?
+
+    def self.validate(options)
+      invalid_options = options.keys - VALID.keys
+
+      return if invalid_options.empty?
+
+      raise CellValidationError, "invalid option(s) supplied: #{invalid_options.inspect}"
+    end
+    private_class_method :validate
+  end
+end

data/lib/csv_decision/parse.rb

@@ -0,0 +1,165 @@
+# 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
+  # All CSVDecision specific errors
+  class Error < StandardError; end
+
+  # Error validating a cell when parsing input table data.
+  class TableValidationError < Error; end
+
+  # Error validating a cell when parsing input table cell data.
+  class CellValidationError < Error; end
+
+  # Table parsing error message enhanced to include the file being processed.
+  class FileError < Error; end
+
+  # Builds a decision table from the input data - which may either be a file, CSV string
+  # or an array of arrays.
+  #
+  # @example Simple Example
+  #   If you have cloned the gem's git repo, then you can run:
+  #   table = CSVDecision.parse(Pathname('spec/data/valid/simple_example.csv'))
+  #     #=> CSVDecision::Table
+  #   table.decide(topic: 'finance', region: 'Europe') #=> team_member: 'Donald'
+  #
+  # @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.
+  #
+  # @option options [Boolean] :first_match Stop scanning after finding the first row match.
+  # @option options [Boolean] :regexp_implicit Make regular expressions implicit rather than
+  #   requiring the comparator =~. (Use with care.)
+  # @option options [Boolean] :text_only All cells treated as simple strings by turning off all
+  #   special matchers.
+  # @option options [Array<Matchers::Matcher>] :matchers May be used to control the inclusion and
+  #   ordering of special matchers. (Advanced feature, use with care.)
+  #
+  # @return [CSVDecision::Table] Resulting decision table.
+  #
+  # @raise [CSVDecision::CellValidationError] Table parsing cell validation error.
+  # @raise [CSVDecision::FileError] Table parsing error for a named CSV file.
+  #
+  def self.parse(data, options = {})
+    Parse.table(data: data, options: Options.normalize(options))
+  end
+
+  # Methods to parse the decision table and return CSVDecision::Table object.
+  # @api private
+  module Parse
+    # Parse the CSV file or input data and create a new decision table object.
+    #
+    # @param (see CSVDecision.parse)
+    # @return (see CSVDecision.parse)
+    def self.table(data:, options:)
+      table = CSVDecision::Table.new
+
+      # In most cases the decision table will be loaded from a CSV file.
+      table.file = data if Data.input_file?(data)
+
+      parse_table(table: table, input: data, options: options)
+
+      # The table object is now immutable.
+      table.columns.freeze
+      table.freeze
+    rescue CSVDecision::Error => exp
+      raise_error(file: table.file, exception: exp)
+    end
+
+    def self.raise_error(file:, exception:)
+      raise exception unless file
+
+      raise CSVDecision::FileError,
+            "error processing CSV file #{file}\n#{exception.inspect}"
+    end
+    private_class_method :raise_error
+
+    def self.parse_table(table:, input:, options:)
+      # Parse input data into an array of arrays.
+      table.rows = Data.to_array(data: input)
+
+      # Pick up any options specified in the CSV file before the header row.
+      # These override any options passed as parameters to the parse method.
+      table.options = Options.from_csv(rows: table.rows, options: options).freeze
+
+      # Parse table header and data rows with special cell matchers.
+      parse_with_matchers(table: table, matchers: CSVDecision::Matchers.new(options))
+
+      # 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
+
+    def self.parse_with_matchers(table:, matchers:)
+      # Parse the header row
+      table.columns = Header.parse(table: table, matchers: matchers)
+
+      # Parse the table's the data rows.
+      parse_data(table: table, matchers: matchers)
+    end
+    private_class_method :parse_with_matchers
+
+    def self.parse_data(table:, matchers:)
+      table.rows.each_with_index do |row, index|
+        # Mutate the row if we find anything other than a simple string constant in its
+        # data cells.
+        row = parse_row(table: table, matchers: matchers, row: row, index: index)
+
+        # Does the row have any output functions?
+        outs_functions(table: table, index: index)
+
+        # No more mutations required for this row.
+        row.freeze
+      end
+    end
+    private_class_method :parse_data
+
+    def self.parse_row(table:, matchers:, row:, index:)
+      # Parse the input cells for this row
+      row = parse_row_ins(table: table, matchers: matchers, row: row, index: index)
+
+      # Parse the output cells for this row
+      parse_row_outs(table: table, matchers: matchers, row: row, index: index)
+    end
+    private_class_method :parse_row
+
+    def self.parse_row_ins(table:, matchers:, row:, index:)
+      # Parse the input cells for this row
+      row, table.scan_rows[index] = matchers.parse_ins(columns: table.columns.ins, row: row)
+
+      # Add any symbol references made by input cell procs to the column dictionary
+      Columns.ins_dictionary(columns: table.columns.dictionary, row: row)
+
+      row
+    end
+    private_class_method :parse_row_ins
+
+    def self.parse_row_outs(table:, matchers:, row:, index:)
+      # Parse the output cells for this row
+      row, table.outs_rows[index] = matchers.parse_outs(columns: table.columns.outs, row: row)
+
+      Columns.outs_dictionary(columns: table.columns, row: row)
+
+      row
+    end
+    private_class_method :parse_row_outs
+
+    def self.outs_functions(table:, index:)
+      return if table.outs_rows[index].procs.empty?
+
+      # Set this flag as the table has output functions
+      table.outs_functions = true
+
+      # Update the output columns that contain functions needing evaluation.
+      table.outs_rows[index].procs.each { |col| table.columns.outs[col].eval = true }
+    end
+    private_class_method :outs_functions
+  end
+end

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