csv_decision2 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a1c5b8a4584339463eb67ce93820087378a62c7edc0b63b61c199b008739604
+  data.tar.gz: e091e00ea144d06fefc692e23639e282f64150305ee5864354d53b91928d9f0d
+SHA512:
+  metadata.gz: 744dd6194daf1902d0eab2e302b82cab87c15c3fe9e0413b7f32b68138ccb3267f6601110fec732a8738596b403bb55a7b9b855e20adbaa0eb3f9dc982b53d5b
+  data.tar.gz: d977d550fab93f91ecae7b6ba668383c6bbc14538e7dd798d632cc2e986bc4a9eb89ff141db5d25d89efd0c63391e7858a4f761745a4294dfaa70eb131384ee4

data/.codeclimate.yml

@@ -0,0 +1,3 @@
+exclude_patterns:
+- "doc/"
+- "spec/"

data/.coveralls.yml

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

data/.gitignore

@@ -0,0 +1,14 @@
+*~
+#*#
+*old
+*.bak
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+# IDE files
+.idea
+.DS_Store
+coverage/
+.yardoc/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require 'spec_helper'

data/.rubocop.yml

@@ -0,0 +1,30 @@
+AllCops:
+  TargetRubyVersion: 2.3.0
+
+Metrics/MethodLength:
+  CountComments: false
+  Max: 15
+
+Metrics/LineLength:
+  Max: 100
+
+Layout/TrailingWhitespace:
+  Enabled: false
+
+Layout/SpaceInsideArrayPercentLiteral:
+  Enabled: false
+
+Layout/AlignArray:
+  Enabled: false
+
+Layout/IdentArray:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+sudo: false
+rvm:
+  - 2.7.0
+script:
+  - bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,85 @@
+## v0.5.1, 12 February 2018.
+*Bug Fix*
+- Fix bug when using a path to scan for a first match.
+
+## v0.5.0, 11 February 2018.
+*Additions*
+- Add the ability to specify an input hash path using path: column types.
+
+## v0.4.1, 10 February 2018.
+*Additions*
+- For consistency, input columns may now use the form `!nil?` to negate 0-arity Ruby methods.
+(Typical SME users can be somewhat lax with syntax.)
+
+## v0.4.0, 28 January 2018.
+*Additions*
+- Input columns may now use 0-arity Ruby methods to implement conditional logic.
+For example `.present?` or `nil?`. Negation is also supported - e.g., `!.nil?`.
+
+## v0.3.2, 28 January 2018.
+*Changes*
+- Refactor code and update documentation.
+
+## v0.3.1, 21 January 2018.
+*Changes*
+- Optimize code.
+
+## v0.3.0, 20 January 2018.
+*Additions*
+- Index one or more text-only input columns for faster lookup performance.
+
+## v0.2.0, 13 January 2018.
+*Additions*
+- Set values in the input hash either as a default or unconditionally.
+
+## v0.1.0, 5 January 2018.
+*Additions*
+- Implement more checks on output columns that are duplicated or
+reference columns that appear after them.
+
+## v0.0.9, 5 January 2018.
+*Additions*
+- Output column if: filter conditions.
+
+## 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.
+
+## v0.0.5, 26 December 2017.
+*Additions*
+- Update YARD documentation.
+
+## v0.0.4, 26 December 2017.
+*Additions*
+- Adds symbol expressions for input columns.
+- Adds non-string constants for output columns.
+- Support Ruby 2.5.0
+- Include YARD documentation.
+
+*Changes*
+- Move `benchmark.rb` to `benchmarks` folder and rename to `rufus_decision.rb`
+
+## v0.0.3, 18 December 2017.
+*Additions*
+- Add non-string constants for input columns.
+
+## v0.0.2, 18 December 2017.
+*Additions*
+- Adds accumulate option.
+
+## v0.0.1, 18 December 2017.
+- Initial release

data/Dockerfile

@@ -0,0 +1,6 @@
+FROM ruby:3.3.0
+RUN mkdir -p /app
+WORKDIR /app
+COPY Gemfile csv_decision.gemspec ./
+RUN gem update bundler
+# RUN bundle install

data/Gemfile

@@ -0,0 +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

