lxl 0.2.4 → 0.3.0

data/CHANGES

@@ -1,3 +1,16 @@
+0.3.0
+
+- Functions and constants moved into LXL::Namespace (major refactoring)
+- Added ranges (r): A1:D5 => LXL::Range.new("A1","D5")
+  LXL::Range is a Range subclass which overrides #each to return an excel-style range
+- Added percentages (p): 25% => 0.25
+- Added & string concentation operator
+- Added ^ exponential operator
+- Added semi-colon guessing: eliminates the need for statement separator in most cases (\n= becomes \n;)
+- Fix: semi-colons parsed as tokens again to allow semis in strings
+- Refactored string quoting
+- Filled out rdoc
+
 0.2.4
 
 - Added Deferred function calls via register_deferred

data/README.en

@@ -0,0 +1,68 @@
+LXL README
+============
+
+LXL (Like Excel) is a mini-language that mimics Microsoft Excel formulas.
+Easily extended with new constants and functions.
+
+Usage
+-----
+
+  formulas = %{
+    This is some text;
+    ="This is some ""quoted"" text"
+    =((1+2)*(10-6))/2
+    =datetime("2004-11-22 11:11:00")=DATE(2004,11,22)+TIME(11,11,00)
+    =IN(" is ", "this is a string")
+    =LIST(1, "two", 3.0)
+    =IN("b", LIST("a", "b", "c"))
+    =AND(TRUE, NULL)
+    =OR(TRUE, FALSE)
+    =IF(1+1=2, "yes", "no")
+    ="this" & " and " & "that"
+    =2^3
+    =25%+25.2%
+  }
+  
+  # single formula
+  puts LXL.eval('=5+5').inspect # => 10
+
+  # multiple formulas separated by semi-colon
+  puts LXL.eval(formulas).inspect
+  # => ["This is some text", "This is some \"quoted\" text", 6, true, true, [1, "two", 3.0], true, false, true, "yes", "this and that", 8, 0.502]
+  
+  See API docs for more information.
+
+Requirements
+------------
+
+  * Ruby 1.8.2
+
+Install
+-------
+
+  GEM file
+
+    gem install lxl (remote)
+    gem install lxl-x.x.x.gem (local)
+  
+  Tarball (setup.rb)
+
+    De-Compress archive and enter its top directory.
+    Then type:
+
+      $ ruby setup.rb config
+      $ ruby setup.rb setup
+     ($ su)
+      # ruby setup.rb install
+
+  You can also install files into your favorite directory
+  by supplying setup.rb some options. Try "ruby setup.rb --help".
+
+License
+-------
+
+  LXL incorporates John Carter's LittleLexer for parsing.
+  Distributes under the same terms as LittleLexer.
+  http://www.rubyforge.org/projects/littlelexer/
+
+Kevin Howe <kh@newclear.ca>

data/VERSION

@@ -1 +1 @@
-0.2.4
+0.3.0

data/lib/lxl.rb

@@ -1,5 +1,5 @@
 # LXL (Like Excel) is a mini-language that mimics Microsoft Excel formulas.
-# Easily extended with new constants and functions.
+# Easily extended with new constants and functions using LXL::Namespace.
 #
 # =Constants
 #
@@ -19,6 +19,8 @@
 #   a >  b # Greater than
 #   a <= b # Less than or equal to
 #   a >= b # Greater than or equal to
+#   a &  b # String concentation
+#   n ^ n  # Exponential
 #
 # =Logical Functions
 #
@@ -42,13 +44,47 @@
 # =Notes
 #
 #  * The number zero is interpereted as FALSE
+#  * Percentages are translated: 25% => 0.25
+#  * Ranges are translated: A1:D5 => LXL::Range.new("A1", "D5")
 #  * Return multiple results in an array by separating formulas with a semi-colon (;)
+#  * Constant and Function names are case-insensitive
+#  * Values prefixed with = are formulas, anything else is assumed to be text:
 #
