linmeric 0.1.0 → 0.2.0

data/lib/linmeric/Archive.rb

@@ -1,21 +1,37 @@
 #! /usr/bin/env ruby
 
+##
+# This class provides a useful object to store the command history 
+# of linmeric
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Archive
+  # Creates a new Archive objects
   def initialize
     @myArray = []
     @i = 0
   end
   
+  # Adds a new item to the archive (it keeps the last 20 items
+  # which have been inserted).
+  #
+  # * **argument**: item to be added (mainly a String)
   def store(str)
     if @myArray.size == 20
       @myArray = @myArray[1...@myArray.size] + [str]
-      @i = @myArray.size
+      # @i = @myArray.size
     else
       @myArray[@myArray.size] = str
       @i = @myArray.size
     end
   end
   
+  # Returns the previous item compared to the pointer position
+  #
+  # * **returns**: saved object; "" if the pointer is already at the 
+  # beginning of the archive 
   def previous
     if not @i == 0 then
       @i -= 1
@@ -28,6 +44,10 @@ class Archive
     return ""
   end
   
+  # Returns the next item compared to the pointer position
+  #
+  # * **returns**: saved object; "" if the pointer is already at the 
+  # end of the Archive
   def next_
     if  @i < (@myArray.size - 1) 
       @i += 1
@@ -40,6 +60,7 @@ class Archive
     return ""
   end
   
+  # Moves the pointer to the top of the archive (the last element inserted)
   def top
     @i = @myArray.size
   end

data/lib/linmeric/Calculator.rb

