soroban 0.7.3 → 0.8.0

data/.travis.yml

@@ -5,9 +5,10 @@ notifications:
 rvm:
   - ree
   - 1.8.7
+  - jruby-18mode
   - 1.9.2
   - 1.9.3
-  - jruby-18mode
   - jruby-19mode
-  - rbx-18mode
-  - rbx-19mode
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1

data/README.md

@@ -71,12 +71,12 @@ cells you've defined, so you can easily rip them out for persistence.
 ```ruby
 s.F1 = "= E1 + SUM(D1:D5)"
 
-s.missing             # => [:E1, :D1, :D2, :D3, :D4, :D5]
+puts s.missing        # => [:E1, :D1, :D2, :D3, :D4, :D5]
 
 s.E1 = "= D1 ^ D2"
 s.set("D1:D5" => [1,2,3,4,5])
 
-s.missing             # => []
+puts s.missing             # => []
 
 s.cells               # => {:F1=>"= E1 + SUM(D1:D5)", :E1=>"= D1 ^ D2", :D1=>"1", :D2=>"2", :D3=>"3", :D4=>"4", :D5=>"5"}
 ```
@@ -93,7 +93,7 @@ BINDINGS = {
   :force => :B3
 }
 
-s = Soroban::Import::rubyXL("files/Physics.xlsx", 0, BINDINGS )
+s = Soroban::Import::rubyXL("files/Physics.xlsx", 0, BINDINGS)
 
 s.planet = 'Earth'
 s.mass = 80
