csv_decision 0.1.0 → 0.2.0

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jan  6 20:03:01 2018 by
+  Generated on Sat Jan 13 10:02:46 2018 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.12 (ruby-2.4.0).
 </div>

data/lib/csv_decision/columns.rb

@@ -8,12 +8,12 @@ module CSVDecision
   # Dictionary of all this table's columns - inputs, outputs etc.
   # @api private
   class Columns
-    # TODO: Value object used for any columns with defaults
-    # Default = Struct.new(:name, :function, :default_if)
-
-    # Dictionary of all data columns.
+    # Dictionary of all table data columns.
     # The key of each hash is the header cell's array column index.
-    # Note that input and output columns can be interspersed and need not have unique names.
+    # Note that input and output columns may be interspersed, and multiple input columns
+    # may refer to the same input hash key symbol.
+    # However, output columns must have unique symbols, which cannot overlap with input
+    # column symbols.
     class Dictionary
       # @return [Hash{Integer=>Entry}] All column names.
       attr_accessor :columns
@@ -21,28 +21,42 @@ module CSVDecision
       # @return [Hash{Integer=>Entry}] All input column dictionary entries.
       attr_accessor :ins
 
+      # @return [Hash{Integer=>Entry}] All defaulted input column dictionary
+      #  entries. This is actually just a subset of :ins.
+      attr_accessor :defaults
+
       # @return [Hash{Integer=>Entry}] All output column dictionary entries.
       attr_accessor :outs
 
       # @return [Hash{Integer=>Entry}] All if: column dictionary entries.
+      #   This is actually just a subset of :outs.
       attr_accessor :ifs
 
-      # TODO: Input hash path - optional (planned feature)
-      # attr_accessor :path
-
-      # TODO: Input columns with a default value (planned feature)
-      # attr_accessor :defaults
-
       def initialize
         @columns = {}
+        @defaults = {}
         @ifs = {}
         @ins = {}
         @outs = {}
-        # TODO: @path = {}
-        # TODO: @defaults = {}
       end
     end
 
+    # Input columns with defaults specified
+    def defaults
+      @dictionary&.defaults
+    end
+
+    # Set defaults for columns with defaults specified
+    def defaults=(value)
+      @dictionary.defaults = value
+    end
+
+    # @return [Hash{Symbol=>[false, Integer]}] Dictionary of all
+    #   input and output column names.
+    def dictionary
+      @dictionary.columns
+    end
+
     # Input columns hash keyed by column index.
     # @return [Hash{Index=>Entry}]
     def ins
@@ -61,24 +75,11 @@ module CSVDecision
       @dictionary.ifs
     end
 
-    def dictionary
-      @dictionary.columns
-    end
-
+    # @return [Array<Symbol>] All input column symbols.
     def input_keys
       @dictionary.columns.select { |_k, v| v == :in }.keys
     end
 
-    # Input columns with defaults specified (planned feature)
-    # def defaults
-    #   @dictionary.defaults
-    # end
-
-    # Input hash path (planned feature)
-    # def path
-    #   @dictionary.path
-    # end
-
     # @param table [Table] Decision table being constructed.
     def initialize(table)
       # If a column does not have a valid header cell, then it's empty of data.

data/lib/csv_decision/defaults.rb

@@ -0,0 +1,47 @@
+# 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
+  # Parse the default row beneath the header row if present
+  # @api private
+  module Defaults
+    # Parse the defaults row that (optionally) appears just after the header row.
+    # We have already determined that this row must be present.
+    # @param columns [{Integer=>Dictionary::Entry}] Hash of header columns with defaults.
+    # @param matchers [Array<Matchers>] Output cell special matchers.
+    # @param row [Array<String>] Defaults row that appears just after the header row.
+    # @raise [TableValidationError] Missing defaults row.
+    def self.parse(columns:, matchers:, row:)
+      raise TableValidationError, 'Missing defaults row' if row.nil?
+
+      defaults = columns.defaults
+
+      # Scan the default row for procs and constants
+      scan_row = ScanRow.new.scan_columns(row: row, columns: defaults, matchers: matchers)
+
+      parse_columns(defaults: defaults, columns: columns.dictionary, row: scan_row)
+    end
+
+    def self.parse_columns(defaults:, columns:, row:)
+      defaults.each_pair do |col, entry|
+        parse_cell(cell: row[col], columns: columns, entry: entry)
+      end
+
+      defaults
+    end
+    private_class_method :parse_columns
+
+    def self.parse_cell(cell:, columns:, entry:)
+      return entry.function = cell unless cell.is_a?(Matchers::Proc)
+
+      entry.function = cell.function
+
+      # Add any referenced input column symbols to the column name dictionary
+      Parse.ins_cell_dictionary(columns: columns, cell: cell)
+    end
+    private_class_method :parse_cell
+  end
+end

