csv_decision 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 076055f3dd0219da9a4d8aa3d0032fd26e320741
-  data.tar.gz: 7ed7716a9f1285b7ed86e3134321e08c829ae7e5
+  metadata.gz: 63aeefecf31a4b0c640e6b345fa1fdcd8af686ab
+  data.tar.gz: 4c1f45f5272e4c565ccd08482beb72e1f8566835
 SHA512:
-  metadata.gz: b87561c15e01daca109a562f68628b15b6f5d33a725ee527a10ad74d79733e5ffe7a8495735d8a41f18a930a4d906312f566a3c5d22fad182b9d94621a7c141d
-  data.tar.gz: be6922a755c26fea0b3d416ee75729bf76eec40a66d386d664aa4e3944be8f311f95d0bdfb004a314da049e2ebe5f0b39987752ccfbe446f01529f7fd62281ba
+  metadata.gz: 0bf8ca1cacd4a5c31198a544c32e4ff0c8138bb9c69771062a91df22ccb4d4e164db7b4134bd21e4be7f857e2909c730a22b6382d21e422c82a030c1641b454c
+  data.tar.gz: 3a54e85c4c8af0859dafcd871a86f143a8cf7f3ae608dda674642c34f5321cee3955fc26910abe496ea7c7912cadf5b26ea378e1bc3b8d884441e42a23139e17

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## v0.0.8, 31 December 2017.
+*Additions*
+- Guard conditions can use `=~` and `!~` for regular expressions.
+
+*Fixes*
+- Bug with column symbol expression not recognising >= and <=.
+
+## v0.0.7, 30 December 2017.
+*Additions*
+- Guard conditions using column symbols and expressions.
+- Guard columns.
+- Symbol functions (0-arity) in output columns.
+- Update YARD documentation.
+
 ## v0.0.6, 26 December 2017.
 *Additions*
 - Update YARD documentation.

data/README.md

@@ -20,16 +20,16 @@ producing a decision as an output hash.
  
 Typical "business logic" is notoriously illogical -- full of corner cases and one-off 
 exceptions. 