@@ -0,0 +1,252 @@
+#! /usr/bin/env ruby
+
+require_relative "CnGal_new_classes.rb"
+
+##
+# This file contains a simple expression evaluator
+# to convert math binary operations in a result. 
+# It is simply a calculator
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
+module Calculator
+
+  OP = ["+","-","*","/","^"]
+  ##
+  # Definition of a simple token with an attribute (@tag)
+  # and a value (@val)
+  #
+  #
+  # Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+  # License:: Distributed under MIT license
+  class Token
+    # * **argument**: value to tokenize (String)
+    def initialize(value)
+      @val = value
+      if OP.include? value then
+        @tag = :OPERATOR
+      elsif value.number? then
+        @tag = :NUMBER
+        @val = value.to_n
+      elsif value == "(" then
+        @tag = :L_PAR
+      elsif value == ")" then
+        @tag = :R_PAR
+      end
+    end 
+    
+    # * **returns**: value of the token 
+    def value
+      return @val
+    end 
+    
+    # * **returns**: tag of the token
+    def tag
+      return @tag
+    end
+  end
+
+  ##
+  # This lexser creates the tokens splitting the input string
+  # according to the operators (OP => see Calculator ) or brackets
+  # it returns nil if an unaccepted char (non-number or non-OP or non-bracket)
+  # is found
+  #
+  #
+  # Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+  # License:: Distributed under MIT license
+  class Lexer
+  
+    # It creates the tokens according to `OP` or '(' and ')'
+    #
+    # * **argument**: the string that needs to be tokenized
+    # * **returns**: array of tokens if all the chars are correct; +nil+ else   
+    def tokenize(string)
+      stream = []
+      temp   = ""
+      for i in 0...string.size
+        if OP.include? string[i] or ["(",")"].include? string[i] then
+          stream << Token.new(temp) unless temp == ""
+          stream << Token.new(string[i])
+          temp = ""
+        elsif string[i].number? then
+          temp += string[i]
+        else
+          return nil
+        end
+      end
+      stream << Token.new(temp) unless temp == ""
+      return stream
+    end
+  end
+  
+  ##
+  # Evaluator parses and evaluates at the same time the stream of tokens
+  #
+  #
+  # Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+  # License:: Distributed under MIT license
+  class Evaluator
+    OPERATORS = {
+      "+" => lambda do |a,b|
+               return (a || 0) + (b || 0)
+             end,
+      "-" => lambda do |a,b|
+               return (a || 0) - (b || 0)
+             end,
+      "*" => lambda do |a,b|
+               return a * b
+             end,
+      "/" => lambda do |a,b|
+               unless b != 0
+                 @error = true 
+                 return nil
+               end
+               return a / b.to_f
+             end,
+      "^" => lambda do |a,b|
+               unless a != 0 and b != 0
+                 @error = true
+                 return nil
+               end
+               return a ** b
+             end
+    }
+    
+    # Evaluates the global expression
+    #
+    # * **argument**: stream of tokens (Array)
+    # * **returns**: result of the operations; +nil+ if an error occourred 
+    def evaluate(stream) 
+      @stack  = []
+      @stream = stream 
+      @i      = 0
+      @error  = false
+      return parse 
+    end
+    
+    # It parses the stream of tokens
+    #
+    # * **argument**: specific end-token (+nil+ default)
+    # * **returns**: result of the operations; +nil+ if an error occourred
+    def parse(m_end = nil) 
+      @num    = []
+      @op     = []
+      st = state0_1(0)
+      return nil if @error
+      @i += 1
+      while @i < @stream.size and current_tk.value != m_end do
+        st = self.send(st)
+        return nil if @error
+        @i += 1
+      end
+      return nil if st == :state_0_1
+      make_op
+      return @num.pop
+    end
+    
+    # State0_1 accepts only numbers or '('
+    #
+    # * **argument**: specification of which state must be runned (1 default)
+    # * **returns**: next state (symbol)
+    def state0_1(state = 1)
+      case current_tk.tag
+        when :NUMBER
+          @num.push current_tk.value
+        when :L_PAR
+          @i += 1
+          @stack.push @op
+          @stack.push @num
+          res = parse(")")
+          @num = @stack.pop
+          @num << res
+          @op = @stack.pop
+        when :OPERATOR
+          if (["+","-"].include? current_tk.value) and (state)== 0 then
+            @op.push current_tk.value
+            return :state0_1
+          else
+            @error = true
+          end
+        else
+          @error = true
+      end
+      return :state2
+    end
+    
+    # State2 accepts only operators
+    #
+    # * **returns**: next state (symbol)
+    def state2
+      if current_tk.tag == :OPERATOR then
+        if @op.size == 0 then
+          @op.push current_tk.value
+        elsif priority(current_tk.value) >= priority(@op.last)
+          @op.push current_tk.value
+        elsif priority(current_tk.value) < priority(@op.last)
+          make_op
+          @op.push current_tk.value
+        end
+      else
+        @error = true
+      end
+      return :state0_1
+    end
+    
+    # Solves the operations saved in @op
+    def make_op
+      while @op.size > 0 and !@error do
+        b = @num.pop
+        a = @num.pop
+        op = @op.pop
+        @num.push OPERATORS[op][a,b]
+      end
+    end
+    
+    # * **returns**: token of the current pointer value
+    def current_tk
+      return @stream[@i]
+    end
+    
+    # Returns the operator priority
+    #
+    # * **argument**: operator (string)
+    # * **returns**: priority (fixnum)
+    def priority(op)
+      case op
+        when "+","-"
+          return 1
+        when "*","/"
+          return 2
+        when /\^/
+          return 3
+      end
+    end
+  end
+  
+  # It solves the expression in string format
+  #
+  # * **argument**: expression to evaluate
+  # * **returns**: result of the expression; +nil+ if an error occourred
+  def self.solve(exp)
+    lexer = Lexer.new
+    evaluator = Evaluator.new
+    stream = lexer.tokenize(exp)
+    return nil if stream == nil
+    return evaluator.evaluate(stream)
+  end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/linmeric/CnGal_Matrix_class.rb

@@ -1,19 +1,33 @@
 #! /usr/bin/env ruby
 
+
 require_relative 'CnGal_new_classes.rb'
-require_relative 'CnGal_tools.rb'
 require_relative 'Listener.rb'
-# Definition of Matrix class
-#
+require_relative 'Calculator.rb'
 
 class InputError < ArgumentError; end
 class MyArgError < RuntimeError; end
 
+##
+# This class provides a simple representation of a matrix with the main
+# features, operations and some useful method to manipulate it or to make 
+# its creation easier.
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Matrix
   
