calculus 0.1.3 → 0.1.4

data/calculus.gemspec

@@ -10,7 +10,12 @@ Gem::Specification.new do |s|
   s.email       = ["sergey.avseyev@gmail.com"]
   s.homepage    = "http://avsej.net/calculus"
   s.summary     = %q{A ruby parser for TeX equations}
-  s.description = %q{A ruby parser for TeX equations. It parses equations to postfix (reverse polish) notation and can build abstract syntax tree (AST). Also it can render images via latex.}
+  s.description = %q{A ruby parser for TeX equations. It parses equations to postfix (reverse polish) notation and can build abstract syntax tree (AST). Also it can render images via latex. Requres modern ruby 1.9.x due to because of using advanced oniguruma regex engine}
+
+  s.has_rdoc     = true
+  s.rdoc_options = ['--main', 'README.rdoc']
+
+  s.required_ruby_version = '>= 1.9'
 
   s.rubyforge_project = "calculus"
 

data/lib/calculus.rb

@@ -4,7 +4,14 @@ require 'calculus/latex'
 require 'calculus/expression'
 
 module Calculus
+  # Raised when parser encounter invalid character
   class ParserError < Exception; end
+
+  # Raised when <tt>Expression</tt> detects during calculation that
+  # there are unbound variables presented
   class UnboundVariableError < Exception; end
+
+  # Raised when <tt>LaTeX</tt> mixin detect missing binaries for images
+  # rendering.
   class CommandNotFoundError < Exception; end
 end

data/lib/calculus/expression.rb

@@ -2,15 +2,48 @@ require 'digest/sha1'
 
 module Calculus
 
+  # This class represent some expression and optionaly transform it to
+  # the postfix notation for later analysis.
+  #
+  # Expression can introduce variables which could be substituted later
+  #
+  #   exp = Expression.new("x + 2 * 4")
+  #   exp.to_s                            #=> "x + 2 * 4"
+  #   exp.calculate                       # raises UnboundVariableError
+  #   exp["x"] = 5
+  #   exp.to_s                            #=> "5 + 2 * 4"
+  #   exp.calculate                       #=> 40
+  #
   class Expression
     include Latex
 
+    # Represents unique identifier of expression. Should be changed when
+    # some variables are binding
     attr_reader :sha1
+
+    # Source expression string
     attr_reader :source
 
+    # Array with postfix notation of expression
     attr_reader :postfix_notation
     alias :rpn :postfix_notation
 
+    # Initialize instance with given string expression.
+    #
+    # It is possible to skip parser.
+    #
+    #   # raises Calculus::ParserError: Invalid character...
+    #   x = Expression.new("\sum_{i=1}^n \omega_i \x_i")
+    #   # just stores source string and allows rendering to PNG
+    #   x = Expression.new("\sum_{i=1}^n \omega_i \x_i", :parse => false)
+    #   x.parsed?   #=> false
+    #
+    # It raises ArgumentError if there are more than one equal sign
+    # because if you need to represent the system of equations you
+    # should you two instances of <tt>Expression</tt> class and no
+    # equals sign for just calculation.
+    #
+    # Also it initializes SHA1 fingerprint of particular expression
     def initialize(source, options = {})
       options = {:parse => true}.merge(options)
       @source = source
@@ -20,30 +53,46 @@ module Calculus
       update_sha1
     end
 
+    # Returns <tt>true</tt> when postfix notation has been built
     def parsed?
       !@postfix_notation.empty?
     end
 
+    # Returns <tt>true</tt> if there equals sign presented
+    def equation?
+      @postfix_notation.include?(:eql)
+    end
+
+    # Returns array of strings with variable names
     def variables
       @variables.keys
     end
 
+    # Returns array of variables which have nil value
     def unbound_variables
       @variables.keys.select{|k| @variables[k].nil?}
     end
 
+    # Getter for given variable.
+    # Raises an <tt>Argument</tt> exception when there no such variable.
     def [](name)
       raise ArgumentError, "No such variable defined: #{name}" unless @variables.keys.include?(name)
       @variables[name]
     end
 
+    # Setter for given variable.
+    # Raises an <tt>Argument</tt> exception when there no such variable.
     def []=(name, value)
       raise ArgumentError, "No such variable defined: #{name}" unless @variables.keys.include?(name)
       @variables[name] = value
       update_sha1
     end
 