-A decision table can capture data-based decisions in a way that comes more naturally 
+A decision table can express data-based decisions in a way that comes more naturally 
 to subject matter experts, who typically prefer spreadsheet models. 
 Business logic may then be encapsulated, avoiding the need to write tortuous 
 conditional expressions in Ruby that draw the ire of `rubocop` and its ilk.
 
 This gem and the examples below take inspiration from 
 [rufus/decision](https://github.com/jmettraux/rufus-decision).
-(However, that gem is no longer maintained and CSV Decision has better 
-decision-time performance for the trade-off of slower table parse times and more memory -- 
-see `benchmarks/rufus_decision.rb`)
+(That gem is no longer maintained and CSV Decision has better 
+decision-time performance, at the expense of slower table parse times and more memory -- 
+see `benchmarks/rufus_decision.rb`.)
  
 ### Installation
  
@@ -68,14 +68,14 @@ When the topic is `finance` and the region is `Europe` the team member `Donald`
 is selected.
 
 This is a "first match" decision table in that as soon as a match is made execution
-stops and a single output value (hash) is returned. 
+stops and a single output row (hash) is returned. 
 
 The ordering of rows matters. `Ernest`, who is in charge of `finance` for the rest of 
 the world, except for `America` and `Europe`, *must* come after his colleagues 
 `Charlie` and `Donald`. `Zach` has been placed last, catching all the input combos
 not matching any other row.
 
-Here it is as code:
+Here is the example as code:
  
  ```ruby
   # Valid CSV string
@@ -94,9 +94,9 @@ Here it is as code:
 
   table = CSVDecision.parse(data)
   
-  table.decide(topic: 'finance', region: 'Europe') # returns team_member: 'Donald'
-  table.decide(topic: 'sports', region: nil) # returns team_member: 'Bob'
-  table.decide(topic: 'culture', region: 'America') # team_member: 'Zach'
+  table.decide(topic: 'finance', region: 'Europe') #=> { team_member: 'Donald' }
+  table.decide(topic: 'sports', region: nil) #=> { team_member: 'Bob' }
+  table.decide(topic: 'culture', region: 'America') #=> { team_member: 'Zach' }
 ```
  
 An empty `in` cell means "matches any value", even nils.
@@ -108,12 +108,12 @@ the table from a CSV file:
 table = CSVDecision.parse(Pathname('spec/data/valid/simple_example.csv'))
 ```
  
- We can also load this same table using the option: `first_match: false`, which means that 
- all matching rows will be accumulated into an array of hashes.
+We can also load this same table using the option: `first_match: false`, which means that 
+*all* matching rows will be accumulated into an array of hashes.
  
  ```ruby
 table = CSVDecision.parse(data, first_match: false)
-table.decide(topic: 'finance', region: 'Europe') # returns team_member: %w[Donald Ernest Zach] 
+table.decide(topic: 'finance', region: 'Europe') #=> { team_member: %w[Donald Ernest Zach] }
 ```
 
 For more examples see `spec/csv_decision/table_spec.rb`. 
@@ -121,18 +121,24 @@ Complete documentation of all table parameters is in the code - see
 `lib/csv_decision/parse.rb` and `lib/csv_decision/table.rb`.
 
 ### CSV Decision features
+ * Either returns the first matching row as a hash (default), or accumulates all matches as an 
+ array of hashes (i.e., `parse` option `first_match: false` or CSV file option `accumulate`).
  * Fast decision-time performance (see `benchmarks` folder).
- * In addition to simple string matching, can match common Ruby constants, 
- regular expressions, numeric comparisons and Ruby-style ranges.
- * Can use column symbols in comparisons for guard conditions -- e.g., > :column.
+ * In addition to simple strings, `csv_decision` can match basic Ruby constants (e.g., `=nil`), 
+ regular expressions (e.g., `=~ on|off`), comparisons (e.g., `> 100.0` ) and 
+ Ruby-style ranges (e.g., `1..10`)
+ * Can compare an input column versus another input hash key - e.g., `> :column`.
+ * Any cell starting with `#` is treated as a comment, and comments may appear anywhere in the
+ table. (Comment cells are always interpreted as the empty string.)
+ * Can use column symbol expressions or Ruby methods (0-arity) in input columns for 
+ matching - e.g., `:column.zero?` or `:column == 0`.
+ * May also use Ruby methods in output columns - e.g., `:column.length`.
  * Accepts data as a file, CSV string or an array of arrays. (For safety all input data is 
  force encoded to UTF-8, and non-ascii strings are converted to empty strings.)
  * All CSV cells are parsed for correctness, and helpful error messages generated for bad 
- inputs.
- * Either returns the first matching row as a hash, or accumulates all matches as an 
- array of hashes.
+ input.
   
-### Constants other than strings
+#### Constants other than strings
 Although `csv_decision` is string oriented, it does recognise other types of constant
 present in the input hash. Specifically, the following classes are recognized: 
 `Integer`, `BigDecimal`, `NilClass`, `TrueClass` and `FalseClass`. 
@@ -157,7 +163,7 @@ For example:
   table.decide(constant: BigDecimal('100.0')) # returns value: BigDecimal('100.0')       
 ```
  
-### Column header symbols
+#### Column header symbols
 All input and output column names are symbolized, and can be used to form simple
 expressions that refer to values in the input hash.
 
@@ -175,8 +181,9 @@ For example:
  ```
  
 Note that there is no need to include an input column for `:node` in the decision 
-table - it just needs to be present in the input hash. Also, `== :node` can be 
-shortened to just `:node`, so the above decision table may be simplified to:
+table - it just needs to be present in the input hash. The expression, `== :node` should be
+read as `:parent == :node`. It can also be shortened to just `:node`, so the above decision table 
+may be simplified to:
 
  ```ruby
     data = <<~DATA
@@ -188,7 +195,7 @@ shortened to just `:node`, so the above decision table may be simplified to:
 These comparison operators are also supported: `!=`, `>`, `>=`, `<`, `<=`.
 For more simple examples see `spec/csv_decision/examples_spec.rb`.
 
-### Column guard conditions
+#### Column guard conditions
 Sometimes it's more convenient to write guard conditions in a single column specialized for that purpose. 
 For example:
 
@@ -208,7 +215,9 @@ table.decide(country: 'US',  CUSIP: '123456789') #=> { ID: '123456789', ID_type:
 table.decide(country: 'EU',  CUSIP: '123456789', ISIN:'123456789012') 
   #=> { ID: '123456789012', ID_type: 'ISIN', len: 12 }
 ```
-Guard columns may be anonymous, and must contain non-constant expressions.  
+Guard columns may be anonymous, and must contain non-constant expressions. In addition to
+0-arity Ruby methods, the following comparison operators are also supported: `==`, `!=`,
+`>`, `>=`, `<` and `<=`. Also, regular expressions are supported - i.e., `=~` and `!~`.
   
 ### Testing
  
@@ -223,12 +232,19 @@ Guard columns may be anonymous, and must contain non-constant expressions.
 ### Planned features
  `csv_decision` is still a work in progress, and will be enhanced to support
  the following features:
- * Use of column symbol expressions or built-in guard functions in the input
- columns for matching.
- * Input columns may be indexed for faster lookup performance.
- * May use functions in the output columns to formulate the final decision.
- * Input hash values may be conditionally defaulted using a constant or a function call
- * Output columns may use interpolated strings referencing column symbols.
- * May be extended with a user-supplied library of Ruby functions for tailored logic.
+ * Text-only input columns may be indexed for faster lookup performance.
+ * Supply a pre-defined library of functions that can be called within input columns to 
+   implement matching logic or from the output columns to formulate the final decision.
+ * Available functions may be extended with a user-supplied library of Ruby methods 
+   for tailored logic.
+ * Input hash values may be (conditionally) defaulted with a constant or a function call.
+ * Output columns may construct interpolated strings referencing column symbols.
  * Can use post-match guard conditions to filter the results of multi-row 
- decision output.
+   decision output.
+ 
+### Reasons for the limitations of column expressions
+The simple column expressions allowed by `csv_decision` are purposely limited for reasons of
+understandability and maintainability. The whole point of this gem is to make decision rules
+easier to express and comprehend as declarative, tabular logic.
+While Ruby makes it easy to execute arbitrary code embedded within a CSV file, 
+this could easily result in hard to debug logic that also poses safety risks.

data/csv_decision.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = 'csv_decision'
-  spec.version       = '0.0.7'
+  spec.version       = '0.0.8'
   spec.authors       = ['Brett Vickers']
   spec.email         = ['brett@phillips-vickers.com']
   spec.description   = 'CSV based Ruby decision tables.'

data/lib/csv_decision/columns.rb

@@ -30,6 +30,10 @@ module CSVDecision
       # @return [Hash{Integer=>Entry}] All output column dictionary entries.
       attr_accessor :outs
 
+      # if: columns.
+      # @return [Hash{Integer=>Entry}] All if: column dictionary entries.
+      attr_accessor :ifs
+
       # TODO: Input hash path - optional (planned feature)
       # attr_accessor :path
 
@@ -39,6 +43,7 @@ module CSVDecision
       def initialize
         @ins = {}
         @outs = {}
+        @ifs = {}
         # TODO: @path = {}
         # TODO: @defaults = {}
       end
@@ -60,6 +65,12 @@ module CSVDecision
       @dictionary.outs
     end
 
+    # if: columns hash keyed by column index.
+    # @return [Hash{Index=>Entry}]
+    def ifs
+      @dictionary.ifs
+    end
+
     # Input columns with defaults specified (planned feature)
     # def defaults
     #   @dictionary.defaults

data/lib/csv_decision/header.rb

@@ -16,10 +16,20 @@ module CSVDecision
 
     # Column types recognised in the header row.
     COLUMN_TYPE = %r{
-      \A(?<type>in|out|in/text|out/text|guard)
+      \A(?<type>in|out|in/text|out/text|guard|if)
       \s*:\s*(?<name>\S?.*)\z
     }xi
 
+    COLUMN_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 :COLUMN_ENTRY
+
     # TODO: implement all anonymous column types
     # COLUMN_TYPE_ANONYMOUS = Set.new(%i[path if guard]).freeze
     # These column types do not need a name
@@ -88,7 +98,7 @@ module CSVDecision
     end
     private_class_method :input_column?
 
-    def self.validate_header_column(cell:)
+    def self.validate_column(cell:)
       match = COLUMN_TYPE.match(cell)
       raise CellValidationError, 'column name is not well formed' unless match
 
@@ -99,7 +109,7 @@ module CSVDecision
     rescue CellValidationError => exp
       raise CellValidationError, "header column '#{cell}' is not valid as the #{exp.message}"
     end
-    private_class_method :validate_header_column
+    private_class_method :validate_column
 
     # Array of all empty column indices.
     def self.empty_columns?(row:)
@@ -131,25 +141,13 @@ module CSVDecision
     # Returns the normalized column type, along with an indication if
     # the column requires evaluation
     def self.column_type(column_name, type)
-      case type
-      when :'in/text'
-        Columns::Entry.new(column_name, false, :in)
-
-      when :guard
-        Columns::Entry.new(column_name, true, :guard)
-
-      when :'out/text'
-        Columns::Entry.new(column_name, false, :out)
-
-      # Column may turn out to be constants only, or not
-      else
-        Columns::Entry.new(column_name, nil, type.to_sym)
-      end
+      entry = COLUMN_ENTRY[type]
+      Columns::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_header_column(cell: cell)
+      column_type, column_name = validate_column(cell: cell)
 
       entry = column_type(column_name, column_type)
 

data/lib/csv_decision/matchers/guard.rb

@@ -22,7 +22,7 @@ module CSVDecision
       GUARD =
         "(?<negate>#{Matchers::NEGATE}?)\\s*" \
         ":(?<name>#{Header::COLUMN_NAME})\\s*" \
-        "(?<method>#{Matchers::EQUALS}|!=|<=|>=|>|<|\\.)\\s*" \
+        "(?<method>!=|=~|!~|<=|>=|>|<|#{Matchers::EQUALS}|\\.)\\s*" \
         "(?<param>\\S.*)"
       private_constant :GUARD
 
@@ -30,9 +30,10 @@ module CSVDecision
       private_constant :GUARD_RE
 
       # Negated methods
-      NEGATION = { '='  => '!=', '==' => '!=', ':=' => '!=', '!=' => '=',
-                   '>'  => '<=', '>=' => '<', '<' => '>=', '<=' => '>',
-                   '.'  => '!.' }.freeze
+      NEGATION = { '=' => '!=', '==' => '!=', ':=' => '!=', '!=' => '=',
+                   '>' => '<=', '>=' => '<', '<' => '>=', '<=' => '>',
+                   '.' => '!.',
+                   '=~' => '!~', '!~' => '=~' }.freeze
       private_constant :NEGATION
 
       # Note: value has already been converted to an Integer or BigDecimal.
@@ -46,13 +47,20 @@ module CSVDecision
       }.freeze
       private_constant :NUMERIC_COMPARE
 
