dentaku 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e51005fddbd5c542da8892bb3db03358e7d4cdf
-  data.tar.gz: 7c13a0a048a14e5bb40151224a95f7a2635ae9fa
+  metadata.gz: 064d1f2a40ca1fa6caf9b07f5fb535a673fcbe32
+  data.tar.gz: 0fe2cb4349c5423da447fa81173d3b70636bacff
 SHA512:
-  metadata.gz: 46026444a4b39bdc8df5f8913422619ac54b52d671e030b5599aa2db9642beabfdfd0c4e79ac9f40dc211de34e3ec791420aed2e162f86dd373c460229e6350a
-  data.tar.gz: 14409916459c8b1481e6f9e1005bd7c2bf49f9c84e7b29a3a97cc2161d92bf0615bde9b3b08005e177e9fcd188d76298324041fd54b36f966961e52ee4ecdf4f
+  metadata.gz: 55fdf11b6a81a851c4d5db09bd2d1ee3385d7ca0f08d2ba806bb9cf9dc914acda0b90d38b817353d28ab99c1b89b198a7d10e998360b2870ca04d485616a97cf
+  data.tar.gz: f68bc08dd8d1ff2f3d4e79f5af7f3131b59ce539d2001360e78c8fe340421f993c6e67d4ea1490b69928861c19b74615caea09cfd0e74cd251f0affd142eb0bd

data/README.md

@@ -21,7 +21,7 @@ This is probably simplest to illustrate in code:
 ```ruby
 calculator = Dentaku::Calculator.new
 calculator.evaluate('10 * 2')
-=> 20
+#=> 20
 ```
 
 Okay, not terribly exciting.  But what if you want to have a reference to a
@@ -29,7 +29,7 @@ variable, and evaluate it at run-time?  Here's how that would look:
 
 ```ruby
 calculator.evaluate('kiwi + 5', kiwi: 2)
-=> 7
+#=> 7
 ```
 
 You can also store the variable values in the calculator's memory and then
@@ -38,9 +38,9 @@ evaluate expressions against those stored values:
 ```ruby
 calculator.store(peaches: 15)
 calculator.evaluate('peaches - 5')
-=> 10
+#=> 10
 calculator.evaluate('peaches >= 15')
-=> true
+#=> true
 ```
 
 For maximum CS geekery, `bind` is an alias of `store`.
@@ -50,29 +50,41 @@ to ensure proper evaluation:
 
 ```ruby
 calculator.evaluate('5 + 3 * 2')
-=> 11
+#=> 11
 calculator.evaluate('(5 + 3) * 2')
-=> 16
+#=> 16
+```
+
+The `evalutate` method will return `nil` if there is an error in the formula.
+If this is not the desired behavior, use `evaluate!`, which will raise an
+exception.
+
+```ruby
+calculator.evaluate('10 * x')
+#=> nil
+calculator.evaluate!('10 * x')
+Dentaku::UnboundVariableError: Dentaku::UnboundVariableError
 ```
 
 A number of functions are also supported.  Okay, the number is currently five,
 but more will be added soon.  The current functions are
-`if`, `not`, `round`, `rounddown`, and `roundup`, and they work like their counterparts in Excel:
+`if`, `not`, `round`, `rounddown`, and `roundup`, and they work like their
+counterparts in Excel:
 
 ```ruby
 calculator.evaluate('if (pears < 10, 10, 20)', pears: 5)
-=> 10
+#=> 10
 calculator.evaluate('if (pears < 10, 10, 20)', pears: 15)
-=> 20
+#=> 20
 ```
 
 `round`, `rounddown`, and `roundup` can be called with or without the number of decimal places:
 
 ```ruby
 calculator.evaluate('round(8.2)')
-=> 8
+#=> 8
 calculator.evaluate('round(8.2759, 2)')
-=> 8.28
+#=> 8.28
 ```
 
 `round` and `rounddown` round down, while `roundup` rounds up.
@@ -82,7 +94,7 @@ for you:
 
 ```ruby
 Dentaku('plums * 1.5', plums: 2)
-=> 3.0
+#=> 3.0
 ```
 
 
@@ -95,6 +107,64 @@ Logic: `< > <= >= <> != = AND OR`
 
 Functions: `IF NOT ROUND ROUNDDOWN ROUNDUP`
 
+RESOLVING DEPENDENCIES
+----------------------
+
+If your formulas rely on one another, they may need to be resolved in a
+particular order. For example:
+
+```ruby
+calc = Dentaku::Calculator.new
+calc.store(monthly_income: 50)
+need_to_compute = {
+  income_taxes: "annual_income / 5",
+  annual_income: "monthly_income * 12"
+}
+```
+
+In the example, `annual_income` needs to be computed (and stored) before
+`income_taxes`.
+
+Dentaku provides two methods to help resolve formulas in order`:
+
+#### Calculator.dependencies
+Pass a (string) expression to Dependencies and get back a list of variables (as
+`:symbols`) that are required for the expression. `Dependencies` also takes
+into account variables already (explicitly) stored into the calculator.
+
+```ruby
+calc.dependencies("monthly_income * 12")
+#=> []
+# (since monthly_income is in memory)
+
+calc.dependencies("annual_income / 5")
+#=> [:annual_income]
+```
+
+#### Calculator.solve!
+Have Dentaku figure out the order in which your formulas need to be evaluated.
+
+Pass in a hash of {eventual_variable_name: "expression"} to `solve!` and
+have Dentaku figure out dependencies (using `TSort`) for you.
+
+Raises `TSort::Cyclic` when a valid expression order cannot be found.
+
+```ruby
+calc = Dentaku::Calculator.new
+calc.store(monthly_income: 50)
+need_to_compute = {
+  income_taxes: "annual_income / 5",
+  annual_income: "monthly_income * 12"
+}
+calc.solve!(need_to_compute)
+#=> {annual_income: 600, income_taxes: 120}
+
+calc.solve!(
+  make_money: "have_money",
+  have_money: "make_money"
+}
+#=> raises TSort::Cyclic
+```
 
 EXTERNAL FUNCTIONS
 ------------------
@@ -148,9 +218,9 @@ Here's an example of adding the `exp` function:
     body: ->(mantissa, exponent) { mantissa ** exponent }
   )
 > c.evaluate('EXP(3,2)')
-=> 9
+#=> 9
 > c.evaluate('EXP(2,3)')
-=> 8
+#=> 8
 ```
 
 Here's an example of adding the `max` function:
