spot_feel 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6323936066f69077c032e9e4f376d10f1ae2c4d343279b4aeded36b9204aa73a
+  data.tar.gz: 2ce14493ddc4432073b2ecd2c966a2f05d29c209b06b0b3f4c66df0d932888fe
+SHA512:
+  metadata.gz: b52024d181ce210c77ec71e9dc040476bde8a96ca1126b7cd3f7b4242cbea24dd6a164ea627d5dc463f9b70975d7eca142ce2836a2b7d72445f37358ab1796f9
+  data.tar.gz: 01ce5c7901b08b926caf0a79806742f33d6051edcff0d9b33a153d5b0e601cd959377db81eede03c14f2fc340d27cb366821b6fc1f736047db14f88a40890a39

data/README.md

@@ -0,0 +1,183 @@
+# Spot Feel
+
+A light-weight DMN FEEL expression evaluator and business rule engine in Ruby.
+
+This gem implements a subset of FEEL (Friendly Enough Expression Language) as defined in the [DMN 1.3 specification](https://www.omg.org/spec/DMN/1.3/PDF) with some additional extensions.
+
+FEEL expressions are parsed into an abstract syntax tree (AST) and then evaluated in a context. The context is a hash of variables and functions to be resolved inside the expression.
+
+Expressions are safe, side-effect free, and deterministic. They are ideal for capturing business logic for storage in a database or embedded in DMN, BPMN, or Form documents for execution in a workflow engine like [Spot Flow](https://github.com/connectedbits/spot-flow).
+
+This project was inspired by these excellent libraries:
+
+- [feelin](https://github.com/nikku/feelin)
+- [dmn-eval-js](https://github.com/mineko-io/dmn-eval-js)
+
+## Usage
+
+To evaluate an expression:
+
+```ruby
+SpotFeel.evaluate('"👋 Hello " + name', variables: { name: "World" })
+# => "👋 Hello World"
+```
+
+A slightly more complex example:
+
+```ruby
+variables = {
+  person: {
+    name: "Eric",
+    age: 59,
+  }
+}
+SpotFeel.evaluate('if person.age >= 18 then "adult" else "minor"', variables:)
+# => "adult"
+```
+
+Calling a built-in function:
+
+```ruby
+SpotFeel.evaluate('sum([1, 2, 3])')
+# => 6
+```
+
+Calling a user-defined function:
+
+```ruby
+SpotFeel.config.functions = {
+  "reverse": ->(s) { s.reverse }
+}
+SpotFeel.evaluate('reverse("Hello World!")', functions:)
+# => "!dlroW olleH"
+```
+
+To evaluate a unary tests:
+
+```ruby
+SpotFeel.test(3, '<= 10, > 50'))
+# => true
+```
+
+```ruby
+SpotFeel.test("Eric", '"Bob", "Holly", "Eric"')
+# => true
+```
+
+![Decision Table](docs/media/decision_table.png)
+
+To evaluate a DMN decision table:
+
+```ruby
+variables = {
+  violation: {
+    type: "speed",
+    actual_speed: 100,
+    speed_limit: 65,
+  }
+}
+result = SpotFeel.decide('fine_decision', definitions_xml: fixture_source("fine.dmn"), variables:)
+# => { "amount" => 1000, "points" => 7 })
+```
+
+To get a list of variables or functions used in an expression:
+
+```ruby
+LiteralExpression.new(text: 'person.first_name + " " + person.last_name').variable_names
+# => ["person.age, person.last_name"]
+```
+
+```ruby
+LiteralExpression.new(text: 'sum([1, 2, 3])').function_names
+# => ["sum"]
+```
+
+```ruby
+UnaryTests.new(text: '> speed - speed_limit').variable_names
+# => ["speed, speed_limit"]
+```
+
+## Supported Features
+
+### Data Types
+
+- [x] Boolean (true, false)
+- [x] Number (integer, decimal)
+- [x] String (single and double quoted)
+- [x] Date, Time, Duration (ISO 8601)
+- [x] List (array)
+- [x] Context (hash)
+
+### Expressions
+
+- [x] Literal
+- [x] Path
+- [x] Arithmetic
+- [x] Comparison
+- [x] Function Invocation
+- [x] Positional Parameters
+- [x] If Expression
+- [ ] For Expression
+- [ ] Quantified Expression
+- [ ] Filter Expression
+- [ ] Disjunction
+- [ ] Conjuction
+- [ ] Instance Of
+- [ ] Function Definition
+
+### Unary Tests
+
+- [x] Comparison
+- [x] Interval/Range (inclusive and exclusive)
+- [x] Disjunction
+- [x] Negation
+- [ ] Expression
+
+### Built-in Functions
+
+- [x] Conversion: `string`, `number`
+- [x] Boolean: `is defined`, `get or else`
+- [x] String: `substring`, `substring before`, `substring after`, `string length`, `upper case`, `lower case`, `contains`, `starts with`, `ends with`, `matches`, `replace`, `split`, `strip`, `extract`
+- [x] Numeric: `decimal`, `floor`, `ceiling`, `round`, `abs`, `modulo`, `sqrt`, `log`, `exp`, `odd`, `even`, `random number`
+- [x] List: `list contains`, `count`, `min`, `max`, `sum`, `product`, `mean`, `median`, `stddev`, `mode`, `all`, `any`, `sublist`, `append`, `concatenate`, `insert before`, `remove`, `reverse`, `index of`, `union`, `distinct values`, `duplicate values`, `flatten`, `sort`, `string join`
+- [x] Context: `get entries`, `get value`, `get keys`
+- [x] Temporal: `now`, `today`, `day of week`, `day of year`, `month of year`, `week of year`
+
+### DMN
+
+- [x] Parse DMN XML documents
+- [x] Evaluate DMN Decision Tables
+- [x] Evaluate dependent DMN Decision Tables
+- [x] Evaluate Expression Decisions
+
+## Installation
+
+Execute:
+
+```bash
+$ bundle add "spot_feel"
+```
+
+Or install it directly:
+
+```bash
+$ gem install spot_feel
+```
+
+### Setup
+
+```bash
+$ git clone ...
+$ bin/setup
+$ bin/guard
+```
+
+## Development
+
+[Treetop Doumentation](https://cjheath.github.io/treetop/syntactic_recognition.html) is a good place to start learning about Treetop.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Developed by [Connected Bits](http://www.connectedbits.com)

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/spot_feel/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  class Configuration
+    attr_accessor :functions, :strict
+
+    def initialize
+      @functions = HashWithIndifferentAccess.new
+      @strict = false
+    end
+  end
+end

data/lib/spot_feel/dmn/decision.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  module Dmn
+    class Decision
+      attr_reader :id, :name, :decision_table, :variable, :literal_expression, :information_requirements
+
+      def self.from_json(json)
+        information_requirements = Array.wrap(json[:information_requirement]).map { |ir| InformationRequirement.from_json(ir) } if json[:information_requirement]
+        decision_table = DecisionTable.from_json(json[:decision_table]) if json[:decision_table]
+        literal_expression = LiteralExpression.from_json(json[:literal_expression]) if json[:literal_expression]
+        variable = Variable.from_json(json[:variable]) if json[:variable]
+        Decision.new(id: json[:id], name: json[:name], decision_table:, variable:, literal_expression:, information_requirements:)
+      end
+
+      def initialize(id:, name:, decision_table:, variable:, literal_expression:, information_requirements:)
+        @id = id
+        @name = name
+        @decision_table = decision_table
+        @variable = variable
+        @literal_expression = literal_expression
+        @information_requirements = information_requirements
+      end
+
+      def evaluate(variables = {})
+        if literal_expression.present?
+          result = literal_expression.evaluate(variables)
+          variable.present? ? { variable.name => result } : result
+        elsif decision_table.present?
+          decision_table.evaluate(variables)
+        end
+      end
+
+      def required_decision_ids
+        information_requirements&.map(&:required_decision_id)
+      end
+
+      def as_json
+        {
+          id: id,
+          name: name,
+          decision_table: decision_table.as_json,
+          variable: variable.as_json,
+          literal_expression: literal_expression.as_json,
+          information_requirements: information_requirements&.map(&:as_json),
+        }
+      end
+    end
+  end
+end

data/lib/spot_feel/dmn/decision_table.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  module Dmn
+    class DecisionTable
+      attr_reader :id, :hit_policy, :inputs, :outputs, :rules
+
+      def self.from_json(json)
+        inputs = Array.wrap(json[:input]).map { |input| Input.from_json(input) }
+        outputs = Array.wrap(json[:output]).map { |output| Output.from_json(output) }
+        rules = Array.wrap(json[:rule]).map { |rule| Rule.from_json(rule) }
+        DecisionTable.new(id: json[:id], hit_policy: json[:hit_policy], inputs: inputs, outputs: outputs, rules: rules)
+      end
+
+      def initialize(id:, hit_policy:, inputs:, outputs:, rules:)
+        @id = id
+        @hit_policy = hit_policy&.downcase&.to_sym || :unique
+        @inputs = inputs
+        @outputs = outputs
+        @rules = rules
+      end
+
+      def evaluate(variables = {})
+        output_values = []
+
+        input_values = inputs.map do |input|
+          input.input_expression.evaluate(variables)
+        end
+
+        rules.each do |rule|
+          results = rule.evaluate(input_values, variables)
+          if results.all?
+            output_value = rule.output_value(outputs, variables)
+            return output_value if hit_policy == :first || hit_policy == :unique
+            output_values << output_value
+          end
+        end
+
+        output_values.empty? ? nil : output_values
+      end
+
+      def as_json
+        {
+          id: id,
+          hit_policy: hit_policy,
+          inputs: inputs.map(&:as_json),
+          outputs: outputs.map(&:as_json),
+          rules: rules.map(&:as_json),
+        }
+      end
+    end
+  end
+end

data/lib/spot_feel/dmn/definitions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  module Dmn
+    class Definitions
+      attr_reader :id, :name, :namespace, :exporter, :exporter_version, :execution_platform, :execution_platform_version
+      attr_reader :decisions
+
+      def self.from_xml(xml)
+        XmlHasher.configure do |config|
+          config.snakecase = true
+          config.ignore_namespaces = true
+          config.string_keys = false
+        end
+        json = XmlHasher.parse(xml)
+        Definitions.from_json(json[:definitions])
+      end
+
+      def self.from_json(json)
+        decisions = Array.wrap(json[:decision]).map { |decision| Decision.from_json(decision) }
+        Definitions.new(id: json[:id], name: json[:name], namespace: json[:namespace], exporter: json[:exporter], exporter_version: json[:exporter_version], execution_platform: json[:execution_platform], execution_platform_version: json[:execution_platform_version], decisions: decisions)
+      end
+
+      def initialize(id:, name:, namespace:, exporter:, exporter_version:, execution_platform:, execution_platform_version:, decisions:)
+        @id = id
+        @name = name
+        @namespace = namespace
+        @exporter = exporter
+        @exporter_version = exporter_version
+        @execution_platform = execution_platform
+        @execution_platform_version = execution_platform_version
+        @decisions = decisions
+      end
+
+      def evaluate(decision_id, variables: {}, already_evaluated_decisions: {})
+        decision = decisions.find { |d| d.id == decision_id }
+        raise EvaluationError, "Decision #{decision_id} not found" unless decision
+
+        # Evaluate required decisions recursively
+        decision.required_decision_ids&.each do |required_decision_id|
+          next if already_evaluated_decisions[required_decision_id]
+          next if decisions.find { |d| d.id == required_decision_id }.nil?
+
+          result = evaluate(required_decision_id, variables:, already_evaluated_decisions:)
+
+          variables.merge!(result) if result.is_a?(Hash)
+
+          already_evaluated_decisions[required_decision_id] = true
+        end
+
+        decision.evaluate(variables)
+      end
+
+      def as_json
+        {
+          id: id,
+          name: name,
+          namespace: namespace,
+          exporter: exporter,
+          exporter_version: exporter_version,
+          execution_platform: execution_platform,
+          execution_platform_version: execution_platform_version,
+          decisions: decisions.map(&:as_json),
+        }
+      end
+    end
+  end
+end

data/lib/spot_feel/dmn/information_requirement.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  module Dmn
+    class InformationRequirement
+      attr_reader :id, :required_input_id, :required_decision_id
+
+      def self.from_json(json)
+        required_input_id = json[:required_input][:href].delete_prefix("#") if json[:required_input]
+        required_decision_id = json[:required_decision][:href].delete_prefix("#") if json[:required_decision]
+        InformationRequirement.new(id: json[:id], required_input_id: required_input_id, required_decision_id: required_decision_id)
+      end
+
+      def initialize(id:, required_input_id:, required_decision_id:)
+        @id = id
+        @required_input_id = required_input_id
+        @required_decision_id = required_decision_id
+      end
+
+      def as_json
+        {
+          id: id,
+          required_decision_id: required_decision_id,
+          required_input_id: required_input_id,
+        }
+      end
+    end
+  end
+end

data/lib/spot_feel/dmn/input.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SpotFeel
+  module Dmn
+    class Input
+      attr_reader :id, :label, :input_expression
+
+      def self.from_json(json)
+        input_expression = LiteralExpression.from_json(json[:input_expression]) if json[:input_expression]
+        Input.new(id: json[:id], label: json[:label], input_expression:)
+      end
+
+      def initialize(id:, label:, input_expression:)
+        @id = id
+        @label = label
+        @input_expression = input_expression
+      end
+
+      def as_json
+        {
+          id: id,
+          label: label,
+          input_expression: input_expression.as_json,
+        }
+      end
+    end
+  end
+end