-      def self.symbol_function(symbol, value, hash)
-        hash[symbol].respond_to?(value) && hash[symbol].send(value)
+      def self.symbol_function(symbol, method, hash)
+        hash[symbol].respond_to?(method) && hash[symbol].send(method)
+      end
+
+      def self.regexp_match(symbol, value, hash)
+        value.is_a?(String) && hash[symbol].is_a?(String) &&
+          Matchers.regexp(value).match(hash[symbol])
       end
 
       FUNCTION = {
-        '.'  => proc { |symbol, value, hash|  symbol_function(symbol, value, hash) },
-        '!.' => proc { |symbol, value, hash| !symbol_function(symbol, value, hash) }
+        '.'  => proc { |symbol, method, hash|  symbol_function(symbol, method, hash) },
+        '!.' => proc { |symbol, method, hash| !symbol_function(symbol, method, hash) },
+        '=~' => proc { |symbol, value, hash|  regexp_match(symbol, value, hash) },
+        '!~' => proc { |symbol, value, hash| !regexp_match(symbol, value, hash) }
       }.freeze
       private_constant :FUNCTION
 
@@ -120,7 +128,7 @@ module CSVDecision
       end
       private_class_method :symbol_guard
 
-      # (see Matchers::Matcher#matches?)
+      # (see Matcher#matches?)
       def self.matches?(cell)
         proc = symbol_proc(cell)
         return proc if proc