@@ -164,7 +234,7 @@ Here's an example of adding the `max` function:
     body: ->(*args) { args.max }
   )
 > c.evaluate 'MAX(5,3,9,6,2)'
-=> 9
+#=> 9
 ```
 
 
@@ -182,6 +252,7 @@ contributors:
 * [mvbrocato](https://github.com/mvbrocato)
 * [brixen](https://github.com/brixen)
 * [0xCCD](https://github.com/0xCCD)
+* [AlexeyMK](https://github.com/AlexeyMK)
 
 
 LICENSE

data/lib/dentaku/calculator.rb

@@ -2,6 +2,7 @@ require 'dentaku/evaluator'
 require 'dentaku/expression'
 require 'dentaku/rules'
 require 'dentaku/token'
+require 'dentaku/dependency_resolver'
 
 module Dentaku
   class Calculator
@@ -36,10 +37,31 @@ module Dentaku
       end
     end
 
+    def solve!(expression_hash)
+      # expression_hash: { variable_name: "string expression" }
+      # TSort thru the expressions' dependencies, then evaluate all
+      expression_dependencies = Hash[expression_hash.map do |var, expr|
+        [var, dependencies(expr)]
+      end]
+      variables_in_resolve_order = DependencyResolver::find_resolve_order(
+        expression_dependencies)
+
+      results = {}
+      variables_in_resolve_order.each do |var_name|
+        results[var_name] = evaluate!(expression_hash[var_name], results)
+      end
+
+      results
+    end
+
+    def dependencies(expression)
+      Expression.new(expression, @memory).identifiers
+    end
+
     def store(key_or_hash, value=nil)
       restore = @memory.dup
 
-      if value
+      if !value.nil?
         @memory[key_or_hash.to_sym] = value
       else
         key_or_hash.each do |key, value|

data/lib/dentaku/dependency_resolver.rb

@@ -0,0 +1,24 @@
+require 'tsort'
+
+module Dentaku
+  class DependencyResolver
+    include TSort
+
+    def self.find_resolve_order(vars_to_dependencies_hash)
+      self.new(vars_to_dependencies_hash).tsort
+    end
+
+    def initialize(vars_to_dependencies_hash)
+      # ensure variables are symbols
+      @vars_to_deps = Hash[vars_to_dependencies_hash.map { |k, v| [k.to_sym, v]}]
+    end
+
+    def tsort_each_node(&block)
+      @vars_to_deps.each_key(&block)
+    end
+
+    def tsort_each_child(node, &block)
+      @vars_to_deps[node.to_sym].each(&block)
+    end
+  end
+end

data/lib/dentaku/version.rb

@@ -1,3 +1,3 @@
 module Dentaku
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/calculator_spec.rb

@@ -17,6 +17,42 @@ describe Dentaku::Calculator do
       expect(calculator.evaluate('pears * 2', :pears => 5)).to eq(10)
       expect(calculator).to be_empty
     end
+
+    it 'can store the value `false`' do
+      calculator.store('i_am_false', false)
+      expect(calculator.evaluate!('i_am_false')).to eq false
+    end
+
+    it 'can store multiple values' do
+      calculator.store(first: 1, second: 2)
+      expect(calculator.evaluate!('first')).to eq 1
+      expect(calculator.evaluate!('second')).to eq 2
+    end
+  end
+
+  describe 'dependencies' do
+    it "finds dependencies in a generic statement" do
+      expect(calculator.dependencies("bob + dole / 3")).to eq([:bob, :dole])
+    end
+    it "doesn't consider variables in memory as dependencies" do
+      expect(with_memory.dependencies("apples + oranges")).to eq([:oranges])
+    end
+  end
+
+  describe 'solve!' do
+    it "evaluates properly with variables, even if some in memory" do
+      expect(with_memory.solve!(
+        weekly_fruit_budget: "weekly_apple_budget + pear * 4",
+        weekly_apple_budget: "apples * 7",
+        pear: "1"
+      )).to eq(pear: 1, weekly_apple_budget: 21, weekly_fruit_budget: 25)
+    end
+
+    it "lets you know about a cycle if one occurs" do
+      expect do
+        calculator.solve!(health: "happiness", happiness: "health")
+      end.to raise_error (TSort::Cyclic)
+    end
   end
 
   it 'evaluates a statement with no variables' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dentaku
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Solomon White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-31 00:00:00.000000000 Z
+date: 2014-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -55,6 +55,7 @@ files:
 - lib/dentaku.rb
 - lib/dentaku/binary_operation.rb
 - lib/dentaku/calculator.rb
+- lib/dentaku/dependency_resolver.rb
 - lib/dentaku/evaluator.rb
 - lib/dentaku/expression.rb
 - lib/dentaku/external_function.rb
@@ -95,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: dentaku
-rubygems_version: 2.2.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A formula language parser and evaluator