csv_decision 0.0.3 → 0.0.4

data/lib/csv_decision/matchers/range.rb

@@ -5,11 +5,12 @@
 # See LICENSE and README.md for details.
 module CSVDecision
   # Methods to assign a matcher to data cells
-  module Matchers
+  class Matchers
     # Match cell against a Ruby-like range
     class Range < Matcher
       # Range types are .. or ...
       TYPE = '(\.\.\.|\.\.)'
+      private_constant :TYPE
 
       def self.range_re(value)
         Matchers.regexp(
@@ -19,10 +20,14 @@ module CSVDecision
       private_class_method :range_re
 
       NUMERIC_RANGE = range_re(Matchers::NUMERIC)
+      private_constant :NUMERIC_RANGE
 
       # One or more alphanumeric characters
       ALNUM = '[[:alnum:]][[:alnum:]]*'
+      private_constant :ALNUM
+
       ALNUM_RANGE = range_re(ALNUM)
+      private_constant :ALNUM_RANGE
 
       def self.convert(value, method)
         method ? Matchers.send(method, value) : value
@@ -37,6 +42,7 @@ module CSVDecision
 
         [negate, type == '...' ? min...max : min..max]
       end
+      private_class_method :range
 
       def self.numeric_range(negate, range)
         return ->(value) { range.include?(Matchers.numeric(value)) } unless negate
@@ -50,24 +56,34 @@ module CSVDecision
       end
       private_class_method :alnum_range
 
-      def self.proc(match:, coerce: nil)
+      def self.range_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
+      private_class_method :range_proc
 
-      def matches?(cell)
+      # @param (see Matchers::Matcher#matches?)
+      # @return (see Matchers::Matcher#matches?)
+      def self.matches?(cell)
         if (match = NUMERIC_RANGE.match(cell))
-          return Range.proc(match: match, coerce: :to_numeric)
+          return range_proc(match: match, coerce: :to_numeric)
         end
 
         if (match = ALNUM_RANGE.match(cell))
-          return Range.proc(match: match)
+          return range_proc(match: match)
         end
 
         false
       end
+
+      # Range expression - e.g., +0...10+ or +a..z+
+      # @param (see Matchers::Matcher#matches?)
+      # @return (see Matchers::Matcher#matches?)
+      def matches?(cell)
+        Range.matches?(cell)
+      end
     end
   end
 end

data/lib/csv_decision/matchers/symbol.rb

@@ -0,0 +1,20 @@
+# 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
+  # Recognise expressions in table data cells.
+  class Matchers
+    # Match cell against a
+    #   * cell constant - e.g., := true, = nil
+    #   * symbolic expression - e.g., :column, > :column
+    class Symbol < Matcher
+      # @param (see Matchers::Matcher#matches?)
+      # @return (see Matchers::Matcher#matches?)
+      def matches?(cell)
+        CSVDecision::Symbol.matches?(cell)
+      end
+    end
+  end
+end

data/lib/csv_decision/matchers.rb

@@ -6,63 +6,85 @@ require 'values'
 # Created December 2017 by Brett Vickers
 # See LICENSE and README.md for details.
 module CSVDecision
-  # Value object for a cell proc
+  # Value object for a cell proc.
   Proc = Value.new(:type, :function)
 
-  # Methods to assign a matcher to data cells
-  module Matchers
-    # Negation sign for ranges and functions
+  # Methods to assign a matcher to table data cells.
+  class Matchers
+    # Negation sign prefixed to ranges and functions.
     NEGATE = '!'
 
-    # All regular expressions used for matching are anchored
+    # Cell constants and functions specified by prefixing the value with one of these 3 symbols
+    EQUALS = '==|:=|='
+
+    # All regular expressions used for matching are anchored inside their own
+    # non-capturing group.
     #
-    # @param value [String]
-    # @return [Regexp]
+    # @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
+      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 = '[-+]?\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 [Object] Value from the input hash.
+    # @return [Boolean] Value is an Integer or a BigDecimal.
+    def self.numeric?(value)
+      value.is_a?(Integer) || value.is_a?(BigDecimal)
+    end
+
+    # 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 value if numeric?(value)
       return unless value.is_a?(String)
 
       to_numeric(value)
     end
 
-    # Validate a numeric string and convert it to an Integer or BigDecimal.
+    # Convert a numeric string into an Integer or BigDecimal.
     #
     # @param value [String]
     # @return [nil, Integer, BigDecimal]
     def self.to_numeric(value)
       return unless (match = NUMERIC_RE.match(value))
+      coerce_numeric(match, value)
+    end
+
+    def self.coerce_numeric(match, value)
       return value.to_i if match['decimal'] == ''
-      BigDecimal.new(value.chomp('.'))
+      BigDecimal(value.chomp('.'))
     end
+    private_class_method :coerce_numeric
 
     # 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]
+    # @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_columns(columns: columns, matchers: matchers, row: row, scan_row: scan_row)
-      scan_row.scan_columns(columns: columns, matchers: matchers, row: row)
+      row = scan_row.scan_columns(columns: columns, matchers: matchers, row: row)
 
-      scan_row
+      scan_row.freeze
+
+      [row, scan_row.freeze]
     end
 
+    # Scan the table cell against all matches.
+    #
+    # @param matchers [Array<Matchers::Matcher>]
+    # @param cell [String]
+    # @return [false, Matchers::Proc]
     def self.scan(matchers:, cell:)
       matchers.each do |matcher|
         proc = matcher.matches?(cell)
@@ -73,12 +95,55 @@ module CSVDecision
       false
     end
 
+    def self.ins_matchers(options)
+      options[:matchers].collect { |klass| klass.new(options) }
+    end
+
+    def self.outs_matchers(matchers)
+      matchers.select { |obj| OUTS_MATCHERS.include?(obj.class) }
+    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)
+      @ins = Matchers.ins_matchers(options)
+      @outs = Matchers.outs_matchers(@ins)
+    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
+
     # @abstract Subclass and override {#matches?} to implement
     #   a custom Matcher class.
     class Matcher
       def initialize(_options = nil); end
 