@@ -131,7 +139,7 @@ module CSVDecision
       # @param (see Matcher#matches?)
       # @return (see Matcher#matches?)
       def matches?(cell)
-        Matchers::Guard.matches?(cell)
+        Guard.matches?(cell)
       end
 
       # @return (see Matcher#outs?)

data/lib/csv_decision/matchers/symbol.rb

@@ -10,9 +10,9 @@ module CSVDecision
   class Matchers
     # Match cell against a symbolic expression - e.g., :column, > :column
     class Symbol < Matcher
-      # Symbol comparison - e.g., > :column or != :column
+      # Column symbol comparison - e.g., > :column or != :column
       SYMBOL_COMPARE =
-        "(?<comparator>#{Matchers::EQUALS}|!=|<|>|>=|<=)?\\s*:(?<name>#{Header::COLUMN_NAME})"
+        "(?<comparator>!=|>=|<=|<|>|#{Matchers::EQUALS})?\\s*:(?<name>#{Header::COLUMN_NAME})"
       private_constant :SYMBOL_COMPARE
 
       # Symbol comparision regular expression.

data/lib/csv_decision/scan_row.rb

@@ -24,7 +24,7 @@ module CSVDecision
     def self.scan_matchers(column:, matchers:, cell:)
       matchers.each do |matcher|
         # Guard function only accepts the same matchers as an output column.