-    def traverse(&block)
+    # Perform traverse along postfix notation. Yields <tt>operation</tt>
+    # with <tt>left</tt> and <tt>right</tt> operands and the latest
+    # argument is the current state of <tt>stack</tt> (*note* you can
+    # amend this stack from outside)
+    def traverse(&block) # :yields: operation, left, right, stack
       stack = []
       @postfix_notation.each do |node|
         case node
@@ -59,6 +108,16 @@ module Calculus
       stack.pop
     end
 
+    # Traverse postfix notation and calculate the actual value of
+    # expression. Raises <tt>NotImplementedError</tt> when equation
+    # detected (currently it cannot solve equation) and
+    # <tt>UnboundVariableError</tt> if there unbound variables found.
+    #
+    # *Note* that there some rounding errors here in root operation
+    # because of general approach to calculate it:
+    #
+    #   1000 ** (1.0 / 3)   #=>   9.999999999999998
+    #
     def calculate
       raise NotImplementedError, "Equation detected. This class can't calculate equations yet." if equation?
       raise UnboundVariableError, "Can't calculate. Unbound variables found: #{unbound_variables.join(', ')}" unless unbound_variables.empty?
@@ -75,10 +134,12 @@ module Calculus
       end
     end
 
-    def equation?
-      @postfix_notation.include?(:eql)
-    end
-
+    # Builds abstract syntax tree (AST) as alternative expression
+    # notation. Return nested array where first member is an operation
+    # and the other operands
+    #
+    #   Calculus::Expression.new("x + 2 * 4").ast   #=> [:plus, "x", [:mul, 2, 4]]
+    #
     def abstract_syntax_tree
       traverse do |operation, left, right, stack|
         [operation, left, right]
@@ -86,6 +147,8 @@ module Calculus
     end
     alias :ast :abstract_syntax_tree
 
+    # Returns string representation of expression. Substitutes bound
+    # variables.
     def to_s
       result = source.dup
       (variables - unbound_variables).each do |var|
@@ -97,16 +160,21 @@ module Calculus
       result
     end
 
-    def inspect
+    def inspect # :nodoc:
       "#<Expression:#{@sha1} postfix_notation=#{@postfix_notation.inspect} variables=#{@variables.inspect}>"
     end
 
     protected
 
+    # Extracts variables from postfix notation and returns <tt>Hash</tt>
+    # object with keys corresponding to variables and nil initial
+    # values.
     def extract_variables
       @postfix_notation.select{|node| node.kind_of? String}.inject({}){|h, v| h[v] = nil; h}
     end
 
+    # Update SHA1 fingerprint. Used during initialization and when
+    # variables is bounding.
     def update_sha1
       @sha1 = Digest::SHA1.hexdigest([@postfix_notation, @variables].map(&:inspect).join('-'))
     end

data/lib/calculus/latex.rb

@@ -2,8 +2,13 @@ require 'tmpdir'
 
 module Calculus
 
+  # Renders expression to PNG image using <tt>latex<tt> and
+  # <tt>dvipng</tt>
   module Latex
 
+    # Basic latex template which use packages <tt>amsmath</tt> and
+    # <tt>amssymb</tt> from standard distributive and set off expression
+    # with <tt>$$</tt>.
     TEMPLATE = <<-EOT.gsub(/^\s+/, '')
       \\documentclass{article}
       \\usepackage{amsmath,amssymb}
@@ -13,6 +18,16 @@ module Calculus
       \\end{document}
     EOT
 
+    # Render image from source expression string. It is possible to pass
+    # <tt>background</tt> color (default: <tt>'White'</tt>) and
+    # <tt>density</tt> (default: <tt>700</tt>). See <tt>dvipng(1)</tt>
+    # page for details.
+    #
+    # Raises <tt>CommandNotFound</tt> exception when some tools not
+    # available.
+    #
+    # Returns path to images. *Note* that caller should take care about
+    # this file.
     def to_png(background = 'White', density = 700)
       raise CommandNotFoundError, "Required commands missing: #{missing_commands.join(', ')} in PATH. (#{ENV['PATH']})" unless missing_commands.empty?
 
@@ -29,6 +44,8 @@ module Calculus
       File.unlink("#{sha1}.dvi") if File.exists?("#{sha1}.dvi")
     end
 
+    # Check LaTeX toolchain availability and returns array of missing
+    # tools
     def missing_commands
       commands = []
       commands << "latex" unless can_run?("latex -v")
@@ -38,6 +55,7 @@ module Calculus
 
     protected
 
+    # Trial command and check if return code is zero
     def can_run?(command)
       `#{command} 2>&1`
       $?.exitstatus.zero?