-      def matches?(_cell); 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
     end
   end
 end

data/lib/csv_decision/numeric.rb

@@ -0,0 +1,38 @@
+# 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
+  # Recognise Ruby-like numeric comparison expressions.
+  module Numeric
+    # For example: >= 100 or != 0
+    COMPARISON = /\A(?<comparator><=|>=|<|>|!=)\s*(?<value>\S.*)\z/
+    private_constant :COMPARISON
+
+    # Coerce the input value to a numeric representation before invoking the comparison.
+    # If the coercion fails, it will produce a nil value which always fails to match.
+    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
+    private_constant :COMPARATORS
+
+    # @param (see Matchers::Matcher#matches?)
+    # @return (see Matchers::Matcher#matches?)
+    def self.matches?(cell)
+      match = COMPARISON.match(cell)
+      return false unless match
+
+      numeric_cell = Matchers.to_numeric(match['value'])
+      return false unless numeric_cell
+
+      comparator = match['comparator']
+      Proc.with(type: :proc,
+                function: COMPARATORS[comparator].curry[numeric_cell].freeze)
+    end
+  end
+end

data/lib/csv_decision/options.rb

@@ -10,32 +10,41 @@ module CSVDecision
     Matchers::Range,
     Matchers::Numeric,
     Matchers::Pattern,
-    Matchers::Function
+    Matchers::Constant,
+    Matchers::Symbol
+    # Matchers::Function
   ].freeze
 
-  # All valid options with their default values.
-  VALID_OPTIONS = {
-    first_match: true,
-    regexp_implicit: false,
-    text_only: false,
-    matchers: DEFAULT_MATCHERS
-  }.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
-
-  # Validate and normalize the options hash supplied.
+  # Subset of matchers that apply to output cells
+  OUTS_MATCHERS = [
+    Matchers::Constant
+  # Matchers::Function
+  ].freeze
+
+  # Validate and normalize the options values supplied.
   module Options
+    # All valid CSVDecision::parse options with their default values.
+    VALID = {
+      first_match: true,
+      regexp_implicit: false,
+      text_only: false,
+      matchers: DEFAULT_MATCHERS
+    }.freeze
+
+    # 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]
+    }.freeze
+
     # 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
+    # @param options [Hash] Input options hash supplied by the user.
+    # @return [Hash] Options hash filled in with all required values, defaulted if necessary.
+    # @raise [ArgumentError] For invalid option keys.
     def self.normalize(options)
       validate(options)
       default(options)
@@ -43,9 +52,9 @@ module CSVDecision
 
     # 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
+    # @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?
@@ -80,7 +89,7 @@ module CSVDecision
       result[:matchers] = matchers(result)
 
       # Supply any missing options with default values