@@ -0,0 +1,356 @@
+# CSV Decision
+
+[![Gem Version](https://badge.fury.io/rb/csv_decision.svg)](https://badge.fury.io/rb/csv_decision)
+[![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)
+[![Maintainability](https://api.codeclimate.com/v1/badges/466a6c52e8f6a3840967/maintainability)](https://codeclimate.com/github/bpvickers/csv_decision/maintainability)
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+
+### INFORMATION
+
+This repo is created while waiting the owner to support latest version
+
+### CSV based Ruby decision tables
+
+`csv_decision2` is a RubyGem for CSV based
+[decision tables](https://en.wikipedia.org/wiki/Decision_table).
+It accepts decision tables implemented as a
+[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values),
+which can then be used to execute complex conditional logic against an input hash,
+producing a decision as an output hash.
+
+### Why use `csv_decision2`?
+
+Typical "business logic" is notoriously illogical - full of corner cases and one-off
+exceptions.
+A decision table can express data-based decisions in a way that comes naturally
+to subject matter experts, who typically use spreadsheet models.
+Business logic can be encapsulated in a table, avoiding the need for tortuous conditional
+expressions.
+
+This gem and the examples below take inspiration from
+[rufus/decision](https://github.com/jmettraux/rufus-decision).
+(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
+
+To get started, just add `csv_decision2` to your `Gemfile`, and then run `bundle`:
+
+```ruby
+gem 'csv_decision2'
+```
+
+or simply
+
+```bash
+gem install csv_decision2
+```
+
+### Simple example
+
+This table considers two input conditions: `topic` and `region`, 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 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's the example as code:
+
+```ruby
+ # Valid CSV string
+ 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') #=> { 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".
+
+Note that all column header names are symbolized, so it's actually more accurate to write
+`in :topic`; however spaces before and after the `:` do not matter.
+
+If you have cloned this gem's git repo, then the example can also be run by loading
+the table from a CSV file:
+
+```ruby
+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.
+
+```ruby
+table = CSVDecision.parse(data, first_match: false)
+table.decide(topic: 'finance', region: 'Europe') #=> { team_member: %w[Donald Ernest Zach] }
+```
+
+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`.
+
+### 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). Automatically indexes all
+  constants-only columns that do not contain any empty strings.
+- In addition to strings, 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.
+- Column symbol expressions or Ruby methods (0-arity) may be used 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.
+
+#### 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`.
+
+This is accomplished by prefixing the value with one of the operators `=`, `==` or `:=`.
+(The syntax is intentionally lax.)
+
+For example:
+
+```ruby
+   data = <<~DATA
+     in :constant, out :value
+     :=nil,        :=nil
+     ==false,      ==false
+     =true,        =true
+     = 0,          = 0
+     :=100.0,      :=100.0
+   DATA
+
+ table = CSVDecision.parse(data)
+ table.decide(constant: nil) # returns value: nil
+ table.decide(constant: 0) # returns value: 0
+ table.decide(constant: BigDecimal('100.0')) # returns value: BigDecimal('100.0')
+```
+
+#### Column header symbols
+
+All input and output column names are symbolized, and those symbols may be used to form
+simple expressions that refer to values in the input hash.
+
+For example:
+
+```ruby
+   data = <<~DATA
+     in :node, in :parent, out :top?
+     ,         == :node,   yes
+     ,         ,           no
+   DATA
+
+   table = CSVDecision.parse(data)
+   table.decide(node: 0, parent: 0) # returns top?: 'yes'
+   table.decide(node: 1, parent: 0) # returns top?: 'no'
+```
+
+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. 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
+     in :parent, out :top?
+        :node,   yes
+     ,           no
+   DATA
+```
+
+These comparison operators are also supported: `!=`, `>`, `>=`, `<`, `<=`.
+In addition, you can also apply a Ruby 0-arity method - e.g., `.present?` or `.nil?`. Negation is
+also supported - e.g., `!.nil?`. Note that `.nil?` can also be written as `:= nil?`, and `!.nil?`
+as `:= !nil?`, depending on preference.
+
+For more simple examples see `spec/csv_decision/examples_spec.rb`.
+
+#### Input `guard` conditions
+
+Sometimes it's more convenient to write guard expressions in a single column specialized for that purpose.
+For example:
+
+```ruby
+data = <<~DATA
+  in :country, guard:,          out :ID, out :ID_type, out :len
+  US,          :CUSIP.present?, :CUSIP,  CUSIP,        :ID.length
+  GB,          :SEDOL.present?, :SEDOL,  SEDOL,        :ID.length
+  ,            :ISIN.present?,  :ISIN,   ISIN,         :ID.length
+  ,            :SEDOL.present?, :SEDOL,  SEDOL,        :ID.length
+  ,            :CUSIP.present?, :CUSIP,  CUSIP,        :ID.length
+  ,            ,                := nil,  := nil,       := nil
+DATA
+
+table = CSVDecision.parse(data)
+table.decide(country: 'US',  CUSIP: '123456789') #=> { ID: '123456789', ID_type: 'CUSIP', len: 9 }
+table.decide(country: 'EU',  CUSIP: '123456789', ISIN:'123456789012')
+  #=> { ID: '123456789012', ID_type: 'ISIN', len: 12 }
+```
+
+Input `guard:` columns may be anonymous, and must contain non-constant expressions. In addition to
+0-arity Ruby methods, the following comparison operators are allowed: `==`, `!=`,
+`>`, `>=`, `<` and `<=`. Also, regular expressions are supported - i.e., `=~` and `!~`.
+
+#### Output `if` conditions
+
+In some situations it is useful to apply filter conditions _after_ all the output
+columns have been derived. For example:
+
+```ruby
+data = <<~DATA
+  in :country, guard:,          out :ID, out :ID_type, out :len,   if:
+  US,          :CUSIP.present?, :CUSIP,  CUSIP8,       :ID.length, :len == 8
+  US,          :CUSIP.present?, :CUSIP,  CUSIP9,       :ID.length, :len == 9
+  US,          :CUSIP.present?, :CUSIP,  DUMMY,        :ID.length,
+  ,            :ISIN.present?,  :ISIN,   ISIN,         :ID.length, :len == 12
+  ,            :ISIN.present?,  :ISIN,   DUMMY,        :ID.length,
+  ,            :CUSIP.present?, :CUSIP,  DUMMY,        :ID.length,
+  DATA
+
+table = CSVDecision.parse(data)
+table.decide(country: 'US',  CUSIP: '123456789') #=> {ID: '123456789', ID_type: 'CUSIP9', len: 9}
+table.decide(CUSIP: '12345678', ISIN:'1234567890') #=> {ID: '1234567890', ID_type: 'DUMMY', len: 10}
+```
+
+Output `if:` columns may be anonymous, and must contain non-constant expressions. In addition to
+0-arity Ruby methods, the following comparison operators are allowed: `==`, `!=`,
+`>`, `>=`, `<` and `<=`. Also, regular expressions are supported - i.e., `=~` and `!~`.
+
+#### Input `set` columns
+
+If you wish to set default values in the input hash, you can use a `set` column rather
+than an `in` column. The data row beneath the header is used to specify the default expression.
+There are three variations: `set` (unconditional default) `set/nil?`(set if `nil?` true)
+and `set/blank?` (set if `blank?` true).
+Note that the `decide!` method will mutate the input hash.
+
+```ruby
+data = <<~DATA
+  set/nil? :country, guard:,          set: class,    out :PAID, out: len,     if:
+  US,                ,                :class.upcase,
+  US,                :CUSIP.present?, != PRIVATE,    :CUSIP,    :PAID.length, :len == 9
+  !=US,              :ISIN.present?,  != PRIVATE,    :ISIN,     :PAID.length, :len == 12
+  US,                :CUSIP.present?, PRIVATE,       :CUSIP,    :PAID.length,
+  !=US,              :ISIN.present?,  PRIVATE,       :ISIN,     :PAID.length,
+DATA
+
+table = CSVDecision.parse(data)
+table.decide(CUSIP: '1234567890', class: 'Private') #=> {PAID: '1234567890', len: 10}
+table.decide(ISIN: '123456789012', country: 'GB', class: 'private') #=> {PAID: '123456789012', len: 12}
+
+```
+
+#### Input `path` columns
+
+For hashes that contain sub-hashes, it's possible to specify a path for the purposes
+of matching. (Arrays are currently not supported.)
+
+```ruby
+data = <<~DATA
+  path:,   path:,    out :value
+  header,  ,         :source_name
+  header,  metrics,  :service_name
+  payload, ,         :amount
+  payload, ref_data, :account_id
+DATA
+table = CSVDecision.parse(data, first_match: false)
+
+input = {
+  header: {
+    id: 1, type_cd: 'BUY', source_name: 'Client', client_name: 'AAPL',
+    metrics: { service_name: 'Trading', receive_time: '12:00' }
+  },
+  payload: {
+    tran_id: 9, amount: '100.00',
+    ref_data: { account_id: '5010', type_id: 'BUYL' }
+  }
+}
+
+table.decide(input) #=> { value: %w[Client Trading 100.00 5010] }
+```
+
+### Testing
+
+`csv_decision` includes thorough [RSpec](http://rspec.info) tests:
+
+```bash
+# Execute within a clone of the csv_decision Git repository:
+bundle install
+rspec
+```
+
+### Planned features
+
+`csv_decision` is still a work in progress, and will be enhanced to support
+the following features:
+
+- Supply a pre-defined library of functions that may be called within input columns to
+  implement custom matching logic, or from the output columns to formulate the final
+  decision.
+- Built-in lookup functions evaluate other decision tables to implement guard conditions,
+  or supply output values.
+- Available functions may be extended with a user-supplied library of Ruby methods
+  for custom logic.
+- Output columns may construct interpolated strings containing references to column
+  symbols.
+
+### 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.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a list of changes.
+
+## License
+
+CSV Decision &copy; 2017-2018 by [Brett Vickers](mailto:brett@phillips-vickers.com).
+CSV Decision is licensed under the MIT license. Please see the [LICENSE](./LICENSE)
+document for more information.