+  # Initialization of  new matrix in two different ways (chosen by
+  # the user): 
+  # * a block can be given to create a matrix according to a function
+  # * the user must insert each value by hand (if block is not given)
+  #
+  # * **requires**: `#solve` of Calculator
+  # * **argument**: number of rows (Fixnum)
+  # * **argument**: number of columns (Fixnum)
+  # * **block**: yields a function with two arguments (optional)
   def initialize(rws = 0,cls = 0)
     listener = Listener.new
-#    @exception = "Matrix "
     if rws == 0 or cls == 0 or rws.is_a? Float or cls.is_a? Float then 
       raise MyArgError,"   Argument Error: invalid dimension #{rws}x#{cls} for Matrix object" 
     elsif !(rws.is_a? Fixnum) or !(cls.is_a? Fixnum) then
@@ -31,21 +45,18 @@ class Matrix
           end
         end       
       else
-#        if @exception == "Matrix " then
           puts "Insert the line values (separated by space) and press return to go on"
           for i in 0...rws
             listener.reset
             cl = listener.gets.split
             raise ArgumentError, "  #{cls} element(s) expected but #{cl.size} found. Retry" unless cl.size==cls
             cl.map! { |e| 
-              cv = Tool.convert(e)
+              cv = Calculator.solve(e)
               err = e if cv == nil
               raise MyArgError, "  Argument Error: Invalid operation '#{err}' found in matrix rows" unless cv != nil
               e = cv
             }
             @mx +=cl 
-#           end  
-#           puts 
         end
       end
     end
@@ -58,8 +69,11 @@ class Matrix
       
   end
    
+  # Creates a new matrix loading it from a .csv file
+  #
+  # * **argument**: `String` of the file path
+  # * **returns**: new matrix object 
   def Matrix.from_file(filename = "")
-#    @exception = "Matrix "
     @mx = []
     @MyCls = 0
     @MyRws = 0
@@ -70,7 +84,7 @@ class Matrix
         @MyRws += 1
         ln = ln.chomp.split(',')
         ln.map! do |el| 
-          cv = Tool.convert(el)
+          cv = Calculator.solve(el)
           err = el if cv == nil
           raise InputError, "  Argument Error: Invalid operation '#{err}' found in matrix rows" unless cv != nil
           el = cv
@@ -78,23 +92,16 @@ class Matrix
         @mx += ln
         if @mx.size % ln.size != 0 then
           raise MyArgError, "  Argument Error: Irregular matrix rows"
-#          break
         end
         @MyCls = ln.length
       end
     end
-#    mat = Matrix.new(1,1) {1}
-#    mat.update(@mx,@MyRws,@MyCls)
-#    mat.inherit_exception(@exception)
     return mat = Matrix.new(@MyRws,@MyCls) {|i,j| @mx[i*@MyCls+j]}
-    
-#    rescue InputError => error
-#      @exception += "#{error}"
-#      mat = Matrix.new(1,1) {1}
-#      mat.inherit_exception(@exception)
-#      return mat
   end 
   
+  # Writes the matrix on a file
+  #
+  # * **argument**: `String` of the file path
   def to_file(filename = "")
     if !(Dir.exist? File.dirname(filename)) or filename == "" then
       raise MyArgError, "  Argument Error: Invalid directory; Directory not found"
@@ -110,40 +117,42 @@ class Matrix
     end
   end
   
-#  def raised_exception?
-#    return nil if @exception == "Matrix "
-#    return @exception
-#  end 
-  
-#  def got_exception()
-#    @exception = "Matrix "
-#  end
-  
-  def show()
+  # converts this matrix object to a string
+  def to_s()
     max = 0
-    @mx.each{ |n| max = n.to_s.size if n.to_s.size > max}
+    str = ""
+    @mx.each{ |n| max = "#{n.round(3)}".size if "#{n.round(3)}".size > max}
     for i in 0...@MyRws do
-      print '|'
+      str += '|'
       for j in (i*(@MyCls))...(i*(@MyCls)+@MyCls) do
-        print "  #{" "*(max-@mx[j].to_s.size)}#{@mx[j] }"
+        str += "  #{" "*(max-@mx[j].round(3).to_s.size).abs}#{@mx[j].round(3) }"
       end
