csv_decision 0.0.1 → 0.0.2

data/lib/csv_decision/input.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'ice_nine'
+require 'ice_nine/core_ext/object'
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Parse the input hash
+  module Input
+    def self.parse(table:, input:, symbolize_keys:)
+      validate(input)
+
+      # For safety the default is to symbolize keys and make a copy of the hash.
+      # However, if this is turned off assume keys are symbolized
+      # TODO: Is it OK to mutate the hash in this case?
+      input = symbolize_keys ? input.deep_symbolize_keys : input
+
+      parsed_input = parse_input(table: table, input: input)
+
+      parsed_input[:hash].freeze if symbolize_keys
+
+      parsed_input
+    end
+
+    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_input(table:, input:)
+      scan_cols = {}
+
+      # Does this table have any defaulted columns?
+      # defaulted_columns = table.columns[:defaults]
+
+      table.columns.ins.each_pair do |col, column|
+        value = input[column.name]
+
+        scan_cols[col] = value
+      end
+
+      { hash: input, scan_cols: scan_cols }
+    end
+    private_class_method :parse_input
+  end
+end

data/lib/csv_decision/load.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Load all the CSV files located in the designated folder path.
+  #
+  # @param path [Pathname] - directiory containing CSV files
+  # @param options [Hash] - supplied options hash for table creation
+  # @return [Hash<CSVDecision::Table>]
+  def self.load(path, options = {})
+    Load.path(path: path, options: options)
+  end
+
+  # Load all CSV files located in the specified folder.
+  module 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.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'values'
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Value object for a cell proc
+  Proc = Value.new(:type, :function)
+
+  # Value object for a data row indicating which columns are constants versus procs.
+  # ScanRow = Struct.new(:constants, :procs) do
+  #   def scan_columns(columns:, matchers:, row:)
+  #     columns.each_pair do |col, column|
+  #       # Empty cell matches everything, and so never needs to be scanned
+  #       next if row[col] == ''
+  #
+  #       # If the column is text only then no special matchers need be invoked
+  #       next constants << col if column.text_only
+  #
+  #       # Need to scan the cell against all matchers
+  #       row[col] = scan_cell(col: col, matchers: matchers, cell: row[col])
+  #     end
+  #   end
+  #
+  #   def match_constants?(row:, scan_cols:)
+  #     constants.each do |col|
+  #       value = scan_cols.fetch(col, [])
+  #       # This only happens if the column is indexed
+  #       next if value == []
+  #       return false unless row[col] == value
+  #     end
+  #
+  #     true
+  #   end
+  #
+  #   def match_procs?(row:, input:)
+  #     hash = input[:hash]
+  #     scan_cols = input[:scan_cols]
+  #
+  #     procs.each do |col|
+  #       return false unless Decide.eval_matcher(proc: row[col],
+  #                                               value: scan_cols[col],
+  #                                               hash: hash)
+  #     end
+  #
+  #     true
+  #   end
+  #
+  #   private
+  #
+  #   def scan_cell(col:, matchers:, cell:)
+  #     # Scan the cell against all the matchers
+  #     proc = Matchers.scan(matchers: matchers, cell: cell)
+  #
+  #     if proc
+  #       procs << col
+  #       return proc
+  #     end
+  #
+  #     constants << col
+  #     cell
+  #   end
+  # end
+
+  # Methods to assign a matcher to data cells
+  module Matchers
+    # Negation sign for ranges and functions
+    NEGATE = '!'
+
+    # All regular expressions used for matching are anchored
+    #
+    # @param value [String]
+    # @return [Regexp]
+    def self.regexp(value)
+      Regexp.new("\\A(#{value})\\z").freeze
+    end
+
+    # Regular expression used to recognise a numeric string with or without a decimal point.
+    NUMERIC = '[-+]?\d*(?<decimal>\.?)\d+'
+    NUMERIC_RE = regexp(NUMERIC)
+
+    # Validate a numeric value and convert it to an Integer or BigDecimal if a valid 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
+
+    # Validate a numeric string and convert it to an Integer or BigDecimal.
+    #
+    # @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.new(value.chomp('.'))
+    end
+
+    # Parse the supplied input columns for the row supplied using an array of matchers.
+    #
+    # @param columns [Hash] - Input columns hash
+    # @param matchers [Array]
+    # @param row [Array]
+    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_columns(columns: columns, matchers: matchers, row: row, scan_row: scan_row)
+      scan_row.scan_columns(columns: columns, matchers: matchers, row: row)
+
+      scan_row
+    end
+
+    def self.scan(matchers:, cell:)
+      matchers.each do |matcher|
+        proc = matcher.matches?(cell)
+        return proc if proc
+      end
+
+      # Must be a simple constant
+      false
+    end
+  end
+end