data/lib/csv_decision/dictionary.rb

@@ -8,27 +8,86 @@ module CSVDecision
   # Parse the CSV file's header row. These methods are only required at table load time.
   # @api private
   module Dictionary
-    # Table used to build a column dictionary entry.
-    ENTRY = {
-      in:         { type: :in,    eval: nil },
-      'in/text':  { type: :in,    eval: false },
-      out:        { type: :out,   eval: nil },
-      'out/text': { type: :out,   eval: false },
-      guard:      { type: :guard, eval: true },
-      if:         { type: :if,    eval: true }
-    }.freeze
-    private_constant :ENTRY
-
-    # Value object to hold column dictionary entries.
-    Entry = Struct.new(:name, :eval, :type) do
+    # 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 }
+      }.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 +ENTRY+ 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], type: entry[:type], set_if: entry[:set_if])
+      end
+
+      # @return [Boolean] Return true is this is an input column, false otherwise.
       def ins?
-        %i[in guard].member?(type) ? true : false
+        @ins
+      end
+
+      # @return [Symbol] Column name.
+      attr_reader :name
+
+      # @return [Symbol] Column type.
+      attr_reader :type
+
+      # @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)
+      def initialize(name:, type:, eval: nil, set_if: nil)
+        @name = name
+        @type = type
+        @eval = eval
+        @set_if = set_if
+        @function = nil
+        @ins = INS_TYPES.member?(type)
       end
-    end
 
-    # These column types do not need a name.
-    COLUMN_TYPE_ANONYMOUS = Set.new(%i[guard if]).freeze
-    private_constant :COLUMN_TYPE_ANONYMOUS
+      # 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.
@@ -48,127 +107,60 @@ module CSVDecision
     # @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 [{Symbol=>Symbol}] Column dictionary updated with the new name.
+    # @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)
+      Validate.name(columns: columns, name: name, out: out)
 
       columns[name] = out ? out : :in
       columns
     end
 
-    def self.validate_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
-    private_class_method :validate_column
-
-    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_RE.match(column_name)
-      raise CellValidationError, "column name '#{name}' contains invalid characters"
-    end
-    private_class_method :format_column_name
-
-    # Returns the normalized column type, along with an indication if
-    # the column requires evaluation
-    def self.column_type(column_name, entry)
-      Entry.new(column_name, entry[:eval], entry[:type])
-    end
-    private_class_method :column_type
-
     def self.parse_cell(cell:, index:, dictionary:)
-      column_type, column_name = validate_column(cell: cell, index: index)
-
-      entry = column_type(column_name, ENTRY[column_type])
+      column_type, column_name = Validate.column(cell: cell, index: index)
 