+#      LXL.eval("5+5")  # => '5+5'
+#      LXL.eval("=5+5") # => 10
+#
+module LXL
+
+  module_function
+
+  # False if nil, false or zero.
+  #
+  def to_b(value)
+    [nil,false,0].include?(value) ? false : true
+  end
+
+  # Evaluate a formula.
+  #
+  def eval(formula)
+    LXL::Parser.eval(formula)
+  end
+
+  # Create a new Parser.
+  #
+  def new(*args)
+    LXL::Parser.new(*args)
+  end
+
+end
+
 # =Lexical Types
 #
-#  w  Whitespace (includes Commas)
+#  w  Whitespace (includes commas)
+#  ;  Semi-Colon (statement separator)
 #  o  Operator
 #  s  String
+#  r  Range
+#  p  Percentage
 #  f  Float
 #  i  Integer
 #  t  Token
@@ -58,146 +94,95 @@
 #  F Function
 #  C Constant
 #
-module LXL
-
-  module_function
-
-  # Evaluate a formula
-  #
-  def eval(formula)
-    LXL::Parser.eval(formula)
-  end
-
-end
-
 class LXL::Parser
 
-  attr_reader :constants, :functions, :lexer
+  attr_reader :namespace, :lexer
 
-  RUBY_OPERATORS  = ['+', '-', '*', '/', '<=', '>=', '==', '!=', '<', '>']
-  EXCEL_OPERATORS = ['+', '-', '*', '/', '<=', '>=', '=',  '<>', '<', '>']
+  RUBY_OPERATORS  = ['+', '-', '*', '/', '<=', '>=', '==', '!=', '<', '>', '+', '**']
+  EXCEL_OPERATORS = ['+', '-', '*', '/', '<=', '>=', '=',  '<>', '<', '>', '&', '^' ]
 
-  # Evaluate a formula
+  # Evaluate a formula.
   #
   def self.eval(formula)
     self.new.eval(formula)
   end
-
-  # Initialize parser
+  
+  # Default namespace class.
   #
-  def initialize
-
-    # Constants
-    @constants = Hash.new
-    register_constant(:TRUE, true)
-    register_constant(:FALSE, false)
-    register_constant(:NULL, nil)
-    
-    # Functions
-    @functions = Hash.new
-    register_function(:AND)      { |a,b| to_b(a) && to_b(b) }
-    register_function(:OR)       { |a,b| to_b(a) || to_b(b) }
-    register_function(:IF)       { |v,a,b| to_b(v) ? a : b }
-    register_function(:LIST)     { |*args| args }
-    register_function(:IN)       { |n,h| h.respond_to?(:include?) ? h.include?(n) : false }
-    register_function(:TODAY)    { Date.today.ajd.to_f }
-    register_function(:NOW)      { DateTime.now.ajd.to_f }
-    register_function(:DATE)     { |y,m,d| Date.new(y,m,d).ajd.to_f }
-    register_function(:DATETIME) { |value| DateTime.parse(value).ajd.to_f }
-    register_function(:TIME)     { |h,m,s|
-      DateTime.valid_time?(h,m,s) ? DateTime.valid_time?(h,m,s).to_f : raise(ArgumentError, 'invalid time')
-    }
+  def self.namespace_class
+    LXL::Namespace
+  end
 
-    # Lexer
+  # Initialize namespace and parser.
+  #
+  def initialize(namespace=self.class.namespace_class.new)
+    @namespace = namespace
     ops = EXCEL_OPERATORS.collect { |v| Regexp.quote(v) }.join('|')