data/lib/csv_decision/matchers/numeric.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Methods to assign a matcher to data cells
+  module Matchers
+    # Match cell against a Ruby-like numeric comparison
+    class Numeric
+      # Range types are .. or ...
+      COMPARISON = /\A(?<comparator><=|>=|<|>|!=)\s*(?<value>\S.*)\z/
+
+      COMPARATORS = {
+        '>'  => proc { |numeric_cell, value| Matchers.numeric(value) &.>  numeric_cell },
+        '>=' => proc { |numeric_cell, value| Matchers.numeric(value) &.>= numeric_cell },
+        '<'  => proc { |numeric_cell, value| Matchers.numeric(value) &.<  numeric_cell },
+        '<=' => proc { |numeric_cell, value| Matchers.numeric(value) &.<= numeric_cell },
+        '!=' => proc { |numeric_cell, value| Matchers.numeric(value) &.!= numeric_cell }
+      }.freeze
+
+      def matches?(cell)
+        match = COMPARISON.match(cell)
+        return false unless match
+
+        numeric_cell = Matchers.numeric(match['value'])
+        return false unless numeric_cell
+
+        Proc.with(type: :proc,
+                  function: COMPARATORS[match['comparator']].curry[numeric_cell])
+      end
+
+      # This matcher does not need access to the options hash
+      def initialize(_options = nil); end
+    end
+  end
+end

data/lib/csv_decision/matchers/pattern.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Methods to assign a matcher to data cells
+  module Matchers
+    # Match cell against a regular expression pattern
+    class Pattern
+      EXPLICIT_COMPARISON = /\A(?<comparator>=~|!~|!=)\s*(?<value>\S.*)\z/
+      IMPLICIT_COMPARISON = /\A(?<comparator>=~|!~|!=)?\s*(?<value>\S.*)\z/
+
+      # rubocop: disable Style/DoubleNegation
+      PATTERN_LAMBDAS = {
+        '!=' => proc { |pattern, value|   pattern != value }.freeze,
+        '=~' => proc { |pattern, value| !!pattern.match(value) }.freeze,
+        '!~' => proc { |pattern, value|  !pattern.match(value) }.freeze
+      }.freeze
+      # rubocop: enable Style/DoubleNegation
+
+      def self.regexp?(cell:, explicit:)
+        # By default a regexp pattern must use an explicit comparator
+        match = explicit ? EXPLICIT_COMPARISON.match(cell) : IMPLICIT_COMPARISON.match(cell)
+        return false if match.nil?
+
+        comparator = match['comparator']
+
+        # Comparator may be omitted if the regexp_explicit option is off.
+        return false if explicit && comparator.nil?
+
+        parse(comparator: comparator, value: match['value'])
+      end
+
+      def self.parse(comparator:, value:)
+        return false if value.blank?
+
+        # We cannot do a regexp comparison against a symbol name.
+        # (Maybe we should add this feature?)
+        return if value[0] == ':'
+
+        # If no comparator then the implicit option must be on
+        comparator = regexp_implicit(value) if comparator.nil?
+
+        [comparator, value]
+      end
+
+      def self.regexp_implicit(value)
+        # rubocop: disable Style/CaseEquality
+        return unless /\W/ === value
+        # rubocop: enable Style/CaseEquality
+
+        # Make the implict comparator explict
+        '=~'
+      end
+
+      def initialize(options = {})
+        # By default regexp's must have an explicit comparator
+        @regexp_explicit = !options[:regexp_implicit]
+      end
+
+      def matches?(cell)
+        comparator, value = Pattern.regexp?(cell: cell, explicit: @regexp_explicit)
+
+        # We could not find a regexp pattern - maybe it's a simple string or something else?
+        return false unless comparator
+
+        # No need for a regular expression if we have simple string inequality
+        pattern = comparator == '!=' ? value : Matchers.regexp(value)
+
+        Proc.with(type: :proc,
+                  function: PATTERN_LAMBDAS[comparator].curry[pattern].freeze)
+      end
+    end
+  end
+end