-        next if column.type == :guard && !matcher.outs?
+        next if guard_ins_matcher?(column, matcher)
 
         proc = scan_proc(column: column, cell: cell, matcher: matcher)
         return proc if proc
@@ -35,6 +35,12 @@ module CSVDecision
     end
     private_class_method :scan_matchers
 
+    # A guard column can only use output matchers
+    def self.guard_ins_matcher?(column, matcher)
+      column.type == :guard && !matcher.outs?
+    end
+    private_class_method :guard_ins_matcher?
+
     def self.scan_proc(column:, cell:, matcher:)
       proc = matcher.matches?(cell)
       guard_constant?(type: proc.type, column: column) if proc

data/spec/csv_decision/matchers/symbol_spec.rb

@@ -37,12 +37,14 @@ describe CSVDecision::Matchers::Symbol do
         { cell:  ':=:col', value:  0,  hash: { col:  0 },  result: true },
         { cell:  '= :col', value: '0', hash: { col:  0 },  result: false },
         { cell:  '>=:col', value:  1,  hash: { col:  0 },  result: true },
+        { cell:  '>=:col', value:  1,  hash: { col:  1 },  result: true },
         { cell:  '>=:col', value:  0,  hash: { col:  1 },  result: false },
         { cell:  '<=:col', value:  0,  hash: { col:  1 },  result: true },
         { cell:  '<=:col', value:  1,  hash: { col:  0 },  result: false },
+        { cell:  '<=:col', value:  1,  hash: { col:  1 },  result: true },
         { cell:  '<=:col', value: '1', hash: { col:  1 },  result: false },
+        { cell:  '<=:col', value: '1', hash: { col: '1' }, result: true },
       ]
-
       examples.each do |ex|
         it "cell #{ex[:cell]} matches value: #{ex[:value]} to hash: #{ex[:hash]}" do
           proc = matcher.matches?(ex[:cell])

data/spec/csv_decision/table_spec.rb

@@ -131,6 +131,22 @@ describe CSVDecision::Table do
             ,          maniac,        Korolev
           DATA
         },
+        {
+          example: 'guard condition',
+          options: { regexp_implicit: false },
+          data: <<~DATA
+            in :age,   guard:,               out :salesperson
+            18..35,    :trait == maniac,     Adelsky
+            23..40,    :trait =~ bad|maniac, Bronco
+            36..50,    :trait =~ bad.*,      Espadas
+            ==100,     ,                     Thorsten
+            44..100,   :trait !~ maniac,     Ojiisan
+            > 100,     :trait =~ maniac.*,   Chester
+            23..35,    :trait =~ .*rich,     Kerfelden
+            ,          :trait == cheerful,   Swanson
+            ,          :trait == maniac,     Korolev
+          DATA
+        },
         {
           example: 'multiple in column references',
           options: { regexp_implicit: false },
@@ -239,6 +255,14 @@ describe CSVDecision::Table do
             ,         no
           DATA
         },
+        { example: 'uses ==:parent & != :parent',
+          options: { first_match: false },
+          data: <<~DATA
+            in :node,    out :top?
+            == :parent,  yes
+            != :parent,  no
+          DATA
+        },
         { example: 'uses != :parent, drops :parent input column',
           options: {},
           data: <<~DATA
@@ -246,6 +270,14 @@ describe CSVDecision::Table do
             != :parent,  no
             ,            yes
           DATA
+        },
+        { example: 'uses != :parent and == :parent',
+          options: { first_match: false },
+          data: <<~DATA
+            in :node,    out :top?
+            != :parent,  no
+            == :parent,  yes
+          DATA
         }
       ]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: csv_decision
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Brett Vickers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-30 00:00:00.000000000 Z
+date: 2017-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport