dentaku 0.2.14 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2786a55545e9a2472089d941fa6611aea6124991
-  data.tar.gz: 312eacef50b85dac484b9166c378a7ca359d305c
+  metadata.gz: 93d875177f2fb6231220227687ce2fa8cfb01a83
+  data.tar.gz: 2bfd4229e677bacb4838f101180574def2d1941b
 SHA512:
-  metadata.gz: fdd35ea4a57f82c6f3c1f9e65ae28fa73d2862e7729225ce714b976466650a2e09473ea3a25c06a18fbaa76e8665294526fed8a3451649140855b79f38337a31
-  data.tar.gz: ea460a2b63b8318bb03a51ecb6c1370794da332395241357f2b486d2495e4079489894a7271b96d4464fac734c4af96caced5cdd3248505726e0841604a6f05c
+  metadata.gz: 95daa0fa7ff7bc708492f0747ef33601c555b32a441f5b50b13c8201edbc3f76d0d606cdd8057ee408e271a9869f1ff1a34ca8219d19e2bd00fc5119c52ea311
+  data.tar.gz: 25e9184f6f077d7af863e434dbdbd87e505cf44d4fd3baf9c1a69400de77912f31b39ff48ad94f412ac3e759acd3a5ead9943837484b8555cc83d9e333a3a6e4

data/README.md

@@ -5,8 +5,6 @@ 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)
 
-http://github.com/rubysolo/dentaku
-
 DESCRIPTION
 -----------
 
@@ -19,97 +17,152 @@ EXAMPLE
 
 This is probably simplest to illustrate in code:
 
-    calculator = Dentaku::Calculator.new
-    calculator.evaluate('10 * 2')
-    => 20
+```ruby
+calculator = Dentaku::Calculator.new
+calculator.evaluate('10 * 2')
+=> 20
+```
 
 Okay, not terribly exciting.  But what if you want to have a reference to a
 variable, and evaluate it at run-time?  Here's how that would look:
 
-    calculator.evaluate('kiwi + 5', :kiwi => 2)
-    => 7
+```ruby
+calculator.evaluate('kiwi + 5', kiwi: 2)
+=> 7
+```
 
 You can also store the variable values in the calculator's memory and then
 evaluate expressions against those stored values:
 
-    calculator.store(:peaches => 15)
-    calculator.evaluate('peaches - 5')
-    => 10
-    calculator.evaluate('peaches >= 15')
-    => true
+```ruby
+calculator.store(peaches: 15)
+calculator.evaluate('peaches - 5')
+=> 10
+calculator.evaluate('peaches >= 15')
+=> true
+```
 
 For maximum CS geekery, `bind` is an alias of `store`.
 
 Dentaku understands precedence order and using parentheses to group expressions
 to ensure proper evaluation:
 
-    calculator.evaluate('5 + 3 * 2')
-    => 11
-    calculator.evaluate('(5 + 3) * 2')
-    => 16
+```ruby
+calculator.evaluate('5 + 3 * 2')
+=> 11
+calculator.evaluate('(5 + 3) * 2')
+=> 16
+```
 
 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:
 