-      VALID_OPTIONS.each_pair do |key, value|
+      Options::VALID.each_pair do |key, value|
         next if result.key?(key)
         result[key] = value
       end
@@ -100,12 +109,12 @@ module CSVDecision
 
     def self.option?(cell)
       key = cell.downcase.to_sym
-      return CSV_OPTION_NAMES[key] if CSV_OPTION_NAMES.key?(key)
+      return Options::CSV_NAMES[key] if Options::CSV_NAMES.key?(key)
     end
     private_class_method :option?
 
     def self.validate(options)
-      invalid_options = options.keys - VALID_OPTIONS.keys
+      invalid_options = options.keys - Options::VALID.keys
 
       return if invalid_options.empty?
 

data/lib/csv_decision/parse.rb

@@ -1,50 +1,71 @@
 # frozen_string_literal: true
 
 # CSV Decision: CSV based Ruby decision tables.
-# Created December 2017 by Brett Vickers
+# 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 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 array of arrays.
+  # 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] Options hash supplied by the user.
+  #
+  # @option options [Boolean] :first_match Stop scanning after find 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.
   #
-  # @param data [Pathname, File, Array<Array<String>>, String] - input data given as
-  #   a file, array of arrays or CSV string.
-  # @param options [Hash] - options hash supplied by the user
-  #   * first_match: stop after finding the first match
-  #   * regexp_implicit: Set to make regular expressions implicit rather than requiring
-  #                      the comparator =~
-  #   * text_only:       Set to make all cells be treated as simple strings by turning
-  #                      off all special matchers.
-  #   * matchers         May be used to control the inclusion and ordering of special
-  #                      matchers.
-  # @return [CSVDecision::Table] - resulting decision table
   def self.parse(data, options = {})
-    Parse.table(input: data, options: Options.normalize(options))
+    Parse.table(data: data, options: Options.normalize(options))
   end
 
-  # Parse the CSV file and create a new decision table object.
-  #
-  # (see #parse)
+  # Methods to parse the decision table and return CSVDecision::Table object.
   module Parse
-    def self.table(input:, options:)
+    # 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 = input if Data.input_file?(input)
+      table.file = data if Data.input_file?(data)
+
+      parse_table(table: table, input: data, options: options)
 
-      parse_table(table: table, input: input, options: options)
+      table.freeze
     rescue CSVDecision::Error => exp
       raise_error(file: table.file, exception: exp)
     end
 
     def self.raise_error(file:, exception:)
       raise exception unless file
-      message = "error processing CSV file #{table.file}\n#{exception.inspect}"
-      raise CSVDecision::FileError, message
+
+      raise CSVDecision::FileError,
+            "error processing CSV file #{file}\n#{exception.inspect}"
     end
     private_class_method :raise_error
 
@@ -59,34 +80,20 @@ module CSVDecision
       # Parse the header row
       table.columns = CSVDecision::Columns.new(table)
 
-      parse_data(table: table, matchers: matchers(table.options).freeze)
-
-      table.freeze
+      parse_data(table: table, matchers: Matchers.new(options))
     end
     private_class_method :parse_table
 
     def self.parse_data(table:, matchers:)
       table.rows.each_with_index do |row, index|
-        # Build an array of column indexes requiring simple matches.
-        # and a second array of columns requiring special matchers
-        table.scan_rows[index] = Matchers.parse(columns: table.columns.ins,
-                                                matchers: matchers,
-                                                row: row)
-
-        # parse_outputs(row, index)
+        row, table.scan_rows[index] = matchers.parse_ins(columns: table.columns.ins, row: row)
+        row, table.outs_rows[index] = matchers.parse_outs(columns: table.columns.outs, row: row)
 
         row.freeze
-        table.scan_rows[index].freeze
       end
 
       table.columns.freeze
     end
-
     private_class_method :parse_data
-
-    def self.matchers(options)
-      options[:matchers].collect { |klass| klass.new(options) }
-    end
-    private_class_method :matchers
   end
 end

data/lib/csv_decision/scan_row.rb

@@ -8,26 +8,38 @@ require 'values'
 module CSVDecision
   # Data row object indicating which columns are constants versus procs.
   class ScanRow
-    attr_accessor :constants
-    attr_accessor :procs
+    # @return [Array<Integer>] Column indices for simple constants.
+    attr_reader :constants
+
+    # @return [Array<Integer>] Column indices for Proc objects.
+    attr_reader :procs
 
     def initialize
       @constants = []
       @procs = []
     end
 
