Soroban 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/.yardopts

@@ -0,0 +1,6 @@
+--protected
+--no-private
+--exclude lib/soroban/parser/
+-
+README.md
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+gem "treetop", "~> 1.4.10"
+
+group :development do
+  gem "rspec", "~> 2.8.0"
+  gem "yard", "~> 0.7"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.1.3"
+  gem "jeweler", "~> 1.8.3"
+  gem "rcov", ">= 0"
+  gem "rubyXL", "~> 1.2.7"
+  gem "redcarpet"
+end

data/Gemfile.lock

@@ -0,0 +1,44 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    polyglot (0.3.3)
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    redcarpet (2.1.1)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    rubyXL (1.2.7)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    yard (0.7.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.1.3)
+  jeweler (~> 1.8.3)
+  rcov
+  rdoc (~> 3.12)
+  redcarpet
+  rspec (~> 2.8.0)
+  rubyXL (~> 1.2.7)
+  treetop (~> 1.4.10)
+  yard (~> 0.7)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Agworld Pty. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS 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/README.md

@@ -0,0 +1,115 @@
+Soroban
+=======
+
+Soroban is a calculating engine that understands Excel formulas.
+
+Getting Started
+---------------
+
+```
+> sudo gem install soroban
+```
+
+Example Usage
+-------------
+
+```ruby
+require 'soroban'
+
+s = Soroban::Sheet.new()
+
+s.A1 = 2
+s.set('B1:B5', [1,2,3,4,5])
+s.C1 = "=SUM(B1:B5) + A1 ^ 3"
+s.C2 = "=IF(C1>25,'Large','Tiny')"
+
+puts s.C1             # => 23
+
+s.bind(:input, :A1)
+s.bind(:output, :C2)
+
+puts s.output         # => "Tiny"
+
+s.input = 3
+
+puts s.output         # => "Large"
+puts s.C1             # => 42
+```
+
+Persistence
+-----------
+
+Soroban formulas are strings that begin with the `=` symbol. It is therefore
+easy to persist them, which is mighty handy if you need to parse an Excel
+spreadsheet, rip out formulas, store everything to a database and then perform
+calculations based on user input.
+
+Soroban makes this easy, as it can tell you which cells you need to add to make
+it possible to do the calculations you want, and it can iterate over all the
+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]
+
+s.E1 = "= D1 ^ D2"
+s.set("D1:D5", [1,2,3,4,5])
+
+s.missing             # => []
+
+s.cells               # => {"F1"=>"= E1 + SUM(D1:D5)", "E1"=>"= D1 ^ D2", "D1"=>"1", "D2"=>"2", "D3"=>"3", "D4"=>"4", "D5"=>"5"}
+```
+
+This means parsing a file can be done as follows.
+
+* Add the cells that correspond to inputs and outputs
+* Add the cells reported by `missing` (and continue to do so until it's empty)
+* Persist the hash returned by `cells`
+
+Iteration
+---------
+
+Note that `cells` returns the label of the cell along with its raw contents. If
+you want to iterate over cell values (including computed values of formulas),
+then use `walk`.
+
+```ruby
+s.set('D1:D5', [1,2,3,4,5])
+s.walk('D1:D5').reduce(:+)    # => 15
+```
+
+Functions
+---------
+
+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            # => ["MIN", "VLOOKUP", "AND", "MAX", "OR", "NOT", "IF", "AVERAGE", "SUM"] 
+
+Soroban::define :FOO => lambda { |lo, hi|
+  raise ArgumentError if lo > hi
+  rand(hi-lo) + lo
+}
+
+s.g = "=FOO(10, 20)"
+
+puts s.g              # => 17
+```
+
+Contributing to Soroban
+-----------------------
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+Copyright
+---------
+
+Copyright (c) 2012 Agworld Pty. Ltd. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,42 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "Soroban"
+  gem.homepage = "http://github.com/jasonhutchens/soroban"
+  gem.license = "MIT"
+  gem.summary = "Soroban is a calculating engine that understands Excel formulas."
+  gem.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."
+  gem.email = "jason.hutchens@agworld.com.au"
+  gem.authors = ["Jason Hutchens"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/soroban.rb

@@ -0,0 +1,3 @@
+require 'soroban/sheet'
+require 'soroban/cell'
+require 'soroban/error'

data/lib/soroban/cell.rb

@@ -0,0 +1,47 @@
+require 'soroban/parser'
+
+module Soroban
+
+  # Represents a single cell in a sheet. This class is used internally, and
+  # isn't exposed to the caller. The cell stores the original string
+  # 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, :ruby, :dependencies
+
+    # Cells are initialised with a binding to allow formulas to be executed
+    # within the context of the sheet which ownes the cell.
+    def initialize(binding)
+      @dependencies = []
+      @binding = binding
+      @touched = false
+    end
+
+    # Set the contents of a cell, and store the executable Ruby version.
+    def set(contents)
+      contents = contents.to_s
+      contents = "'#{contents}'" if Soroban::unknown?(contents)
+      @excel, @ruby = contents, _convert(contents)
+    end
+
+    # Eval the Ruby version of the string contents within the context of the
+    # owning sheet. Will throw Soroban::RecursionError if recursion is detected.
+    def get
+      raise Soroban::RecursionError, "Loop detected when evaluating '#{@excel}'" if @touched
+      @touched = true
+      eval(@ruby, @binding)
+    ensure
+      @touched = false
+    end
+
+  private
+
+    def _convert(contents)
+      tree = Soroban::parser.parse(contents)
+      raise Soroban::ParseError, Soroban::parser.failure_reason if tree.nil?
+      tree.convert(@dependencies.clear)
+    end
+
+  end
+
+end

data/lib/soroban/error.rb

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

data/lib/soroban/functions.rb

@@ -0,0 +1,31 @@
+module Soroban
+
+  # Define a new function.
+  def self.define(function_hash)
+    @@functions ||= {}
+    function_hash.each { |name, callback| @@functions[name] = callback }
+  end 
+
+  # Return an array of all defined functions.
+  def self.functions
+    @@functions.keys.map { |f| f.to_s }
+  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])
+  end
+
+end
+
+require 'soroban/functions/average'
+require 'soroban/functions/sum'
+require 'soroban/functions/vlookup'
+require 'soroban/functions/if'
+require 'soroban/functions/and'
+require 'soroban/functions/or'
+require 'soroban/functions/not'
+require 'soroban/functions/max'
+require 'soroban/functions/min'