data/lib/csv_decision/matchers/range.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# CSV Decision: CSV based Ruby decision tables.
+# Created December 2017 by Brett Vickers
+# See LICENSE and README.md for details.
+module CSVDecision
+  # Methods to assign a matcher to data cells
+  module Matchers
+    # Match cell against a Ruby-like range
+    class Range
+      # Range types are .. or ...
+      TYPE = '(\.\.\.|\.\.)'
+
+      def self.range_re(value)
+        Matchers.regexp(
+          "(?<negate>#{NEGATE}?)\\s*(?<min>#{value})(?<type>#{TYPE})(?<max>#{value})"
+        )
+      end
+      private_class_method :range_re
+
+      NUMERIC_RANGE = range_re(Matchers::NUMERIC)
+
+      # One or more alphanumeric characters
+      ALNUM = '[[:alnum:]][[:alnum:]]*'
+      ALNUM_RANGE = range_re(ALNUM)
+
+      def self.convert(value, method)
+        method ? Matchers.send(method, value) : value
+      end
+      private_class_method :convert
+
+      def self.range(match, coerce: nil)
+        negate = match['negate'] == Matchers::NEGATE
+        min = convert(match['min'], coerce)
+        type = match['type']
+        max = convert(match['max'], coerce)
+
+        [negate, type == '...' ? min...max : min..max]
+      end
+
+      def self.numeric_range(negate, range)
+        return ->(value) { range.include?(Matchers.numeric(value)) } unless negate
+        ->(value) { !range.include?(Matchers.numeric(value)) }
+      end
+      private_class_method :numeric_range
+
+      def self.alnum_range(negate, range)
+        return ->(value) { range.include?(value) } unless negate
+        ->(value) { !range.include?(value) }
+      end
+      private_class_method :alnum_range
+
+      def self.proc(match:, coerce: nil)
+        negate, range = range(match, coerce: coerce)
+        method = coerce ? :numeric_range : :alnum_range
+        function = Range.send(method, negate, range).freeze
+        Proc.with(type: :proc, function: function)
+      end
+
+      def matches?(cell)
+        if (match = NUMERIC_RANGE.match(cell))
+          return Range.proc(match: match, coerce: :to_numeric)
+        end
+
+        if (match = ALNUM_RANGE.match(cell))
+          return Range.proc(match: match)
+        end
+
+        false
+      end
+
+      # This matcher does not need access to the options hash
+      def initialize(_options = nil); end
+    end
+  end
+end

data/lib/csv_decision/options.rb

@@ -4,82 +4,112 @@
 # Created December 2017 by Brett Vickers
 # See LICENSE and README.md for details.
 module CSVDecision