-    calculator.evaluate('if (pears < 10, 10, 20)', :pears => 5)
-    => 10
-    calculator.evaluate('if (pears < 10, 10, 20)', :pears => 15)
-    => 20
+```ruby
+calculator.evaluate('if (pears < 10, 10, 20)', pears: 5)
+=> 10
+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:
 
-    calculator.evaluate('round(8.2)')
-    => 8
-    calculator.evaluate('round(8.2759, 2)')
-    => 8.28
+```ruby
+calculator.evaluate('round(8.2)')
+=> 8
+calculator.evaluate('round(8.2759, 2)')
+=> 8.28
+```
 
 `round` and `rounddown` round down, while `roundup` rounds up.
 
 If you're too lazy to be building calculator objects, there's a shortcut just
 for you:
 
-    Dentaku('plums * 1.5', {:plums => 2})
-    => 3.0
+```ruby
+Dentaku('plums * 1.5', plums: 2)
+=> 3.0
+```
 
 
 BUILT-IN OPERATORS AND FUNCTIONS
 ---------------------------------
 
 Math: `+ - * / %`
+
 Logic: `< > <= >= <> != = AND OR`
+
 Functions: `IF NOT ROUND ROUNDDOWN ROUNDUP`
 
 
 EXTERNAL FUNCTIONS
 ------------------
 
-See `spec/external_function_spec.rb` for examples of how to add your own functions.
-
-The short, dense version:
-
-Each rule for an external function consists of three parts: the function's name,
-a list of tokens describing its signature (parameters), and a lambda representing the
-function's body.
-
-The function name should be passed as a symbol (for example, `:func`).
-
-The token list should consist of `:numeric` or `:string` if a single value of the named
-type should be passed; `:non_group` or `:non_group_star` for grouped expressions.
-
-> (what's the difference? when would you use one instead of the other?)
-
-The function body should accept a list of parameters. Each function body will be passed
-a sequence of tokens, in order:
-
-1. The function's name
-2. A token representing the opening parenthesis
-3. Tokens representing the parameter values, separated by tokens representing the commas between parameters
-4. A token representing the closing parenthesis
-
-It should return a token (either `:numeric` or `:string`) representing the return value.
-
-Rules can be set individually using Calculator#add_rule, or en masse using Calculator#add_rules.
+I don't know everything, so I might not have implemented all the functions you
+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
+
+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.
+
+`: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: `[:non_close_plus]` (one or more tokens that are not
+closing parentheses.
+
+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:
+
+```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)')
+=> 9
+> c.evaluate('EXP(2,3)')
+=> 8
+```
+
+Here's an example of adding the `max` function:
+
+```ruby
+> c = Dentaku::Calculator.new
+> c.add_function(
+    name: :max,
+    type: :numeric,
+    signature: [:non_close_plus],
+    body: ->(*args) { args.max }
+  )
+> c.evaluate 'MAX(5,3,9,6,2)'
+=> 9
+```
 
 
 THANKS

data/Rakefile

@@ -10,4 +10,19 @@ task :spec do
 end
 
 desc "Default: run specs."
-task :default => :spec
+task default: :spec
+
+task :console do
+  begin
+    require 'pry'
+    console = Pry
+  rescue LoadError
+    require 'irb'
+    require 'irb/completion'
+    console = IRB
+  end
+
+  require 'dentaku'
+  ARGV.clear
+  console.start
+end

data/lib/dentaku/calculator.rb

@@ -11,13 +11,13 @@ module Dentaku
       clear
     end
 
-    def add_rule(new_rule)
-      Rules.add_rule new_rule
+    def add_function(fn)
+      Rules.add_function(fn)
       self
     end
 
-    def add_rules(new_rules)
-      new_rules.each { | r | Rules.add_rule r }
+    def add_functions(fns)
+      fns.each { |fn| Rules.add_function(fn) }
       self
     end
 

data/lib/dentaku/evaluator.rb

@@ -55,15 +55,25 @@ module Dentaku
 
     def evaluate_step(token_stream, start, length, evaluator)
       expr = token_stream.slice!(start, length)
+
       if self.respond_to?(evaluator)
         token_stream.insert start, *self.send(evaluator, *expr)
       else
         func = Rules.func(evaluator)
         raise "unknown evaluator '#{evaluator.to_s}'" if func.nil?
-        token_stream.insert start, *(func.call(*expr))
+
+        arguments = extract_arguments_from_function_call(expr).map { |t| t.value }
+        return_value = func.body.call(*arguments)
+
+        token_stream.insert start, Token.new(func.type, return_value)
       end
     end
 
+    def extract_arguments_from_function_call(tokens)
+      _function_name, _open, *args_and_commas, _close = tokens
+      args_and_commas.reject { |token| token.is?(:grouping) }
+    end
+
     def evaluate_group(*args)
       evaluate_token_stream(args[1..-2])
     end

data/lib/dentaku/external_function.rb

@@ -0,0 +1,10 @@
+class ExternalFunction < Struct.new(:name, :type, :signature, :body)
+  def initialize(*)
+    super
+    self.name = self.name.to_sym
+  end
+
+  def tokens
+    signature.flat_map { |t| [t, :comma] }[0...-1]
+  end
+end

data/lib/dentaku/rules.rb

@@ -1,3 +1,4 @@
+require 'dentaku/external_function'
 require 'dentaku/token'
 require 'dentaku/token_matcher'
 
@@ -6,8 +7,7 @@ module Dentaku
     def self.core_rules
       [
         [ p(:if),         :if             ],
-        [ p(:round_one),  :round          ],
-        [ p(:round_two),  :round          ],
+        [ p(:round),      :round          ],
         [ p(:roundup),    :round_int      ],
         [ p(:rounddown),  :round_int      ],
         [ p(:not),        :not            ],
@@ -32,22 +32,23 @@ module Dentaku
       @rules.each { |r| yield r }
     end
 
-    def self.add_rule(new_rule)
+    def self.add_function(f)
+      ext = ExternalFunction.new(f[:name], f[:type], f[:signature], f[:body])
+
       @rules ||= core_rules
       @funcs ||= {}
-      name = new_rule[:name].to_sym
 
-      ## rules need to be added to the beginning of @rules; for precedence?
+      ## rules need to be added to the beginning of @rules for precedence
       @rules.unshift [
         [
-          TokenMatcher.send(name),
+          TokenMatcher.send(ext.name),
           t(:open),
-          *pattern(*new_rule[:tokens]),
-          t(:close),
+          *pattern(*ext.tokens),
+          t(:close)
         ],
-        name
+        ext.name
       ]
-      @funcs[name] = new_rule[:body]
+      @funcs[ext.name] = ext
     end
 
     def self.func(name)
@@ -65,7 +66,7 @@ module Dentaku
         :numeric, :string, :addsub, :subtract, :muldiv, :pow, :mod,
         :comparator, :comp_gt, :comp_lt,
         :open, :close, :comma,
-        :non_group, :non_group_star,
+        :non_close_plus, :non_group, :non_group_star,
         :logical, :combinator,
         :if, :round, :roundup, :rounddown, :not
       ].each_with_object({}) do |name, matchers|
@@ -75,25 +76,24 @@ module Dentaku
 
     def self.p(name)
       @patterns ||= {
-        group:      pattern(:open,    :non_group_star, :close),
-        math_add:   pattern(:numeric, :addsub,         :numeric),
-        math_mul:   pattern(:numeric, :muldiv,         :numeric),
-        math_pow:   pattern(:numeric, :pow,            :numeric),
-        math_mod:   pattern(:numeric, :mod,            :numeric),
+        group:      pattern(:open,     :non_group_star, :close),
+        math_add:   pattern(:numeric,  :addsub,         :numeric),
+        math_mul:   pattern(:numeric,  :muldiv,         :numeric),
+        math_pow:   pattern(:numeric,  :pow,            :numeric),
+        math_mod:   pattern(:numeric,  :mod,            :numeric),
         negation:   pattern(:subtract, :numeric),
-        percentage: pattern(:numeric, :mod),
-        range_asc:  pattern(:numeric, :comp_lt,        :numeric,  :comp_lt, :numeric),
-        range_desc: pattern(:numeric, :comp_gt,        :numeric,  :comp_gt, :numeric),
-        num_comp:   pattern(:numeric, :comparator,     :numeric),
-        str_comp:   pattern(:string,  :comparator,     :string),
-        combine:    pattern(:logical, :combinator,     :logical),
+        percentage: pattern(:numeric,  :mod),
+        range_asc:  pattern(:numeric,  :comp_lt,        :numeric,  :comp_lt, :numeric),
+        range_desc: pattern(:numeric,  :comp_gt,        :numeric,  :comp_gt, :numeric),
+        num_comp:   pattern(:numeric,  :comparator,     :numeric),
+        str_comp:   pattern(:string,   :comparator,     :string),
+        combine:    pattern(:logical,  :combinator,     :logical),
 
         if:         func_pattern(:if,        :non_group,      :comma, :non_group, :comma, :non_group),
-        round_one:  func_pattern(:round,     :non_group_star),
-        round_two:  func_pattern(:round,     :non_group_star, :comma, :numeric),
-        roundup:    func_pattern(:roundup,   :non_group_star),
-        rounddown:  func_pattern(:rounddown, :non_group_star),
-        not:        func_pattern(:not,       :non_group_star)
+        round:      func_pattern(:round,     :non_close_plus),
+        roundup:    func_pattern(:roundup,   :non_close_plus),
+        rounddown:  func_pattern(:rounddown, :non_close_plus),
+        not:        func_pattern(:not,       :non_close_plus)
       }
 
       @patterns[name]

data/lib/dentaku/token_matcher.rb

@@ -39,12 +39,12 @@ module Dentaku
 
     def star
       @min = 0
-      @max = 1.0/0
+      @max = Float::INFINITY
       self
     end
 
     def plus
-      @max = 1.0/0
+      @max = Float::INFINITY
       self
     end
 
@@ -78,6 +78,7 @@ module Dentaku
     def self.roundup;        new(:function, :roundup);             end
     def self.rounddown;      new(:function, :rounddown);           end
     def self.not;            new(:function, :not);                 end
+    def self.non_close_plus; new(:grouping, :close).invert.plus;   end
     def self.non_group;      new(:grouping).invert;                end
     def self.non_group_star; new(:grouping).invert.star;           end
 

data/lib/dentaku/version.rb

@@ -1,3 +1,3 @@
 module Dentaku
-  VERSION = "0.2.14"
+  VERSION = "1.0.0"
 end

data/spec/external_function_spec.rb

@@ -7,25 +7,31 @@ describe Dentaku::Calculator do
       let(:with_external_funcs) do
         c = described_class.new
 
-        rule = { :name => :now, :tokens => [], :body => ->(*args) { Dentaku::Token.new(:string, Time.now.to_s) } }
-        c.add_rule rule
+        now = { name: :now, type: :string, signature: [], body: -> { Time.now.to_s } }
+        c.add_function(now)
 
-        new_rules = [
+        fns = [
           {
-            :name => :exp,
-            :tokens => [ :non_group_star, :comma, :non_group_star ],
-            :body => ->(*args) do
-              ## first one is function name
-              ## second one is open parenthesis
-              ## last one is close parenthesis
-              ## all others are commas
-              _, _, mantissa, _, exponent, _ = args
-              Dentaku::Token.new(:numeric, (mantissa.value ** exponent.value))
-            end
+            name:      :exp,
+            type:      :numeric,
+            signature: [ :numeric, :numeric ],
+            body:      ->(mantissa, exponent) { mantissa ** exponent }
           },
+          {
+            name:      :max,
+            type:      :numeric,
+            signature: [ :non_close_plus ],
+            body:      ->(*args) { args.max }
+          },
+          {
+            name:      :min,
+            type:      :numeric,
+            signature: [ :non_close_plus ],
+            body:      ->(*args) { args.min }
+          }
         ]
 
-        c.add_rules new_rules
+        c.add_functions(fns)
       end
 
       it 'should include NOW' do
@@ -37,7 +43,15 @@ describe Dentaku::Calculator do
       it 'should include EXP' do
         with_external_funcs.evaluate('EXP(2,3)').should eq(8)
         with_external_funcs.evaluate('EXP(3,2)').should eq(9)
-        with_external_funcs.evaluate('EXP(mantissa,exponent)', :mantissa => 2, :exponent => 4).should eq(16)
+        with_external_funcs.evaluate('EXP(mantissa,exponent)', mantissa: 2, exponent: 4).should eq(16)
+      end
+
+      it 'should include MAX' do
+        with_external_funcs.evaluate('MAX(8,6,7,5,3,0,9)').should eq(9)
+      end
+
+      it 'should include MIN' do
+        with_external_funcs.evaluate('MIN(8,6,7,5,3,0,9)').should eq(0)
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dentaku
 version: !ruby/object:Gem::Version
-  version: 0.2.14
+  version: 1.0.0
 platform: ruby
 authors:
 - Solomon White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-24 00:00:00.000000000 Z
+date: 2014-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -56,6 +56,7 @@ files:
 - lib/dentaku/binary_operation.rb
 - lib/dentaku/calculator.rb
 - lib/dentaku/evaluator.rb
+- lib/dentaku/external_function.rb
 - lib/dentaku/rules.rb
 - lib/dentaku/token.rb
 - lib/dentaku/token_matcher.rb