@@ -135,7 +135,7 @@ Soroban implements some Excel functions, but you may find that you need more
 than those. In that case, it's easy to add more.
 
 ```ruby
-Soroban::functions            # => ["AVERAGE", "SUM", "VLOOKUP", "IF", "AND", "OR", "NOT", "MAX", "MIN", "LN", "EXP"]
+Soroban::functions            # => ["AND", "AVERAGE", "EXP", "IF", "LN", "MAX", "MIN", "NOT", "OR", "SUM", "VLOOKUP"]
 
 Soroban::define :FOO => lambda { |lo, hi|
   raise ArgumentError if lo > hi

data/Soroban.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "soroban"
-  s.version = "0.7.3"
+  s.version = "0.8.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason Hutchens"]
-  s.date = "2014-03-20"
+  s.date = "2014-03-25"
   s.description = "Soroban makes it easy to extract and execute formulas from Excel spreadsheets. It rewrites Excel formulas as Ruby expressions, and allows you to bind named variables to spreadsheet cells to easily manipulate inputs and capture outputs."
   s.email = "jason.hutchens@agworld.com.au"
   s.extra_rdoc_files = [
@@ -31,7 +31,7 @@ Gem::Specification.new do |s|
     "files/Physics.xlsx",
     "lib/soroban.rb",
     "lib/soroban/cell.rb",
-    "lib/soroban/error.rb",
+    "lib/soroban/errors.rb",
     "lib/soroban/functions.rb",
     "lib/soroban/functions/and.rb",
     "lib/soroban/functions/average.rb",

data/VERSION

@@ -1 +1 @@
-0.7.3
+0.8.0

data/lib/soroban.rb

@@ -1,4 +1,3 @@
+require 'soroban/parser'
 require 'soroban/sheet'
-require 'soroban/cell'
-require 'soroban/error'
 require 'soroban/import'

data/lib/soroban/cell.rb

@@ -1,3 +1,9 @@
+unless defined?(Set)
+  require 'set'
+end
+
+require 'soroban/errors'
+require 'soroban/helpers'
 require 'soroban/parser'
 
 module Soroban
@@ -7,43 +13,66 @@ module Soroban
   # representation of its contents, and the executable Ruby version of same, as
   # generated via a rewrite grammar. Cells also store their dependencies.
   class Cell
-    attr_reader :excel, :dependencies
+    attr_reader :excel, :ruby, :dependencies
 
     # Cells are initialised with a binding to allow formulas to be executed
     # within the context of the sheet which owns the cell.
     def initialize(context)
-      @dependencies = []
-      @binding = context
-      @touched = false
-      @value = nil
+      @dependencies = Set.new
+      @excel = nil
+      @ruby = nil
+      @_binding = context
+      @_touched = false
+      @_value = nil
+      @_tree = nil
     end
 
-    # Set the contents of a cell, and store the executable Ruby version.
+    # Set the contents of a cell, and store the executable Ruby version. A
+    # Soroban::ParseError will be raised if an attempt is made to assign a value
+    # that isn't recognised by the Excel parser (although in most cases this
+    # should be treated as if you've passed in a string value). Note that
+    # assigning to the cell may cause its computed value to change; call #get to
+    # retrieve that. Note also that #set calls #clear internally to force
+    # recomputation of this value on the next #get call.
     def set(contents)
       contents = contents.to_s
-      contents = "'#{contents}'" if Soroban::unknown?(contents)
+      contents = "'#{contents}'" if Soroban::Helpers.unknown?(contents)
       clear
       @excel = contents
-      @tree = Soroban::parser.parse(@excel)
-      raise Soroban::ParseError, Soroban::parser.failure_reason if @tree.nil?
-      @ruby = @tree.to_ruby(@dependencies.clear)
+      @_tree = Soroban::Parser.instance.parse(@excel)
+      raise Soroban::ParseError, Soroban::Parser.instance.failure_reason if @_tree.nil?
+      @dependencies.clear
+      @ruby = @_tree.to_ruby(self)
     end
 
-    # Clear the cached value of a cell to force it to be recalculated
+    # Clear the cached value of a cell to force it to be recalculated. This
+    # should be unnecessary to call explicitly.
     def clear
-      @value = nil
+      @_value = nil
     end
 
-    # Eval the Ruby version of the string contents within the context of the
-    # owning sheet. Will throw Soroban::RecursionError if recursion is detected.
+    # Compute the value of the cell by evaluating the #ruby version of its
+    # contents within the context of the owning sheet. Will raise a
+    # Soroban::RecursionError if recursion is detected.
     def get
-      raise Soroban::RecursionError, "Loop detected when evaluating '#{@excel}'" if @touched
-      @touched = true
-      @value ||= eval(@ruby, @binding)
+      raise Soroban::RecursionError, "Loop detected when evaluating '#{@excel}'" if @_touched
+      @_touched = true
+      @_value ||= eval(@ruby, @_binding)
+      @_value
     rescue TypeError, RangeError, ZeroDivisionError
       nil
     ensure
-      @touched = false
+      @_touched = false
+    end
+
+    # Used by the parser to add information about which cells the value of this
+    # particular cell is dependent on. May pass in a single cell label or a
+    # collection of cells labels. The dependencies are stored as a Set, so the
+    # best way of adding the labels is to ensure they're converted to an
+    # enumerable (with [labels].flatten), and then to assign the union of the
+    # Set with that enumerable (with |=)
+    def add_dependencies(labels)
+      @dependencies |= [labels].flatten unless labels.nil?
     end
   end
 

data/lib/soroban/errors.rb

@@ -0,0 +1,20 @@
+module Soroban
+
+  # Raised if an invalid formula is assigned to a cell.
+  class ParseError < StandardError
+  end
+
+  # Raised if calculation of a cell's formula depends on the value of the same
+  # cell.
+  class RecursionError < StandardError
+  end
+
+  # Raised if a referenced cell falls outside the limits of a supplied range.
+  class RangeError < StandardError
+  end
+
+  # Raised if access is attempted to an undefined cell.
+  class UndefinedError < StandardError
+  end
+
+end

data/lib/soroban/functions.rb

@@ -1,33 +1,43 @@
+require 'soroban/errors'
+require 'soroban/helpers'
+
 module Soroban
 
-  # Define a new function.
-  def self.define(function_hash)
-    @@functions ||= {}
-    function_hash.each { |name, callback| @@functions[name] = callback }
-  end 
+  class Functions
+    # Define one or more functions by passing in a hash mapping function name to
+    # the lambda that computes the function's value.
+    def self.define(function_hash)
+      @@_functions ||= {}
+      function_hash.each do |name, callback|
+        @@_functions[name.to_s.upcase.to_sym] = callback
+      end
+    end 
 
-  # Return an array of all defined functions.
-  def self.functions
-    @@functions.keys.map { |f| f.to_s }
-  end
+    # Return an array of all defined functions.
+    def self.all
+      @@_functions.keys.map(&:to_s).to_a.sort
+    end
 
-  # Call the named function within the context of the specified sheet.
-  def self.call(sheet, name, *args)
-    function = name.upcase.to_sym
-    raise Soroban::UndefinedError, "No such function '#{function}'" unless @@functions[function]
-    sheet.instance_exec(*args, &@@functions[function])
+    # Call the named function within the context of the specified sheet, supplying
+    # some number of arguments (which is a property of the function, and therefore
+    # given as a splat here).
+    def self.call(sheet, name, *args)
+      callback = @@_functions[name.to_s.upcase.to_sym]
+      raise Soroban::UndefinedError, "No such function '#{name}'" if callback.nil?
+      sheet.instance_exec(*args, &callback)
+    end
   end
 
 end
 
+require 'soroban/functions/and'
 require 'soroban/functions/average'
-require 'soroban/functions/sum'
-require 'soroban/functions/vlookup'
+require 'soroban/functions/exp'
 require 'soroban/functions/if'
-require 'soroban/functions/and'
-require 'soroban/functions/or'
-require 'soroban/functions/not'
+require 'soroban/functions/ln'
 require 'soroban/functions/max'
 require 'soroban/functions/min'
-require 'soroban/functions/ln'
-require 'soroban/functions/exp'
+require 'soroban/functions/not'
+require 'soroban/functions/or'
+require 'soroban/functions/sum'
+require 'soroban/functions/vlookup'

data/lib/soroban/functions/and.rb

@@ -1,4 +1,6 @@
 # Logical and of supplied arguments, which may be booleans, labels or ranges.
-Soroban::define :AND => lambda { |*args|
-  Soroban::getValues(binding, *args).reduce(true) { |s, a| s && a }
+# Note that the reduce call will short-circuit as long as the |l, r| arguments
+# are used in the correct order.
+Soroban::Functions.define :AND => lambda { |*args|
+  Soroban::Helpers.getValues(binding, *args).reduce(true) { |l, r| l && r }
 }

data/lib/soroban/functions/average.rb

@@ -1,5 +1,5 @@
 # Average the arguments, which may be numbers, labels or ranges.
-Soroban::define :AVERAGE => lambda { |*args|
-  values = Soroban::getValues(binding, *args)
+Soroban::Functions.define :AVERAGE => lambda { |*args|
+  values = Soroban::Helpers.getValues(binding, *args)
   values.reduce(:+) / values.length.to_f
 }

data/lib/soroban/functions/exp.rb

@@ -1,4 +1,2 @@
 # Return e raised to the power of the argument
-Soroban::define :EXP => lambda { |val|
-  Math.exp(val)
-}
+Soroban::Functions.define :EXP => lambda { |val| Math.exp(val) }

data/lib/soroban/functions/if.rb

@@ -1,4 +1,4 @@
 # Return one of two values depending on the value of the supplied boolean.
-Soroban::define :IF => lambda { |val, if_true, if_false|
+Soroban::Functions.define :IF => lambda { |val, if_true, if_false|
   val ? if_true : if_false
 }

data/lib/soroban/functions/ln.rb

@@ -1,4 +1,2 @@
 # Return the natural logarithm of the argument
-Soroban::define :LN => lambda { |val|
-  Math.log(val)
-}
+Soroban::Functions.define :LN => lambda { |val| Math.log(val) }

data/lib/soroban/functions/max.rb

@@ -1,4 +1,4 @@
 # Return the maximum of the supplied values, which may be numbers, labels or ranges.
-Soroban::define :MAX => lambda { |*args|
-  Soroban::getValues(binding, *args).max
+Soroban::Functions.define :MAX => lambda { |*args|
+  Soroban::Helpers.getValues(binding, *args).max
 }

data/lib/soroban/functions/min.rb

@@ -1,4 +1,4 @@
 # Return the minimum of the supplied values, which may be numbers, labels or ranges.
-Soroban::define :MIN => lambda { |*args|
-  Soroban::getValues(binding, *args).min
+Soroban::Functions.define :MIN => lambda { |*args|
+  Soroban::Helpers.getValues(binding, *args).min
 }

data/lib/soroban/functions/not.rb

@@ -1,4 +1,2 @@
 # Return the logical not of the supplied boolean.
-Soroban::define :NOT => lambda { |val|
-  !val
-}
+Soroban::Functions.define :NOT => lambda { |val| !val }

data/lib/soroban/functions/or.rb

@@ -1,4 +1,6 @@
 # Logical or of supplied arguments, which may be booleans, labels or ranges.
-Soroban::define :OR => lambda { |*args|
-  Soroban::getValues(binding, *args).reduce(false) { |s, a| s || a }
+# Note that the reduce call will short-circuit as long as the |l, r| arguments
+# are used in the correct order.
+Soroban::Functions.define :OR => lambda { |*args|
+  Soroban::Helpers.getValues(binding, *args).reduce(false) { |l, r| l || r }
 }

data/lib/soroban/functions/sum.rb

@@ -1,4 +1,4 @@
 # Sum the arguments, which may be numbers, labels or ranges.
-Soroban::define :SUM => lambda { |*args|
-  Soroban::getValues(binding, *args).reduce(:+)
+Soroban::Functions.define :SUM => lambda { |*args|
+  Soroban::Helpers.getValues(binding, *args).reduce(:+)
 }

data/lib/soroban/functions/vlookup.rb

@@ -1,7 +1,7 @@
 # Return a value from the supplied range by searching the first column for the
 # supplied value, and then reading the result from the matching row.
-Soroban::define :VLOOKUP => lambda { |value, range, col, inexact|
-  fc, fr, tc, tr = Soroban::getRange(range)
+Soroban::Functions.define :VLOOKUP => lambda { |value, range, col, inexact|
+  fc, fr, tc, tr = Soroban::Helpers.getRange(range)
   i = walk("#{fc}#{fr}:#{fc}#{tr}").find_index(value)
   if i.nil?
     nil

data/lib/soroban/helpers.rb

@@ -1,52 +1,76 @@
-require 'soroban/parser'
+require 'soroban/errors'
+require 'soroban/value_walker'
 
 module Soroban
 
-  # Return true if the supplied data represents a formula.
-  def self.formula?(data)
-    data.to_s.slice(0..0) == '='
-  end
+  class Helpers
+    # Return true if the supplied data represents a formula.
+    def self.formula?(data)
+      data.to_s.slice(0..0) == '='
+    end
 
-  # Return true if the supplied data is a number.
-  def self.number?(data)
-    Float(data.to_s) && true rescue false
-  end
+    # Return true if the supplied data is a number.
+    def self.number?(data)
+      Float(data.to_s) && true rescue false
+    end
 
-  # Return true if the supplied data is a boolean.
-  def self.boolean?(data)
-    /^(true|false)$/i.match(data.to_s) && true || false
-  end
+    # Return true if the supplied data is a boolean.
+    def self.boolean?(data)
+      /^(true|false)$/i.match(data.to_s) && true ||
+      false
+    end
 
-  # Return true if the supplied data is a string.
-  def self.string?(data)
-    /^["](\"|[^"])*["]$/.match(data.to_s) && true || /^['][^']*[']$/.match(data.to_s) && true || false
-  end
+    # Return true if the supplied data is a string.
+    def self.string?(data)
+      /^["](\"|[^"])*["]$/.match(data.to_s) && true ||
+      /^['][^']*[']$/.match(data.to_s) && true ||
+      false
+    end
 
-  # Return true if the supplied data is a range.
-  def self.range?(data)
-    /^([a-zA-Z]+)([\d]+):([a-zA-Z]+)([\d]+)$/.match(data.to_s) && true || false
-  end
+    # Return true if the supplied data is a label.
+    def self.label?(data)
+      /^([a-zA-Z]+)([\d]+)$/.match(data.to_s) && true ||
+      false
+    end
 
-  # Return true if the supplied data is of no recognised format.
-  def self.unknown?(data)
-    !self.formula?(data) && !self.number?(data) && !self.boolean?(data) && !self.string?(data)
-  end
+    # Return true if the supplied data is a range.
+    def self.range?(data)
+      /^([a-zA-Z]+)([\d]+):([a-zA-Z]+)([\d]+)$/.match(data.to_s) && true ||
+      false
+    end
 
-  # Return the components of a range.
-  def self.getRange(range)
-    /^([a-zA-Z]+)([\d]+):([a-zA-Z]+)([\d]+)$/.match(range.to_s).to_a[1..-1]
-  end
+    # Return true if the supplied data is of no recognised format.
+    def self.unknown?(data)
+      !formula?(data) &&
+      !number?(data) &&
+      !boolean?(data) &&
+      !string?(data) &&
+      !label?(data) &&
+      !range?(data)
+    end
 
-  # Return the row and column index of the given label.
-  def self.getPos(label)
-    # TODO: fix for labels such as "BC42"
-    match = /^([a-zA-Z]+)([\d]+)$/.match(label.to_s)
-    return match[2].to_i - 1, match[1].upcase[0].ord-"A"[0].ord
-  end
+    # Return the components of a range. This converts something like "A12:C42"
+    # to a tuple of the form ["A", "12", "C", "42"]. Will raise a ParseError if
+    # the supplied argument is not a valid range.
+    def self.getRange(data)
+      raise Soroban::ParseError, "invalid #getRange for '#{data}'" if !range?(data)
+      /^([a-zA-Z]+)([\d]+):([a-zA-Z]+)([\d]+)$/.match(data.to_s).to_a[1..-1]
+    end
+
+    # Return the row and column index of the given label. This converts something
+    # like "B42" into [41, 1]. It is a known bug that it does not work for labels
+    # of the form "BC42". Will raise a ParseError if the supplied argument is not
+    # a valid label.
+    def self.getPos(data)
+      raise Soroban::ParseError, "invalid #getPos for '#{data}'" if !label?(data)
+      match = /^([a-zA-Z]+)([\d]+)$/.match(data.to_s)
+      return [match[2].to_i - 1, match[1].upcase[0].ord-"A"[0].ord]
+    end
 
-  # Return an array of values for the supplied arguments (which may be numbers, labels and ranges).
-  def self.getValues(context, *args)
-    args.map { |arg| Soroban::range?(arg) ? ValueWalker.new(arg, context).to_a : arg }.to_a.flatten
+    # Return an array of values for the supplied arguments (which may be numbers, labels and ranges).
+    def self.getValues(context, *args)
+      args.map { |arg| range?(arg) ? Soroban::ValueWalker.new(arg, context).to_a : arg }.to_a.flatten
+    end
   end
 
 end