-  VALID_OPTIONS = %i[
-    force_encoding
-    ascii_only?
-    first_match
-    regexp_implict
-    text_only
-    index
-    tables
+  # Specialized cell value matchers beyond simple string compares.
+  # By default all these matchers are tried in the specified order.
+  DEFAULT_MATCHERS = [
+    Matchers::Range,
+    Matchers::Numeric,
+    Matchers::Pattern
   ].freeze
 
-  OPTION_DEFAULTS = {
-    force_encoding: 'UTF-8',
-    ascii_only?: true,
+  # All valid options with their default values.
+  VALID_OPTIONS = {
     first_match: true,
-    regexp_implict: false,
-    text_only: false
+    regexp_implicit: false,
+    text_only: false,
+    matchers: DEFAULT_MATCHERS
   }.freeze
 
-  CSV_OPTION_NAMES = %i[first_match accumulate regexp_implict text_only].freeze
+  # These options may appear in the CSV file before the header row.
+  # Convert them to a normalized option key value pair.
+  CSV_OPTION_NAMES = {
+    first_match: [:first_match, true],
+    accumulate: [:first_match, false],
+    regexp_implicit: [:regexp_implicit, true],
+    text_only: [:text_only, true]
+  }.freeze
 
-  # Parse the CSV file and create a new decision table object
-  class Options
-    def self.default(options)
-      result = options.deep_dup
+  # Validate and normalize the options hash supplied.
+  module Options
+    # Validate options and supply default values for any options not explicitly set.
+    #
+    # @param options [Hash] - input options hash supplied
+    # @return [Hash] - options hash filled in with all required default values
+    def self.normalize(options)
+      validate(options)
+      default(options)
+    end
 
-      # Default any missing options that have defaults defined
-      OPTION_DEFAULTS.each_pair do |key, value|
-        next if result.key?(key)
-        result[key] = value
-      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 option values in the CSV file
+    def self.from_csv(rows:, options:)
+      row = rows.first
+      return options if row.nil?
 
-      result
-    end
+      # Have we hit the header row?
+      return options if Header.row?(row)
 
-    def self.cell?(cell)
-      return false if cell == ''
+      # Scan each cell looking for valid option values
+      options = scan_cells(row: row, options: options)
 
-      key = cell.downcase.to_sym
-      return [key, true] if CSV_OPTION_NAMES.include?(key)
+      rows.shift
+      from_csv(rows: rows, options: options)
     end
 
-    def self.valid?(options)
-      invalid_options = options.keys - VALID_OPTIONS
+    def self.scan_cells(row:, options:)
+      # Scan each cell looking for valid option values
+      row.each do |cell|
+        next if cell == ''
 
-      return true if invalid_options.empty?
+        key, value = option?(cell)
+        options[key] = value if key
+      end
 
-      raise ArgumentError, "invalid option(s) supplied: #{invalid_options.inspect}"
+      options
     end
+    private_class_method :scan_cells
 
-    def self.from_csv(table, attributes)
-      row = table.rows.first
-      return attributes unless row
+    def self.default(options)
+      result = options.dup
 
-      return attributes if Header.row?(row)
+      # The user may override the list of matchers to be used
+      result[:matchers] = matchers(result)
 
-      row.each do |cell|
-        key, value = Options.cell?(cell)
-        attributes[key] = value if key
+      # Supply any missing options with default values
+      VALID_OPTIONS.each_pair do |key, value|
+        next if result.key?(key)
+        result[key] = value
       end
 
-      table.rows.shift
-      from_csv(table, attributes)
+      result
     end
+    private_class_method :default
 
-    attr_accessor :attributes
+    def self.matchers(options)
+      return [] if options.key?(:matchers) && !options[:matchers]
+      return [] if options[:text_only]
+      return DEFAULT_MATCHERS unless options.key?(:matchers)
 
-    def initialize(options)
-      Options.valid?(options)
-      @attributes = Options.default(options)
+      options[:matchers]
     end
+    private_class_method :matchers
 
-    def from_csv(table)
-      # Options on the CSV file override the ones passed in to the method
-      @attributes = Options.from_csv(table, @attributes)
+    def self.option?(cell)
+      key = cell.downcase.to_sym
+      return CSV_OPTION_NAMES[key] if CSV_OPTION_NAMES.key?(key)
+    end
+    private_class_method :option?
+
+    def self.validate(options)
+      invalid_options = options.keys - VALID_OPTIONS.keys
 
-      self
+      return if invalid_options.empty?
+
+      raise ArgumentError, "invalid option(s) supplied: #{invalid_options.inspect}"
     end
+    private_class_method :validate
   end
 end