-      puts '  |'
+      str+= "  |\n"
     end
-    return nil
+    return str
   end
   
+  # * **returns**: `Fixnum` of number of columns
   def getCls()
     return @MyCls
   end
   
+  # * **returns**: `Fixnum` of number of rows
   def getRws()
     return @MyRws
   end
   
+  # * **returns**: `Array` on which the matrix is saved
   def export()
     return @mx
   end
   
+  # Updates this matrix after the array in which it was saved has been
+  # manually modified
+  #
+  # * **argument**: `Array` on which the new matrix is saved
+  # * **argument**: `Fixnum` of number of rows
+  # * **argument**: `Fixnum` of number of columns
   def update(mat,rws,cls)
     if !(mat.is_a? Array) then
       raise MyArgError, "  Argument Error: invalid matrix array found"
@@ -152,17 +161,18 @@ class Matrix
         raise MyArgError, "  Argument Error: colums and rows in Integer format expected but #{e.class} found" unless e.is_a? Numeric
       end
     end
-#    if @exception == "Matrix " then
      @mx = mat
      @MyRws = rws
      @MyCls = cls
-#    end
   end
-  
-#  def inherit_exception(exception)
-#     @exception = exception
-#   end
-  
+
+  # Gives access to each component of a matrix.
+  # It accepts two kinds of arguments: `Fixnum` or `Range`
+  # to get a specific component or a collection of components (eg. a whole row)
+  #
+  # * **argument**: `Fixnum` or `Range` of row
+  # * **argument**: `Fixnum` or `Range` of column  
+  # * **returns**: `Numeric` if an only component has been required; `Matrix` else
   def [](x,y)
     if x.is_a? Numeric and y.is_a? Numeric then
       return @mx[x*@MyCls + y]
@@ -190,10 +200,20 @@ class Matrix
     return nil
   end
   
+  # Allows direct overwriting of a component
+  #
+  # * **argument**: `Fixnum` of row number
+  # * **argument**: `Fixnum` of column number
+  # * **argument**: `Numeric` to overwrite the component value
   def []=(i,j,val)
+    raise ArgumentError, "  Argument Error: Numeric value expected but #{val.class} found" unless val.is_a? Numeric
     @mx[i*@MyCls + j] = val
   end
-  
+ 
+  # Compares the current matrix with another object
+  #
+  # * **argument**: `Object` to be compared with
+  # * **returns**: +true+ if two equal matrix are compered; +false+ else  
   def ==(obj)
    if obj.is_a? Matrix then
      if (self.getCls == obj.getCls && self.getRws == obj.getRws ) then
@@ -203,6 +223,10 @@ class Matrix
    return false
   end
   
+  # Checks if this matrix is different from another object
+  #
+  # * **argument**: `Object` to be compared with
+  # * **returns**: +true+ if the matrix and the object are different; +false+ else
   def !=(obj)
     if obj.is_a? Matrix then
       self == obj ? (return false) : (return true)
@@ -211,6 +235,11 @@ class Matrix
     end
   end
   