-      dictionary_entry(dictionary: dictionary, entry: entry, 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
-      # Header column that has a function for setting the value (planned feature)
-      # when :set, :'set/nil?', :'set/blank?'
-      #   # Default function will set the input value unconditionally or conditionally
-      #   dictionary.defaults[index] =
-      #     Columns::Default.new(entry.name, nil, default_if(type))
-      #
-      #   # Treat set: as an in: column
-      #   dictionary.ins[index] = entry
-
-      when :in
-        add_name(columns: dictionary.columns, name: entry.name)
-        dictionary.ins[index] = entry
-
       # A guard column is still added to the ins hash for parsing as an input column.
-      when :guard
-        dictionary.ins[index] = entry
+      when :in, :guard, :set
+        input_entry(dictionary: dictionary, entry: entry, index: index)
 
-      when :out
-        add_name(columns: dictionary.columns, name: entry.name, out: index)
-        dictionary.outs[index] = entry
-
-      # Add an if: column to both the +outs+ hash for output column parsing, and also
-      # a specialized +ifs+ hash used for evaluating them for row filtering.
-      when :if
-        dictionary.outs[index] = entry
-        dictionary.ifs[index] = entry
+      when :out, :if
+        output_entry(dictionary: dictionary, entry: entry, index: index)
       end
 
       dictionary
     end
     private_class_method :dictionary_entry
 
-    def self.validate_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
-    private_class_method :validate_name
+    def self.output_entry(dictionary:, entry:, index:)
+      case entry.type
+      # if: columns are anonymous
+      when :if
+        dictionary.ifs[index] = entry
 
-    def self.validate_out_name(in_out:, name:)
-      if in_out == :in
-        raise CellValidationError, "output column name '#{name}' is also an input column"
+      when :out
+        add_name(columns: dictionary.columns, name: entry.name, out: index)
       end
 
-      raise CellValidationError, "output column name '#{name}' is duplicated"
+      dictionary.outs[index] = entry
     end
-    private_class_method :validate_out_name
+    private_class_method :output_entry
+
+    def self.input_entry(dictionary:, entry:, index:)
+      dictionary.ins[index] = entry
 
-    def self.validate_in_name(in_out:, name:)
-      # in: columns may be duped
-      return if in_out == :in
+      # Default function will set the input value unconditionally or conditionally.
+      dictionary.defaults[index] = entry if entry.type == :set
 
-      raise CellValidationError, "output column name '#{name}' is also an input column"
+      # guard: columns are anonymous
+      add_name(columns: dictionary.columns, name: entry.name) unless entry.type == :guard
     end
-    private_class_method :validate_in_name
-
-    # def self.default_if(type)
-    #   return nil if type == :set
-    #   return :nil? if type == :'set/nil'
-    #   :blank?
-    # end
-    # private_class_method :default_if
+    private_class_method :input_entry
   end
 end

data/lib/csv_decision/header.rb

@@ -8,15 +8,9 @@ module CSVDecision
   # Parse the CSV file's header row. These methods are only required at table load time.
   # @api private
   module Header
-    # TODO: implement all column types
-    # COLUMN_TYPE = %r{
-    #   \A(?<type>in|out|in/text|out/text|set|set/nil|set/blank|path|guard|if)
-    #   \s*:\s*(?<name>\S?.*)\z
-    # }xi
-
     # Column types recognised in the header row.
     COLUMN_TYPE = %r{
-      \A(?<type>in|out|in/text|out/text|guard|if)
+      \A(?<type>in/text|in|out/text|out|guard|if|set/nil\?|set/blank\?|set)
       \s*:\s*(?<name>\S?.*)\z
     }xi
 
@@ -27,20 +21,29 @@ module CSVDecision
 
     # 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| cell.match(COLUMN_TYPE) }
+      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.
+    # @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

data/lib/csv_decision/input.rb

@@ -43,19 +43,67 @@ module CSVDecision
     private_class_method :validate
 
     def self.parse_input(table:, input:)
+      defaulted_columns = table.columns.defaults
+      parse_cells(table: table, input: input) if defaulted_columns.empty?
+
+      parse_defaulted(table: table, input: input, defaulted_columns: defaulted_columns)
+    end
+    private_class_method :parse_input
+
+    def self.parse_cells(table:, input:)
       scan_cols = {}
+      table.columns.ins.each_pair do |col, column|
+        next if column.type == :guard
 
-      # TODO: Does this table have any defaulted columns?
-      # defaulted_columns = table.columns[:defaults]
+        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|
-        value = input[column.name]
+        next if column.type == :guard
 
-        scan_cols[col] = value
+        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_input
+    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/matchers/constant.rb

@@ -61,8 +61,7 @@ module CSVDecision
       # If a constant expression returns a Proc of type :constant,
       #   otherwise return false.
       #
-      # @param (see Matcher#matches?)
-      # @return (see Matcher#matches?)
+      # (see Matcher#matches?)
       def matches?(cell)
         Matchers::Constant.matches?(cell)
       end

data/lib/csv_decision/matchers/guard.rb

@@ -48,8 +48,9 @@ module CSVDecision
       end
 
       def self.regexp_match(symbol, value, hash)
-        value.is_a?(String) && hash[symbol].is_a?(String) &&
-          Matchers.regexp(value).match(hash[symbol])
+        return false unless value.is_a?(String)
+        data = hash[symbol]
+        data.is_a?(String) && Matchers.regexp(value).match?(data)
       end
 
       FUNCTION = {

data/lib/csv_decision/matchers/numeric.rb

@@ -8,9 +8,9 @@ module CSVDecision
   # Methods to assign a matcher to data cells.
   # @api private
   class Matchers
-    # Recognise numeric comparison expressions - e.g., +> 100+ or +!= 0+
+    # Recognise numeric comparison expressions - e.g., +> 100+ or +!= 0+.
     class Numeric < Matcher
-      # For example: >= 100 or != 0
+      # For example: +>= 100+ or +!= 0+.
       COMPARISON = /\A(?<comparator><=|>=|<|>|!=)\s*(?<value>\S.*)\z/
       private_constant :COMPARISON
 
@@ -25,8 +25,7 @@ module CSVDecision
       }.freeze
       private_constant :COMPARATORS
 
-      # @param (see Matchers::Matcher#matches?)
-      # @return (see Matchers::Matcher#matches?)
+      # (see Matcher#matches?)
       def self.matches?(cell)
         match = COMPARISON.match(cell)
         return false unless match
@@ -39,8 +38,7 @@ module CSVDecision
                            function: COMPARATORS[comparator].curry[numeric_cell].freeze)
       end
 
-      # @param (see Matchers::Matcher#matches?)
-      # @return (see Matchers::Matcher#matches?)
+      # (see Matcher#matches?)
       def matches?(cell)
         Numeric.matches?(cell)
       end

data/lib/csv_decision/matchers/pattern.rb

@@ -16,14 +16,12 @@ module CSVDecision
       IMPLICIT_COMPARISON = Matchers.regexp("(?<comparator>=~|!~|!=)?\\s*(?<value>\\S.*)")
       private_constant :IMPLICIT_COMPARISON
 
-      # 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
+        '!=' => proc { |pattern, value|  pattern != value }.freeze,
+        '=~' => proc { |pattern, value|  pattern.match?(value) }.freeze,
+        '!~' => proc { |pattern, value| !pattern.match?(value) }.freeze
       }.freeze
       private_constant :PATTERN_LAMBDAS
-      # rubocop: enable Style/DoubleNegation
 
       def self.regexp?(cell:, explicit:)
         # By default a regexp pattern must use an explicit comparator
@@ -79,7 +77,7 @@ module CSVDecision
 
       # @param options [Hash{Symbol=>Object}] Used to determine the value of regexp_implicit:.
       def initialize(options = {})
-        # By default regexp's must have an explicit comparator
+        # By default regexp's must have an explicit comparator.
         @regexp_explicit = !options[:regexp_implicit]
       end
 
@@ -87,8 +85,8 @@ module CSVDecision
       # If the option regexp_implicit: true has been set, then cells may omit the +=~+ comparator
       # so long as they contain non-word characters typically used in regular expressions such as
       # +*+ and +.+.
-      # @param (see Matchers::Matcher#matches?)
-      # @return (see Matchers::Matcher#matches?)
+      # @param (see Matcher#matches?)
+      # @return (see Matcher#matches?)
       def matches?(cell)
         Pattern.matches?(cell, regexp_explicit: @regexp_explicit)
       end

data/lib/csv_decision/matchers/range.rb

@@ -13,8 +13,7 @@ module CSVDecision
     class Range < Matcher
       # Match a table data cell string against a Ruby-like range expression.
       #
-      # @param (see Matcher#matches?)
-      # @return (see Matcher#matches?)
+      # (see Matcher#matches?)
       def self.matches?(cell)
         if (match = NUMERIC_RANGE.match(cell))
           return range_proc(match: match, coerce: :to_numeric)
@@ -87,7 +86,6 @@ module CSVDecision
 
       # Ruby-like range expressions or their negation - e.g., +0...10+ or +!a..z+.
       #
-      # @param (see Matcher#matches?)
       # @return (see Matcher#matches?)
       def matches?(cell)
         Range.matches?(cell)