dentaku 1.2.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3007daa3af2e8cf5e738f4d98d046f23422004e3
-  data.tar.gz: 7994b1e07961a589580275cfb14978a9fb6ab091
+  metadata.gz: 85e18c02f88a1fc906c69667776e00ccb1f969f5
+  data.tar.gz: 6fba624e3b93a4e64e2ce55fb6fe13f42d9138be
 SHA512:
-  metadata.gz: b5287d0c47550c976e373a1b291526e79da3fae5aa4e78ebd6e479e3ee467a701f577b45d9acacf9949466186f429f6b9d0ec211917a776e0e29230bba6075d7
-  data.tar.gz: f7ac853d45ed2a50b3b5d0b4ee8cab110db7adea2dce84f291a328051a19da1c955e058d2d68d23ea1cb367deac0387b94b6039b836f7310a625a7a599861236
+  metadata.gz: befe922779a83e64b95ed17907846a29901c59badb2810d2c28f2555aabc5359f7a21a1aeac6cca12b63c39bb59dad225ce233bfccc59b91af9eea027f3ab3cf
+  data.tar.gz: 2bac8daaa567d69860f8c5d00ed52375f989bde4893bb7b405ca513c257edf987a742ea7dc97d5817d8fa6023a82a77040bd69e17ca487c4f2fc45c8c6fba4e1

data/README.md

@@ -1,6 +1,7 @@
 Dentaku
 =======
 