+  # Checks if this matrix and the given object have the same features
+  #
+  # * **argument**: `Object`
+  # * **returns**: +true+ if `obj` is a `Matrix` and has the same rows and colum number;
+  # +false+ else
   def similar_to?(obj)
     if obj.is_a? Matrix then
       (self.getCls == obj.getCls && 
@@ -219,6 +248,10 @@ class Matrix
     return false
   end
   
+  # Sums the current matrix to another
+  #
+  # * **argument**: `Matrix` to be summed to
+  # * **returns**: `Matrix` object
   def +(m)
     if m.is_a? Matrix then
       if m.similar_to? self then
@@ -231,6 +264,10 @@ class Matrix
     end
   end
  
+  # Subtracts the current matrix to another
+  #
+  # * **argument**: `Matrix` to be subtracted to
+  # * **returns**: `Matrix` object
   def -(m)
     if m.is_a? Matrix then
       if m.similar_to? self then
@@ -243,6 +280,11 @@ class Matrix
     end
   end
   
+  # Checks if the given object can be multiplied to the matrix
+  #
+  # * **argument**: `Object`
+  # * **returns**: +true++ if `obj` is a `Numeric` or a good `Matrix` for '*' operation;
+  # +false+ else
   def can_multiply?(obj)
     if obj.is_a? Matrix then
       (self.getCls == obj.getRws) ? (return true) : (return false)
@@ -252,6 +294,10 @@ class Matrix
     return false
   end
   
+  # Multiplies the current matrix to another
+  #
+  # * **argument**: `Matrix` to be multiplied to
+  # * **returns**: `Matrix` object
   def *(ob)
     case 
       when (ob.is_a? Numeric)
@@ -276,27 +322,44 @@ class Matrix
     end
   end
   
-  
+  # Checks if the given object can divide the current matrix
+  #
+  # * **argument**: `Object`
+  # * **returns**: +true+ if `obj` is a Numeric; +false+ else
   def can_divide?(obj)
     return (obj.is_a? Numeric)
   end
   
-  
+  # Divides each element of the current matrix to a `Numeric` value
+  #
+  # * **argument**: `Numeric`
+  # * **returns**: `Matrix` object
   def /(obj)
     return Matrix.new(@MyRws,@MyCls) { |i,j| self[i,j] / obj.to_f} if obj.is_a? Numeric
     raise MyArgError, "  Argument Error: Invalid division between Matrix and #{obj.class} "
   end
   
+  # Elevates each element of the current matrix to a `Numeric` exponent
+  #
+  # * **argument**: `Numeric`
+  # * **returns**: `Matrix` object
   def **(obj)
     return Matrix.new(@MyRws,@MyCls) { |i,j| self[i,j] ** obj} if obj.is_a? Numeric
     raise MyArgError, "  Argument Error: Invalid power Matrix-#{obj.class} "
   end
   
+  # Trasposes a matrix
+  #
+  # **returns**: `Matrix` object
   def tr()
     return Matrix.new(@MyCls,@MyRws) { |i,j| @mx[j * @MyCls + i]}
   end
   
-  def norma()
+  # Calculates the norm of a matrix, defined as
+  # sqrt(sum(m[i,j]**2))
+  #
+  # * **returns**: `Float` value
+  def norm()
    sum=0
    @mx.map do |e|
      sum +=e**2
@@ -304,10 +367,16 @@ class Matrix
    return Math.sqrt(sum)
   end
   
+  # Checks if the matrix is squared
+  #
+  # * **returns**: +true+ if the matrix is squared; +false+ else
   def is_squared?()
     self.getCls == self.getRws ? (return true) : (return false)
   end
   
+  # Calulates the determinant of the matrix using the Laplace's algorithm
+  #
+  # * **returns**: `Numeric` value
   def laplace
     if self.is_squared? then
       return (self[0,0] * self[1,1]) - (self[0,1] * self[1,0]) if self.getRws == 2 
@@ -322,7 +391,12 @@ class Matrix
     end
   end
   
+  # Builds an identity matrix
+  #
+  # * **argument**: `Fixnum` of the matrix dimension
+  # * **returns**: `Matrix` object
   def Matrix.identity(n)
+    raise MyArgError, "Argument Error: expecting Fixnum value, but #{n.class} found" unless n.is_a? Fixnum
     return Matrix.new(n,n) { |i,j|  (i == j) ? 1 : 0 }
   end
   
@@ -331,8 +405,17 @@ class Matrix
   end
   
   private
-  
+   
+   # Private method to delete rows and columns from a matrix
+   #
+   # * **argument**: `Matrix`
+   # * **argument**: row number (`Fixnum`)
+   # * **argument**: column number (`Fixnum`)
+   # * **returns**: `Matrix` object 
    def del_rwcl(mx,rw,cl)
+     [rw,cl].each do |arg| 
+       raise MyArgError,"Argument Error: row and column in Fixnum format expected, but #{arg.class} found" unless arg.is_a? Fixnum
+     end
      rd = mx.export.clone
      cols = mx.getCls
      for i in 0...cols
@@ -344,8 +427,6 @@ class Matrix
      cl = mx.getCls - 1
      return Matrix.new(rw,cl) { |i,j| rd[i*cl+j]}
    end
-   
-  protected
   
    
 end