-    def scan_columns(columns:, matchers:, row:)
+    # Scan all the specified +columns+ (e.g., inputs) in the given +data+ row using the +matchers+
+    # array supplied.
+    #
+    # @param row [Array<String>] Data row.
+    # @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|
         # Empty cell matches everything, and so never needs to be scanned
         next if (cell = row[col]) == ''
 
         # If the column is text only then no special matchers need be invoked
-        next constants << col if column.text_only
+        next @constants << col if column.text_only
 
         # Need to scan the cell against all matchers, and possibly overwrite
         # the cell contents with a proc.
         row[col] = scan_cell(col: col, matchers: matchers, cell: cell)
       end
+
+      row
     end
 
     def match_constants?(row:, scan_cols:)
@@ -59,18 +71,18 @@ module CSVDecision
       return set(proc, col) if proc
 
       # Just a plain constant
-      constants << col
+      @constants << col
       cell
     end
 
     def set(proc, col)
       # Unbox a constant
       if proc.type == :constant
-        constants << col
+        @constants << col
         return proc.function
       end
 
-      procs << col
+      @procs << col
       proc
     end
   end

data/lib/csv_decision/symbol.rb

@@ -0,0 +1,73 @@
+# 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
+  # Recognise column symbol comparison expressions in input column data cells - e.g., +> :column+ or +!= :column+.
+  module Symbol
+    # Symbol comparison - e.g., > :column or != :column
+    SYMBOL_COMPARE =
+      "(?<comparator>#{Matchers::EQUALS}|!=|<|>|>=|<=)?\\s*:(?<name>#{Header::COLUMN_NAME})"
+    private_constant :SYMBOL_COMPARE
+
+    # Symbol comparision regular expression.
+    SYMBOL_COMPARE_RE = Matchers.regexp(SYMBOL_COMPARE)
+    private_constant :SYMBOL_COMPARE_RE
+
+    # These procs compare one input hash value to another, and so do not coerce numeric values.
+    # Note that we do *not* check +hash.key?(symbol)+, so a +nil+ value will match a missing hash key.
+    EQUALITY = {
+      ':=' => proc { |symbol, value, hash| value == hash[symbol] },
+      '!=' => proc { |symbol, value, hash| value != hash[symbol] }
+    }.freeze
+    private_constant :EQUALITY
+
+    def self.compare_proc(compare)
+      proc { |symbol, value, hash| compare?(lhs: value, compare: compare, rhs: hash[symbol]) }
+    end
+    private_class_method :compare_proc
+
+    COMPARE = {
+      # Equality and inequality - create a lambda proc by calling with the actual column name symbol
+      ':=' => ->(symbol) { EQUALITY[':='].curry[symbol].freeze },
+      '='  => ->(symbol) { EQUALITY[':='].curry[symbol].freeze },
+      '==' => ->(symbol) { EQUALITY[':='].curry[symbol].freeze },
+      '!=' => ->(symbol) { EQUALITY['!='].curry[symbol].freeze },
+
+      # Comparisons - create a lambda proc by calling with the actual column name symbol.
+      '>'  => ->(symbol) { compare_proc(:'>' ).curry[symbol].freeze },
+      '>=' => ->(symbol) { compare_proc(:'>=').curry[symbol].freeze },
+      '<'  => ->(symbol) { compare_proc(:'<' ).curry[symbol].freeze },
+      '<=' => ->(symbol) { compare_proc(:'<=').curry[symbol].freeze },
+    }.freeze
+    private_constant :COMPARE
+
+    def self.compare?(lhs:, compare:, rhs:)
+      # Is the rhs a superclass of lhs, and does rhs respond to the compare method?
+      return lhs.public_send(compare, rhs) if lhs.is_a?(rhs.class) && rhs.respond_to?(compare)
+
+      false
+    end
+    private_class_method :compare?
+
+    # E.g., > :col, we get comparator: >, args: col
+    def self.comparison(comparator:, name:)
+      function = COMPARE[comparator]
+      Proc.with(type: :symbol, function: function[name])
+    end
+    private_class_method :comparison
+
+    # @param (see Matchers::Matcher#matches?)
+    # @return (see Matchers::Matcher#matches?)
+    def self.matches?(cell)
+      match = SYMBOL_COMPARE_RE.match(cell)
+      return false unless match
+
+      comparator = match['comparator'] || '='
+      name = match['name'].to_sym
+
+      comparison(comparator: comparator, name: name)
+    end
+  end
+end