-    #
     @lexer = LXL::LittleLexer.new([
                         [/\A[\s,]+/, ?w],          # Whitespace (includes Commas)
+                        [/\A;/, ?;],               # Semi-Colon (statement separator)
                         [/\A(#{ops})/, ?o],        # Operator
                         [/\A("([^"]|"")*")/m, ?s], # String
-                        [/\A[0-9]+\.[0-9]+/, ?f],  # Float
-                        [/\A[0-9]+/, ?i],          # Integer
+                        [/\A\w+:\w+/, ?r],         # Range
+                        [/\A\d+(\.\d+)?%/, ?p],    # Percentage
+                        [/\A\d+\.\d+/, ?f],        # Float
+                        [/\A\d+/, ?i],             # Integer
                         [/\A\w+/, ?t],             # Token
                         [/\A\(/, ?(],              # Open (
                         [/\A\)/, ?)],              # Close )
                       ], false)
   end
 
-  # Evaluate formula
+  # Evaluate a formula.
   #
   def eval(formula)
-    formulas = formula.to_s.split(';').collect { |f| f.strip }.find_all { |f| ! f.empty? }
-    formulas.collect! { |f| Kernel.eval(tokenize_text(f).last.join, binding) }
+    formulas = [[]]
+    formula = formula.to_s.gsub(/(\n)(\s*=)/, '\1;\2') # infer statement separators
+    types,tokens = tokenize(formula)
+    tokens.each_index { |i| tokens[i] == ';' ? formulas << [] : formulas.last << [types[i], tokens[i]] }
+    formulas.collect! { |f|
+      types  = f.collect { |t| t.first }
+      tokens = f.collect { |t| t.last  }
+      token = tokens.join.strip
+      if token =~ /^=/
+        tokens.each_index { |i| tokens[i] = translate_quotes(tokens[i]) if types[i] == :s }
+        token = tokens.join.strip.gsub(/^=+/, '')
+      else
+        token = translate_quotes(quote(tokens.join.strip))
+      end
+    }
+    formulas.delete_if { |f| f == '""' }
+    formulas.collect! { |f| Kernel.eval(f, binding) }
     formulas.size == 1 ? formulas.first : formulas
   end
   
-  # Register a function
-  #
-  # * Converts name to symbol
-  # * Wraps function with a debugging procedure
-  #
-  def register_function(name, &block)
-    name = name(name)
-    @functions[name] = debug(name, &block)
-  end
-  
-  # Register a constant
-  #
-  # * Converts name to symbol
-  #
-  def register_constant(name, value)
-    name = name(name)
-    @constants[name] = value
-  end
-
-  # Register a constant for each symbol of the same name and value
-  #
-  def register_symbols(*symbols)
-    symbols.each { |s| register_constant(s, s) }
-  end
-
-  # Register each symbol as a Deferred function call
-  #
-  def register_deferred(*symbols)
-    symbols.each { |s| register_function(s) { |*args| LXL::Deferred.new(s, *args) } }
-  end
-  
   protected
   
-  # Translate to uppercase symbol
-  #
-  def name(obj)
-    obj.to_s.upcase.to_sym
-  end
-
-  # Wrap a procedure in a debugging procedure
+  # Quote a text value.
   #
-  # * Raise an error unless given the correct number of arguments
+  #  quote('a "quoted" value.')
+  #  # => '"a ""quoted"" value."'
   #
-  def debug(name, &block)
-    raise ArgumentError, 'block not given to debug' unless block_given?
-    Proc.new { |*args|
-      if block.arity >= 0 and block.arity != args.size
-        raise ArgumentError, "wrong number of arguments (#{args.size} for #{block.arity}) for #{name}"
-      end
-      block.call(*args)
-    }
+  def quote(text)
+    '"'+text.to_s.gsub('"','""')+'"'
   end
   
-  # Translates text to a formula before tokenizing
+  # Translate "" to \" in quoted string values.
   #
-  def tokenize_text(text)
-    formula = (text =~ /^=/) ? text : '="'+text.gsub('"','""')+'"'
-    tokenize(formula)
+  #   translate_quotes('"a ""quoted"" value."')
+  #   # => '"a \"quoted\" value."'
+  #
+  def translate_quotes(text)
+    text.to_s.gsub(/([^\\])""/,'\1\"')
   end
 
-  # Tokenize formula into [TypesArray, TokensArray]
+  # Tokenize a formula into <tt>[TypesArray, TokensArray]</tt>.
   #
   def tokenize(formula)
     ops = Hash[*EXCEL_OPERATORS.zip(RUBY_OPERATORS).flatten]
 
     # Parse formula
-    types,tokens = @lexer.scan(formula.gsub(/^=/,''))
+    types,tokens = @lexer.scan(formula.to_s)
     raise SyntaxError, 'unbalanced parentheses' unless balanced?(tokens)
     
     # Parse tokens
@@ -205,23 +190,25 @@ class LXL::Parser
       type, token = types[i], tokens[i]
       tokens[i] = case type
         when :o then ops[token]
-        when :s then token.gsub(/([^\\])""/,'\1\"') # "" to \"
+        when :r then "LXL::Range.new(*#{token.split(':').inspect})"
+        when :p then token.to_f/100
         when :f then token.to_f
         when :i then token.to_i
         when :t then
-          name = name(token)
-          if @functions.key?(name)
+          upper = token.to_s.upcase.to_sym
+          lower = token.to_s.downcase.to_sym
+          raise NoMethodError, "protected method `#{token}` called for #{self}" if @namespace.const_get(:METHODS).include?(token.to_s)
+          if @namespace.respond_to?(lower)
             if tokens[i+1] != '('
               raise ArgumentError, "wrong number of arguments for #{token}"
             else
               types[i] = :F
-              "@functions[:#{name}].call"
+              "@namespace.method(:#{lower}).call"
             end
-          elsif @constants.key?(name)
+          elsif @namespace.const_defined?(upper)
             types[i] = :C
-            "@constants[:#{name}]"
-          else
-            raise NameError, "unknown constant #{token}"
+            "@namespace.const_get(:#{upper})"
+          else token
           end
         else token
       end
@@ -230,21 +217,47 @@ class LXL::Parser
     [types,tokens]
   end
   
-  # Check that parentheses are balanced
+  # Check that parentheses are balanced.
   #
   def balanced?(tokens)
     tokens.find_all { |t| ['(', ')'].include?(t) }.size % 2 == 0
   end
 
-  # False if nil, false or zero
-  #
-  def to_b(value)
-    [nil,false,0].include?(value) ? false : true
+end
+
+# Excel-style ranges.
+#
+#   Range.new("B3", "D5").collect
+#   # => ["B3", "B4", "B5", "B6", "B7", "B8", "B9",
+#         "C0", "C1", "C2", "C3", "C4", "C5", "C6", "C7", "C8", "C9",
+#         "D0", "D1", "D2", "D3", "D4", "D5"]
+#
+#   LXL::Range.new("B3", "D5").collect
+#   # => ["B3", "B4", "B5", "C3", "C4", "C5", "D3", "D4", "D5"]
+#
+class LXL::Range < Range
+
+  def each
+    a,b = self.begin.to_s, self.end.to_s
+    if a =~ /\D/ and b =~ /\D/
+      r = [a,b].collect{ |x| x.upcase }.sort
+      a_col,b_col = r.collect { |x| x.gsub(/\d/, '') }
+      a_cel,b_cel = r.collect { |x| x.gsub(/\D/, '') }
+      range = Range.new(a_col,b_col).each{ |col| Range.new(a_cel,b_cel).each { |cel| yield col+cel } }
+    else
+      super
+    end
   end
 
 end
 
-# Deferred function call (snapshots the symbol and arguments).
+# Snapshots the symbol/arguments of a function call for later use.
+#
+#   class MyNamespace < LXL::Namespace
+#     register_deferred :foo
+#   end
+#   LXL.new(MyNamespace.new).eval('=FOO(1, "two", 3)').inspect
+#   # => <LXL::Deferred @args=[1, "two", 3] @symbol=:foo>
 #
 class LXL::Deferred
 
@@ -257,7 +270,112 @@ class LXL::Deferred
 
 end
 
-# John Carter's LittleLexer
+# Namespace lookup for constants and functions (minimal methods).
+#
+class LXL::EmptyNamespace
+
+  # Remove all unessecary methods
+  ['constants', 'const_defined?', 'const_get', 'const_set'].each { |m| define_method(m) { |s| self.class.send(m,s) } }
+  METHODS = ['__id__', '__send__', 'constants', 'const_defined?', 'const_get', 'const_set', 'class', 'instance_methods', 'method', 'methods', 'respond_to?', 'to_s']
+  (instance_methods-METHODS).sort.each { |m| undef_method m }
+
+  # Ensure all constants are included (inherited, extended, included, etc).
+  #
+  def self.const_defined?(symbol) #:nodoc:
+    constants.include?(symbol.to_s)
+  end
+  
+  # Register lowercase methods which return a Deferred function call.
+  #
+  #   class MyNamespace < LXL::Namespace
+  #     register_deferred :foo
+  #   end
+  #   LXL.new(MyNamespace.new).eval('=FOO(1, "two", 3)').inspect
+  #   # => <LXL::Deferred @args=[1, "two", 3] @symbol=:foo>
+  #
+  def self.register_deferred(*symbols)
+    symbols.collect! { |s| s.to_s.downcase.to_sym }
+    symbols.each { |s| define_method(s) { |*args| LXL::Deferred.new(s, *args) } }
+  end
+
+  # Register uppercase constants of the same name and value.
+  #
+  #   class MyNamespace < LXL::Namespace
+  #     register_symbols :foo, :bar
+  #   end
+  #   LXL.new(MyNamespace.new).eval('=LIST(FOO, BAR)').inspect
+  #   # => [:FOO, :BAR]
+  #
+  def self.register_symbols(*symbols)
+    symbols.collect! { |s| s.to_s.upcase.to_sym }
+    symbols.each { |s| const_set(s, s) }
+  end
+  
+end
+
+# Constants and functions defined here will become available to formulas.
+# 
+#   class MyLXLNamespace < LXL::Namespace
+#     NAME = 'John Doe'
+#     def upper(text) text.to_s.upcase end
+#   end
+#   
+#   class MyLXL < LXL::Parser
+#     def self.namespace_class() MyLXLNamespace end
+#   end
+#   
+#   MyLXL.eval('=UPPER(NAME)')
+#   # => JOHN DOE
+#
+class LXL::Namespace < LXL::EmptyNamespace
+
+  TRUE = true
+  FALSE = false
+  NULL = nil
+  
+  def and(a,b)
+    LXL.to_b(a) && LXL.to_b(b)
+  end
+
+  def or(a,b)
+    LXL.to_b(a) || LXL.to_b(b)
+  end
+
+  def if(c,a,b)
+    LXL.to_b(c) ? a : b
+  end
+
+  def list(*items)
+    items
+  end
+
+  def in(n,h)
+    h.respond_to?(:include?) ? h.include?(n) : false
+  end
+
+  def today
+    Date.today.ajd.to_f
+  end
+
+  def now
+    DateTime.now.ajd.to_f
+  end
+
+  def date(y,m,d)
+    Date.new(y,m,d).ajd.to_f
+  end
+
+  def datetime(text)
+    DateTime.parse(text.to_s).ajd.to_f
+  end
+
+  def time(h,m,s)
+    DateTime.valid_time?(h,m,s) ? DateTime.valid_time?(h,m,s).to_f : raise(ArgumentError, 'invalid time')
+  end
+
+end
+
+# John Carter's LittleLexer.
 #
 # http://www.rubyforge.org/projects/littlelexer
 #
@@ -321,21 +439,25 @@ if $0 == __FILE__
 
   formulas = %{
     This is some text;
-    ="This is some ""quoted"" text";
-    =((1+2)*(10-6))/2;
-    =datetime("2004-11-22 11:11:00")=DATE(2004,11,22)+TIME(11,11,00);
-    =IN(" is ", "this is a string");
-    =LIST(1, "two", 3.0);
-    =IN("b", LIST("a", "b", "c"));
-    =AND(TRUE, NULL);
-    =OR(TRUE, FALSE);
-    =IF(1+1=2, "yes", "no");
+    ="This is some ""quoted"" text"
+    =((1+2)*(10-6))/2
+    =datetime("2004-11-22 11:11:00")=DATE(2004,11,22)+TIME(11,11,00)
+    =IN(" is ", "this is a string")
+    =LIST(1, "two", 3.0)
+    =IN("b", LIST("a", "b", "c"))
+    =AND(TRUE, NULL)
+    =OR(TRUE, FALSE)
+    =IF(1+1=2, "yes", "no")
+    ="this" & " and " & "that"
+    =2^3
+    =25%+25.2%
   }
-
+  
   # single formula
   puts LXL.eval('=5+5').inspect # => 10
 
   # multiple formulas separated by semi-colon
-  puts LXL.eval(formulas).inspect # => ["This is some text", "This is some \"quoted\" text", 6, true, true, [1, "two", 3.0], true, false, true, "yes"]  
+  puts LXL.eval(formulas).inspect
+  # => ["This is some text", "This is some \"quoted\" text", 6, true, true, [1, "two", 3.0], true, false, true, "yes", "this and that", 8, 0.502]
 
 end