+[![Join the chat at https://gitter.im/rubysolo/dentaku](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/rubysolo/dentaku?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Gem Version](https://badge.fury.io/rb/dentaku.png)](http://badge.fury.io/rb/dentaku)
 [![Build Status](https://travis-ci.org/rubysolo/dentaku.png?branch=master)](https://travis-ci.org/rubysolo/dentaku)
 [![Code Climate](https://codeclimate.com/github/rubysolo/dentaku.png)](https://codeclimate.com/github/rubysolo/dentaku)
@@ -66,10 +67,9 @@ 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:
+Dentaku has built-in functions (including `if`, `not`, `min`, `max`, and
+`round`) and the ability to define custom functions (see below). Functions
+generally work like their counterparts in Excel:
 
 ```ruby
 calculator.evaluate('if (pears < 10, 10, 20)', pears: 5)
@@ -78,7 +78,7 @@ calculator.evaluate('if (pears < 10, 10, 20)', pears: 15)
 #=> 20
 ```
 
-`round`, `rounddown`, and `roundup` can be called with or without the number of decimal places:
+`round` can be called with or without the number of decimal places:
 
 ```ruby
 calculator.evaluate('round(8.2)')
@@ -87,7 +87,8 @@ calculator.evaluate('round(8.2759, 2)')
 #=> 8.28
 ```
 
-`round` and `rounddown` round down, while `roundup` rounds up.
+`round` follows rounding rules, while `roundup` and `rounddown` are `ceil` and
+`floor`, respectively.
 
 If you're too lazy to be building calculator objects, there's a shortcut just
 for you:
@@ -105,7 +106,9 @@ Math: `+ - * / %`
 
 Logic: `< > <= >= <> != = AND OR`
 
-Functions: `IF NOT ROUND ROUNDDOWN ROUNDUP`
+Functions: `IF NOT MIN MAX ROUND ROUNDDOWN ROUNDUP`
+
+Math: all functions from Ruby's Math module, including `SIN, COS, TAN, ...`
 
 RESOLVING DEPENDENCIES
 ----------------------
@@ -125,7 +128,7 @@ need_to_compute = {
 In the example, `annual_income` needs to be computed (and stored) before
 `income_taxes`.
 
-Dentaku provides two methods to help resolve formulas in order`:
+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
@@ -144,7 +147,7 @@ calc.dependencies("annual_income / 5")
 #### 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
+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.
@@ -153,7 +156,7 @@ Raises `TSort::Cyclic` when a valid expression order cannot be found.
 calc = Dentaku::Calculator.new
 calc.store(monthly_income: 50)
 need_to_compute = {
-  income_taxes: "annual_income / 5",
+  income_taxes:  "annual_income / 5",
   annual_income: "monthly_income * 12"
 }
 calc.solve!(need_to_compute)
@@ -166,6 +169,29 @@ calc.solve!(
 #=> raises TSort::Cyclic
 ```
 
+INLINE COMMENTS
+---------------------------------
+
+If your expressions grow long or complex, you may add inline comments for future
+reference. This is particularly useful if you save your expressions in a model.
+
+```ruby
+calculator.evaluate('kiwi + 5 /* This is a comment */', kiwi: 2)
+#=> 7
+```
+
+Comments can be single or multi-line. The following are also valid.
+
+```
+/*
+ * This is a multi-line comment
+ */
+
+/*
+ This is another type of multi-line comment
+ */
+```
+
 EXTERNAL FUNCTIONS
 ------------------
 
@@ -174,69 +200,39 @@ need.  Please implement your favorites and send a pull request!  Okay, so maybe
 that's not feasible because:
 
 1. You can't be bothered to share
-2. You can't wait for me to respond to a pull request, you need it `NOW()`
-3. The formula is the secret sauce for your startup
+1. You can't wait for me to respond to a pull request, you need it `NOW()`
+1. The formula is the secret sauce for your startup
 
 Whatever your reasons, Dentaku supports adding functions at runtime.  To add a
-function, you'll need to specify:
-
-* Name
-* Return type
-* Signature
-* Body
-
-Naming can be the hardest part, so you're on your own for that.
-
-`:type` specifies the type of value that will be returned, most likely
-`:numeric`, `:string`, or `:logical`.
-
-`:signature` specifies the types and order of the parameters for your function.
+function, you'll need to specify a name and a lambda that accepts all function
+arguments and returns the result value.
 
-`:body` is a lambda that implements your function.  It is passed the arguments
-and should return the calculated value.
-
-As an example, the exponentiation function takes two parameters, the mantissa
-and the exponent, so the token list could be defined as: `[:numeric,
-:numeric]`.  Other functions might be variadic -- consider `max`, a function
-that takes any number of numeric inputs and returns the largest one.  Its token
-list could be defined as: `[:arguments]` (one or more numeric, string, or logical
-values, separated by commas).  See the
-[rules definitions](https://github.com/rubysolo/dentaku/blob/master/lib/dentaku/token_matcher.rb#L87)
-for the names of token patterns you can use.
-
-Functions can be added individually using Calculator#add_function, or en masse using
-Calculator#add_functions.
-
-Here's an example of adding the `exp` function:
+Here's an example of adding a function named `POW` that implements
+exponentiation.
 
 ```ruby
 > c = Dentaku::Calculator.new
-> c.add_function(
-    name: :exp,
-    type: :numeric,
-    signature: [:numeric, :numeric],
-    body: ->(mantissa, exponent) { mantissa ** exponent }
-  )
-> c.evaluate('EXP(3,2)')
+> c.add_function(:pow, ->(mantissa, exponent) { mantissa ** exponent })
+> c.evaluate('POW(3,2)')
 #=> 9
-> c.evaluate('EXP(2,3)')
+> c.evaluate('POW(2,3)')
 #=> 8
 ```
 
-Here's an example of adding the `max` function:
+Here's an example of adding a variadic function:
 
 ```ruby
 > c = Dentaku::Calculator.new
-> c.add_function(
-    name: :max,
-    type: :numeric,
-    signature: [:arguments],
-    body: ->(*args) { args.max }
-  )
+> c.add_function(:max, ->(*args) { args.max })
 > c.evaluate 'MAX(8,6,7,5,3,0,9)'
 #=> 9
 ```
 
+(However both of these are already built-in -- the `^` operator and the `MAX`
+function)
+
+Functions can be added individually using Calculator#add_function, or en masse
+using Calculator#add_functions.
 
 THANKS
 ------
@@ -283,4 +279,3 @@ 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/Rakefile

@@ -5,7 +5,7 @@ desc "Run specs"
 task :spec do
   RSpec::Core::RakeTask.new(:spec) do |t|
     t.rspec_opts = %w{--colour --format progress}
-    t.pattern = 'spec/*_spec.rb'
+    t.pattern = 'spec/**/*_spec.rb'
   end
 end
 

data/lib/dentaku.rb

@@ -7,6 +7,14 @@ module Dentaku
     calculator.evaluate(expression, data)
   end
 
+  def self.enable_ast_cache!
+    @enable_ast_caching = true
+  end
+
+  def self.cache_ast?
+    @enable_ast_caching
+  end
+
   private
 
   def self.calculator

data/lib/dentaku/ast.rb

@@ -0,0 +1,22 @@
+require_relative './ast/node'
+require_relative './ast/nil'
+require_relative './ast/numeric'
+require_relative './ast/string'
+require_relative './ast/identifier'
+require_relative './ast/addition'
+require_relative './ast/subtraction'
+require_relative './ast/multiplication'
+require_relative './ast/division'
+require_relative './ast/exponentiation'
+require_relative './ast/negation'
+require_relative './ast/comparators'
+require_relative './ast/combinators'
+require_relative './ast/grouping'
+require_relative './ast/functions/if'
+require_relative './ast/functions/max'
+require_relative './ast/functions/min'
+require_relative './ast/functions/not'
+require_relative './ast/functions/round'
+require_relative './ast/functions/roundup'
+require_relative './ast/functions/rounddown'
+require_relative './ast/functions/ruby_math'

data/lib/dentaku/ast/addition.rb

@@ -0,0 +1,15 @@
+require_relative './operation'
+
+module Dentaku
+  module AST
+    class Addition < Operation
+      def value(context={})
+        left.value(context) + right.value(context)
+      end
+
+      def self.precedence
+        10
+      end
+    end
+  end
+end

data/lib/dentaku/ast/combinators.rb

@@ -0,0 +1,15 @@
+module Dentaku
+  module AST
+    class And < Operation
+      def value(context={})
+        left.value(context) && right.value(context)
+      end
+    end
+
+    class Or < Operation
+      def value(context={})
+        left.value(context) || right.value(context)
+      end
+    end
+  end
+end

data/lib/dentaku/ast/comparators.rb

@@ -0,0 +1,47 @@
+require_relative './operation'
+
+module Dentaku
+  module AST
+    class Comparator < Operation
+      def self.precedence
+        5
+      end
+    end
+
+    class LessThan < Comparator
+      def value(context={})
+        left.value(context) < right.value(context)
+      end
+    end
+
+    class LessThanOrEqual < Comparator
+      def value(context={})
+        left.value(context) <= right.value(context)
+      end
+    end
+
+    class GreaterThan < Comparator
+      def value(context={})
+        left.value(context) > right.value(context)
+      end
+    end
+
+    class GreaterThanOrEqual < Comparator
+      def value(context={})
+        left.value(context) >= right.value(context)
+      end
+    end
+
+    class NotEqual < Comparator
+      def value(context={})
+        left.value(context) != right.value(context)
+      end
+    end
+
+    class Equal < Comparator
+      def value(context={})
+        left.value(context) == right.value(context)
+      end
+    end
+  end
+end

data/lib/dentaku/ast/division.rb

@@ -0,0 +1,15 @@
+require_relative './operation'
+
+module Dentaku
+  module AST
+    class Division < Operation
+      def value(context={})
+        left.value(context) / right.value(context)
+      end
+
+      def self.precedence
+        20
+      end
+    end
+  end
+end

data/lib/dentaku/ast/exponentiation.rb

@@ -0,0 +1,15 @@
+require_relative './operation'
+
+module Dentaku
+  module AST
+    class Exponentiation < Operation
+      def value(context={})
+        left.value(context) ** right.value(context)
+      end
+
+      def self.precedence
+        30
+      end
+    end
+  end
+end

data/lib/dentaku/ast/function.rb

@@ -0,0 +1,54 @@
+require_relative 'node'
+
+module Dentaku
+  module AST
+    class Function < Node
+      def initialize(*args)
+        @args = args
+      end
+
+      def dependencies(context={})
+        @args.flat_map { |a| a.dependencies(context) }
+      end
+
+      def self.get(name)
+        registry.fetch(function_name(name)) { fail "Undefined function #{ name } "}
+      end
+
+      def self.register(name, implementation)
+        function = Class.new(self) do
+          def self.implementation=(impl)
+            @implementation = impl
+          end
+
+          def self.implementation
+            @implementation
+          end
+
+          def value(context={})
+            args = @args.flat_map { |a| a.value(context) }
+            self.class.implementation.call(*args)
+          end
+        end
+
+        function.implementation = implementation
+
+        registry[function_name(name)] = function
+      end
+
+      def self.register_class(name, function_class)
+        registry[function_name(name)] = function_class
+      end
+
+      private
+
+      def self.function_name(name)
+        name.to_s.downcase
+      end
+
+      def self.registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/dentaku/ast/functions/if.rb

@@ -0,0 +1,26 @@
+require_relative '../function'
+
+module Dentaku
+  module AST
+    class If < Function
+      attr_reader :predicate, :left, :right
+
+      def initialize(predicate, left, right)
+        @predicate = predicate
+        @left      = left
+        @right     = right
+      end
+
+      def value(context={})
+        predicate.value(context) ? left.value(context) : right.value(context)
+      end
+
+      def dependencies(context={})
+        # TODO : short-circuit?
+        (predicate.dependencies(context) + left.dependencies(context) + right.dependencies(context)).uniq
+      end
+    end
+  end
+end
+
+Dentaku::AST::Function.register_class(:if, Dentaku::AST::If)