data/lib/soroban/functions/and.rb

@@ -0,0 +1,4 @@
+# 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 }
+}

data/lib/soroban/functions/average.rb

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

data/lib/soroban/functions/if.rb

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

data/lib/soroban/functions/max.rb

@@ -0,0 +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
+}

data/lib/soroban/functions/min.rb

@@ -0,0 +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
+}

data/lib/soroban/functions/not.rb

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

data/lib/soroban/functions/or.rb

@@ -0,0 +1,4 @@
+# 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 }
+}

data/lib/soroban/functions/sum.rb

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

data/lib/soroban/functions/vlookup.rb

@@ -0,0 +1,10 @@
+# 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)
+  i = walk("#{fc}#{fr}:#{fc}#{tr}").find_index(value)
+  return nil if i.nil?
+  (0...i).each { fr.next! }
+  (1...col).each { fc.next! }
+  eval("@#{fc}#{fr}.get")
+}

data/lib/soroban/helpers.rb

@@ -0,0 +1,45 @@
+require 'soroban/parser'
+
+module Soroban
+
+  # 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 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 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 of no recognised format.
+  def self.unknown?(data)
+    !self.formula?(data) && !self.number?(data) && !self.boolean?(data) && !self.string?(data)
+  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 an array of values for the supplied arguments (which may be numbers, labels and ranges).
+  def self.getValues(binding, *args)
+    args.map { |arg| Soroban::range?(arg) ? Walker.new(arg, binding).map : arg }.flatten
+  end
+
+end