data/lib/calculus/parser.rb

@@ -2,15 +2,62 @@ require 'strscan'
 
 module Calculus
 
+  # Parses string with expression or equation and builds postfix
+  # notation. It supprorts following operators (ordered by precedence
+  # from the highest to the lowest):
+  #
+  # +:sqrt+, +:exp+::   root and exponent operations. Could be written as
+  #                     <tt>\sqrt[degree]{radix}</tt> and <tt>x^y</tt>.
+  # +:div+, +:mul+::    division and multiplication. There are set of
+  #                     syntaxes accepted. To make division operator you
+  #                     can use <tt>num/denum</tt> or
+  #                     <tt>\frac{num}{denum}</tt>. For multiplication
+  #                     there accepted <tt>*</tt> and also two TeX
+  #                     symbols: <tt>\cdot</tt> and <tt>\times</tt>.
+  # +:plus+, +:minus+:: summation and substraction. Here you can use
+  #                     plain <tt>+</tt> and <tt>-</tt>
+  # +:eql+::            equals sign it has the lowest priority so it to
+  #                     be calculated in last turn.
+  #
+  # Also it is possible to use parentheses for grouping. There are plain
+  # <tt>(</tt>, <tt>)</tt> acceptable and also <tt>\(</tt>, <tt>\)</tt>
+  # which are differ only for latex diplay. Parser doesn't distinguish
+  # these two styles so you could give expression with visually
+  # unbalanced parentheses (matter only for image generation. Consider
+  # the example:
+  #
+  #   Parser.new("(2 + 3) * 4").parse   #=> [2, 3, :plus, 4, :mul]
+  #   Parser.new("(2 + 3\) * 4").parse  #=> [2, 3, :plus, 4, :mul]
+  #
+  # This two examples will yield the same notation, but make issue
+  # during display.
+  #
+  # Numbers could be given as a floats and as a integer
+  #
+  #   Parser.new("3 + 4.0 * 4.5e-10")   #=> [3, 4.0, 4.5e-10, :mul, :plus]
+  #
+  # Symbols could be just alpha-numeric values with optional subscript
+  # index
+  #
+  #   Parser.new("x_3 + y * E")         #=> ["x_3", "y", "E", :mul, :plus]
+  #
   class Parser < StringScanner
     attr_accessor :operators
 
+    # Initialize parser with given source string. It could simple
+    # (native expression like <tt>2 + 3 * (4 / 3)</tt>, but also in TeX
+    # style <tt>2 + 3 \cdot \frac{4}{3}.
     def initialize(source)
       @operators = {:sqrt => 3, :exp => 3, :div => 2, :mul => 2, :plus => 1, :minus => 1, :eql => 0}
 
       super(source.dup)
     end
 
+    # Run parse cycle. It builds postfix notation (aka reverse polish
+    # notation). Returns array with operations with operands.
+    #
+    #   Parser.new("2 + 3 * 4").parse               #=> [2, 3, 4, :mul, :plus]
+    #   Parser.new("(\frac{2}{3} + 3) * 4").parse   #=> [2, 3, :div, 3, :plus, 4, :mul]
     def parse
       exp = []
       stack = []
@@ -37,6 +84,12 @@ module Calculus
       exp
     end
 
+    # Fetch next token from source string. Skips any whitespaces
+    # matching regexp <tt>/\s+/</tt> and returs <tt>nil</tt> at when
+    # meet the end of string.
+    #
+    # Raises <tt>ParseError</tt> when encounter invalid character
+    # sequence.
     def fetch_token
       skip(/\s+/)
       return nil if(eos?)

data/lib/calculus/version.rb

@@ -1,3 +1,3 @@
 module Calculus
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -2,7 +2,7 @@
 name: calculus
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors: 
 - Sergey Avseyev
@@ -10,11 +10,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-12 00:00:00 +03:00
+date: 2011-05-13 00:00:00 +03:00
 default_executable: 
 dependencies: []
 
-description: A ruby parser for TeX equations. It parses equations to postfix (reverse polish) notation and can build abstract syntax tree (AST). Also it can render images via latex.
+description: A ruby parser for TeX equations. It parses equations to postfix (reverse polish) notation and can build abstract syntax tree (AST). Also it can render images via latex. Requres modern ruby 1.9.x due to because of using advanced oniguruma regex engine
 email: 
 - sergey.avseyev@gmail.com
 executables: []
@@ -42,8 +42,9 @@ homepage: http://avsej.net/calculus
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --main
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -51,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: "1.9"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: