csv_decision 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 486bc130f39ee0893ac24493bb1e4f866e23171a
-  data.tar.gz: 1b0b4467391b2358e0bdb6e380a9fc7cbfa815d9
+  metadata.gz: 824f8e4c688f507bc8e0ea1c65c37d7a615e7d1d
+  data.tar.gz: 644623f44ba59db10bc98470e113673f0482fbcd
 SHA512:
-  metadata.gz: c8dae72ca353f917f4511735e5a5d5d7f9eccc7627a41cdf53e9a92c8d63374cf69f4c84834da1e8cd9ae08178ae13aaa71443bbed5e60394507645296f5b931
-  data.tar.gz: b292cd9287309a084fefd21d78f6b04d90448188ff85008b17c75dc6aab66cc902e3bfddcfe66d1c266b7c924bbe5ee9d33dc73609da9bcddffccbd306217808
+  metadata.gz: 005e743b69070d458d93d8fef1fd1e75e6328d3046e6adb7e2461d0d3201848d011922e3536b4942949697d3cbb04f985af21da48b3464690c2373490ffffd5c
+  data.tar.gz: e3dd1c8cc027ae660a82ad8f5c9be5f1307741aa329ca03c109bc28486acd59dac4ecc18ed497e75294f162fda596d91cd1e937f3ccbb494af4bd6fcf57e8692

data/.coveralls.yml

@@ -0,0 +1,2 @@
+service_name: travis-ci
+repo_token: Rr2wjGPimrqmxVhIHHN29kGxcaQnSh4Xs

data/.rubocop.yml

@@ -1,15 +1,27 @@
 AllCops:
-  TargetRubyVersion: 2.3.1
+  TargetRubyVersion: 2.3.0
 
 Metrics/MethodLength:
   CountComments: false
   Max: 15
 
-Metrics/AbcSize:
-  Max: 18
-
 Metrics/LineLength:
   Max: 100
 
 Layout/TrailingWhitespace:
   Enabled: false
+
+Layout/SpaceInsideArrayPercentLiteral:
+  Enabled: false
+
+Layout/AlignArray:
+  Enabled: false
+
+Layout/IdentArray:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,10 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=787a2f89b15c637323c7340d65ec17e898ac44480706b4b4122ea040c2a88f1d
+language: ruby
+rvm:
+  - 2.3.0
+  - 2.3.6
+  - 2.4.3
+script:
+  - bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## v0.0.1, 28 December 2017.
+- Initial release

data/Gemfile

@@ -1,4 +1,7 @@
 source 'https://rubygems.org'
 
+gem 'coveralls', require: false
+
 gemspec
 
+

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Brett Vickers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,20 +1,134 @@
-# csv_decision - Work In Progress
-`csv_decision` is a Ruby gem for CSV based decision tables. It accepts decision table logic encoded in
-a CSV file, which can then be used to implement complex conditional logic.
+CSV Decision
+============
 
-`csv_decision` has many useful features:
- * able to parse and load into memory many CSV files for subsequent processing
- * can return the first matching row as a hash, or accumulate all matches as an array of hashes
- * input columns may be indexed for fast lookup performance
- * can use regular expressions, Ruby-style ranges and function calls to implement complex decision logic
- * all CSV cells are parsed for correctness, and friendly error messages generated for bad input
- * can be safely extended with user defined Ruby functions for tailored logic
- * good decision time performance
- * flexible options for tailoring behavior and defaults
- 
- ### Why use CSV Decision?
- 
- Typical "business logic" is notoriously illogical -- full of corner cases and irregular exceptions. 
- A decision table can capture data-based decisions in a way that comes naturally to analysts and subject matter 
- experts, who typically use spreadsheet models. Business logic can be encapsulated, avoiding the need to write
- tortuous conditional expressions in Ruby that draws the ire of `rubocop` and its ilk.
+<a href="https://codeclimate.com/github/bpvickers/csv_decision/maintainability"><img src="https://api.codeclimate.com/v1/badges/466a6c52e8f6a3840967/maintainability" /></a>
+[![Build Status](https://travis-ci.org/bpvickers/csv_decision.svg?branch=master)](https://travis-ci.org/bpvickers/csv_decision)
+[![Coverage Status](https://coveralls.io/repos/github/bpvickers/csv_decision/badge.svg?branch=master)](https://coveralls.io/github/bpvickers/csv_decision?branch=master)
+[![Gem Version](https://badge.fury.io/rb/csv_decision.svg)](http://badge.fury.io/rb/csv_decision)
+
+# CSV based Ruby decision tables
+
+`csv_decision` is a Ruby gem for CSV (comma separated values) based 
+[decision tables](https://en.wikipedia.org/wiki/Decision_table). 
+It accepts decision tables written in a CSV file, which can then be used to execute 
+complex conditional logic against an input hash, producing a decision as an output hash.
+
+ ### `csv_decision` features
+ * fast decision-time performance
+ * can use regular expressions, numeric comparisons and Ruby-style ranges
+ * accepts data as a file, CSV string or an array of arrays.
+ * all CSV cells are parsed for correctness, and helpful error messages generated for bad 
+ inputs
+ 
+ ### Planned features
+ * input columns may be indexed for faster lookup performance
+ * either returns the first matching row as a hash, or accumulates all matches as an 
+ array of hashes.
+ * use of output functions to formulate the final decision
+ * can use column symbol references or built-in guard functions for matching
+ * may be extended with user-defined Ruby functions for tailored logic 
+ * can use if conditions to filter the results of multi-row decision output
+ 
+ ### Why use `csv_decision`?
+ 
+ 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 
+ 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 takes its inspiration from 
+ [rufus/decision](https://github.com/jmettraux/rufus-decision).
+ (That gem is no longer maintained and has issues with execution performance.)
+ 
+ ### Installation
+ 
+ To get started, just add `csv_decision` to your `Gemfile`, and then run `bundle`:
+ 
+ ```ruby
+ gem 'csv_decision', '~> 0.0.1'
+ ```
+ 
+ ### Simple example
+ 
+ A decision table may be as simple or as complex as you like (although very complex 
+ tables defeat the whole purpose). 
+ Basic usage will be illustrated by an example taken from:
+ https://jmettraux.wordpress.com/2009/04/25/rufus-decision-11-ruby-decision-tables/.
+ 
+ This example considers two input conditions: `topic` and `region`.
+ These are labeled `in`. Certain combinations yield an output value for `team_member`, 
+ labeled `out`.
+ 
+```
+in :topic | in :region  | out :team_member
+----------+-------------+-----------------
+sports    | Europe      | Alice
+sports    |             | Bob
+finance   | America     | Charlie
+finance   | Europe      | Donald
+finance   |             | Ernest
+politics  | Asia        | Fujio
+politics  | America     | Gilbert
+politics  |             | Henry
+          |             | Zach
+```
+ 
+ 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. 
+ 
+ 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.
+ 
+ Now for some code.
+ 
+ ```ruby
+  data = <<~DATA
+    in :topic, in :region,  out :team_member
+    sports,    Europe,      Alice
+    sports,    ,            Bob
+    finance,   America,     Charlie
+    finance,   Europe,      Donald
+    finance,   ,            Ernest
+    politics,  Asia,        Fujio
+    politics,  America,     Gilbert
+    politics,  ,            Henry
+    ,          ,            Zach
+  DATA
+
+  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'
+```
+ 
+ An empty `in` cell means "matches any value".
+ 
+ If you have cloned this gem's git repo, then this example can also be run by loading
+ the table from a CSV file:
+ 
+ ```ruby
+table = CSVDecision.parse(Pathname('spec/data/valid/simple_example.csv'))
+```
+ 
+ For more examples see `spec/csv_decision/table_spec.rb`. 
+ Complete documentation of all table parameters is in the code - see 
+ `lib/csv_decision/parse.rb` and `lib/csv_decision/table.rb`.
+ 
+ 
+ ### Testing
+ 
+ `csv_decision` includes thorough [RSpec](http://rspec.info) tests:
+ 
+ ```bash
+ # Execute within a clone of the csv_decision Git repository:
+ bundle install
+ rspec
+ ```

data/benchmark.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+require 'benchmark/memory'
+require 'rufus/decision'
+require 'ice_nine'
+require 'ice_nine/core_ext/object'
+
+require_relative 'lib/csv_decision'
+
+SPEC_DATA_VALID ||= File.join(CSVDecision.root, 'spec', 'data', 'valid')
+
+CSV_OPTIONS = { regexp_implicit: true }.freeze
+RUFUS_OPTIONS = { open_uri: false, ruby_eval: false }.freeze
+
+benchmarks = [
+  {
+    name: 'String compares only (no index)',
+    data: 'simple_example.csv',
+    input: { 'topic' => 'culture', 'region' => 'America' },
+    # Expected results for first_match and accumulate
+    first_match: { 'team_member' => 'Zach' }
+  }
+].deep_freeze
+
+tag_width = 70
+
+puts ""
+puts "Benchmarking Decisions per Second"
+puts '=' * tag_width
+puts ""
+
+# First match true and false run options
+[true].each do |first_match|
+  puts "Table Decision Option: first_match: #{first_match}"
+  puts '-' * tag_width
+
+  csv_options = CSV_OPTIONS.merge(first_match: first_match)
+  rufus_options = RUFUS_OPTIONS.merge(first_match: first_match)
+
+  benchmarks.each do |test|
+    name = test[:name]
+    data = Pathname(File.join(SPEC_DATA_VALID, test[:data]))
+
+    rufus_table = Rufus::Decision::Table.new(data.to_s, rufus_options)
+    csv_table = CSVDecision.parse(data, csv_options)
+
+    # Prepare input hash
+    input = test[:input].deep_dup
+    input_symbolized = input.symbolize_keys
+
+    # Test expected results
+    expected = first_match ? test[:first_match] : test[:accumulate]
+
+    result = rufus_table.transform!(input)
+
+    unless result.slice(*expected.keys).eql?(expected)
+      raise "Rufus expected results check failed for test: #{name}"
+    end
+
+    result = csv_table.decide!(input_symbolized)
+
+    unless result.eql?(expected.symbolize_keys)
+      raise "CSV Decision expected results check failed for test: #{name}"
+    end
+
+    Benchmark.ips do |x|
+      GC.start
+      x.report("CSV decision   (first_match: #{first_match}) - #{name}: ") do |count|
+        count.times { csv_table.decide!(input_symbolized) }
+      end
+
+      GC.start
+      x.report("Rufus decision (first_match: #{first_match}) - #{name}: ") do |count|
+        count.times { rufus_table.transform!(input) }
+      end
+
+      x.compare!
+    end
+  end
+end
+
+puts ""
+puts "Benchmarking Memory"
+puts '=' * tag_width
+puts ""
+
+def benchmark_memory(test, quiet: false)
+  name = test[:name]
+  data = Pathname(File.join(SPEC_DATA_VALID, test[:data]))
+  file_name = data.to_s
+
+  rufus_tables = {}
+  csv_tables = {}
+  key = File.basename(file_name, '.csv').to_sym
+
+  Benchmark.memory(quiet: quiet) do |x|
+    GC.start
+    x.report("Rufus new table - #{name}        ") do
+      rufus_tables[key] = Rufus::Decision::Table.new(file_name, RUFUS_OPTIONS)
+    end
+
+    GC.start
+    x.report("CSV Decision new table - #{name} ") do
+      csv_tables[key] = CSVDecision.parse(data, CSV_OPTIONS)
+    end
+
+    x.compare!
+  end
+end
+
+# Warmup
+benchmarks.each { |test| benchmark_memory(test, quiet: true) }
+
+# Run the test
+benchmarks.each { |test| benchmark_memory(test, quiet: false) }
+
+puts ""
+puts "Benchmarking Table Loads per Second"
+puts '=' * tag_width
+puts ""
+
+benchmarks.each do |test|
+  name = test[:name]
+  data = Pathname(File.join(SPEC_DATA_VALID, test[:data]))
+  file_name = data.to_s
+
+  Benchmark.ips do |x|
+    GC.start
+    x.report("CSV new table   - #{name}: ") do |count|
+      count.times { CSVDecision.parse(data) }
+    end
+
+    GC.start
+    x.report("Rufus new table - #{name}: ") do |count|
+      count.times { Rufus::Decision::Table.new(file_name, RUFUS_OPTIONS) }
+    end
+
+    x.compare!
+  end
+end
+
+

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.1'
+  spec.version       = '0.0.2'
   spec.authors       = ['Brett Vickers']
   spec.email         = ['brett@phillips-vickers.com']
   spec.description   = 'CSV based Ruby decision tables.'
@@ -18,17 +18,19 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.3.1'
+  spec.required_ruby_version = '>= 2.3.0'
 
-  spec.add_dependency 'activesupport', '~> 5.0'
+  spec.add_dependency 'activesupport', '~> 5.1'
+  spec.add_dependency 'ice_nine', '~> 0.11'
+  spec.add_dependency 'values', '~> 1.8'
 
   spec.add_development_dependency 'benchmark-ips',         '~> 2.7'
   spec.add_development_dependency 'benchmark-memory',      '~> 0.1'
   spec.add_development_dependency 'bundler',               '~> 1.3'
   spec.add_development_dependency 'oj',                    '~> 3.3'
   spec.add_development_dependency 'rake',                  '~> 12.3'
-  spec.add_development_dependency 'rspec',                 '~> 3.5'
-  spec.add_development_dependency 'rubocop',               '~> 0.51'
+  spec.add_development_dependency 'rspec',                 '~> 3.7'
+  spec.add_development_dependency 'rubocop',               '~> 0.52'
   spec.add_development_dependency 'rufus-decision',        '~> 1.3'
-  spec.add_development_dependency 'simplecov',             '~> 0.12'
+  spec.add_development_dependency 'simplecov',             '~> 0.15'
 end

data/lib/csv_decision.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true\
 
+require 'active_support/core_ext/object'
+require 'csv_decision/parse'
+
 # CSV Decision: CSV based Ruby decision tables.
 # Created December 2017 by Brett Vickers
 # See LICENSE and README.md for details.
-
-require 'active_support/core_ext/object'
-require_relative '../lib/csv_decision/table'
-
 module CSVDecision
   # @return [String] gem project's root directory
   def self.root
@@ -14,6 +13,21 @@ module CSVDecision
   end
 
   autoload :Data,     'csv_decision/data'
+  autoload :Decide,   'csv_decision/decide'
+  autoload :Decision, 'csv_decision/decision'
+  autoload :Columns,  'csv_decision/columns'
+  autoload :Header,   'csv_decision/header'
+  autoload :Input,    'csv_decision/input'
+  autoload :Load,     'csv_decision/load'
+  autoload :Matchers, 'csv_decision/matchers'
   autoload :Options,  'csv_decision/options'
   autoload :Parse,    'csv_decision/parse'
+  autoload :ScanRow,  'csv_decision/scan_row'
+  autoload :Table,    'csv_decision/table'
+
+  module Matchers
+    autoload :Numeric, 'csv_decision/matchers/numeric'
+    autoload :Pattern, 'csv_decision/matchers/pattern'
+    autoload :Range,   'csv_decision/matchers/range'
+  end
 end