linmeric 0.1.0 → 0.2.0

data/lib/linmeric/CnGal_new_classes.rb

@@ -2,93 +2,141 @@
 
 require_relative 'Function_class.rb'
 
-# Adding some method to Numeric class
-# to work properly with CnGal project
-
+##
+# Overload of Numeric class
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Numeric 
-
+  
+  # Compares the value with another object
+  #
+  # * **argument**: object for the comparison
+  # * **returns**: +true+ if the object is a `Numeric`; +false+ else. 
   def is_similar?(obj)
     (obj.is_a? Numeric) ? (return true) : (return false)
   end
   
+  # Checks if the numeric value can be multiplied by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is `Numeric` or Matrix; +false+ else. 
   def can_multiply?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
   
+  # Checks if the numeric value can be divided by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is `Numeric` or Matrix; +false+ else. 
   def can_divide?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
 
-  def show()
-    puts self
-  end
-
 end
 
-# Adding some method to Fixnum class
-# to work properly with CnGal project
-
+##
+# Overload of Fixnum class
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Fixnum 
+
+  # Compares the value with another object
+  #
+  # * **argument**: object for the comparison
+  # * **returns**: +true+ if the object is a Numeric; +false+ else.
   def similar_to?(obj)
     (obj.is_a? Numeric) ? (return true) : (return false)
   end
   
+  # Checks if the fixnum value can be multiplied by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is Numeric or Matrix; +false+ else.
   def can_multiply?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
   
+  # Checks if the fixnum value can be divided by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is Numeric or Matrix; +false+ else. 
   def can_divide?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
   
-  def show()
-    puts self
-  end
 end
 
 
-# Adding some method to Float class
-# to work properly with CnGal project
-
+##
+# Overload of Float class
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Float 
+
+  # Compares the value with another object
+  #
+  # * **argument**: object for the comparison
+  # * **returns**: +true+ if the object is a Numeric; +false+ else.
   def similar_to?(obj)
     (obj.is_a? Numeric) ? (return true) : (return false)
   end
   
+  # Checks if the float value can be multiplied by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is Numeric or Matrix; +false+ else.
   def can_multiply?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
   
+  # Checks if the float value can be divided by a given object
+  #
+  # * **argument**: object for the checking
+  # * **returns**: +true+ if the object is Numeric or Matrix; +false+ else.   
   def can_divide?(obj)
     (obj.is_a? Numeric) ? (return true) : ((obj.is_a? Matrix) ? (return true) : (return false))
   end
-
-  def show()
-    puts self
-  end
   
 end
 
+##
+# Overload of NilClass
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class NilClass
-  def show
-    puts "nil"
+  
+  # * **returns**: string representation of +nil+
+  def to_s
+    return "nil"
   end
   
+  # * **returns**: 0
   def size
     return 0
   end
   
 end
 
-# Adding some method to String class:
-# contain? returns true whether the current string contains one of the
-# chars in str
-# contain_all? returns true whether the current string contains all the 
-# chars in str
-# compact returns a string without spaces
-
+##
+# Overload of String class
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class String
 
+  # Checks if the string contains at least a character of the given one.
+  #
+  # * **argument**: string for the checking
+  # * **returns**: +true+ if a character in common is found; +false+ else.
   def contain?(str)
     raise ArgumentError, '' unless str.is_a? String
     str.each_char do |ch|
@@ -101,17 +149,26 @@ class String
       retry
   end
   
+  # Checks if the string contains all the characters of the given one.
+  # 
+  # * **argument**: string for the checking
+  # * **returns**: +true+ if the string contins all the chars of the argument;
+  # +false+ else
   def contain_all?(str)
     raise ArgumentError, '' unless str.is_a? String
     str.each_char do |ch|
       return false if not self.include? ch
     end
     return true
+    
     rescue ArgumentError
       str = str.to_s
       retry
   end
   
+  # Deletes spaces from a string
+  #
+  # * **returns**: new string
   def compact()
     nstr = ''
     self.each_char do |ch|
@@ -120,6 +177,10 @@ class String
     return nstr
   end
   
+  # Subtracts the substring to the main
+  #
+  # * **argument**: substring
+  # * **returns**: new string
   def -(str)
     myStr = str.to_s
     temp = ''
@@ -139,34 +200,52 @@ class String
     return temp
   end
   
+  # Checks if the strings represents a `Fixnum` value
+  #
+  # * **returns**: +true+ if the string represents a `Fixnum`; +false+ else
   def integer?
     [                          # In descending order of likeliness:
       /^[-+]?[1-9]([0-9]*)?$/, # decimal
       /^0[0-7]+$/,             # octal
       /^0x[0-9A-Fa-f]+$/,      # hexadecimal
       /^0b[01]+$/,             # binary
-      /[0]/                     # zero
+      /[0]/                    # zero
     ].each do |match_pattern|
       return true if self =~ match_pattern
     end
     return false
   end
 
+  # Checks if the strings represents a `Float` value
+  #
+  # * **returns**: +true+ if the string represents a `Float`; +false+ else
   def float?
     pat = /^[-+]?[1-9]([0-9]*)?\.[0-9]+$/
     return true if self=~pat 
     return false 
   end
   
+  # Checks if the string represents a number
+  #
+  # * **returns*: +true+ if the string represents a number; +false+ else
   def number?
     (self.integer? or self.float?) ? (return true) : (return false)
   end
 
+  # Converts a string to a number
+  #
+  # * **returns**: `Float` value if the string represents a float
+  # `Fixnum` value if the string represents a fixnum; 0 else. 
   def to_n
     return self.to_f if self.float?
     return self.to_i if self.integer? 
+    return 0
   end
   
+  # Removes a character at the given index
+  #
+  # * **argument**: index of the character (`Fixnum`)
+  # * **returns**: new string
   def remove(index)
     return self if index < 0
     n_str = ''
@@ -177,11 +256,19 @@ class String
   end
 end
 
+##
+# Defining a subclass of string to identify a fileneme
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Filename < String
-  def show
-    puts self
+  
+  def to_s
+    return self
   end
   
+  # * **returns**: name of the file (`String`)
   def name
     i = self.size - 1
     nm = ''
@@ -192,28 +279,43 @@ class Filename < String
     return nm.reverse
   end
   
+  # * **argument**: class name
+  # * **returns**: +true+ if `self.class` = `obj`; +false+ else
   def is_a?(obj)
-    self.class == obj.class ? (return true) : (return false)
+    self.class == obj ? (return true) : (return false)
   end
   
 end
 
+##
+# Definition of a dimension (structure: from-to)
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Dim
+  
+  # * **argument**: string to be converted to a dimension
   def initialize(str)
     str = str - '"'
     str = str.split(',')
     if str.size == 2 and str[0] != "" and str[1] != "" then
-      @sx = str[0].to_n if str[0].integer? or str[0].float?
-      @dx = str[1].to_n if str[1].integer? or str[1].float? 
+      str.each do |val|
+        puts '  Argument Error: wrong range format' unless val.number?
+      end
+      @sx = str[0].to_n
+      @dx = str[1].to_n
     else
-      puts '  Argument Error: wrong range format'#; puts
+      puts '  Argument Error: wrong range format'
     end
   end
   
+  # * **returns**: left dimension value
   def sx()
     return @sx
   end
   
+  # * **returns**: right dimension value
   def dx()
     return @dx
   end

data/lib/linmeric/CnGal_tools.rb

@@ -2,79 +2,62 @@
 
 require_relative 'CnGal_new_classes.rb'
 
+##
+# Provides some useful procedure for linmeric
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 module Tool
+  
+  # * **returns**: array of all the keywords used by linmeric
   def self.keys 
     return ["mx:","t:", "shw:","shwvar:","det:","solve:","from:","as:","f:","norm:","id_mx:","integ:"]
   end
   
+  # * **returns**: array of all the operators
   def self.operators
     return ["=","-","+","*","/","^",">"]
   end
   
+  # * **returns**: alphabet in string format
   def self.letters
     return "abcdefghijklmnopqrstuvwxyz"
   end
   
+  # **returns**: array of the supported math functions; see: Function
   def self.f
     return ["log","sin","cos","PI","tan","exp"]
   end
   
+  # Checks if a string represents a keyword
+  #
+  # * **argument**: object to check
+  # * **returns**: +true+ if `ob` represents a keyword; +false+ else. 
   def self.is_keyword?(ob)   
     (self.keys.include? ob) ? (return true) : (return false)
   end
   
+  # Dummy function to ckeck if a string represents an expression (may not work properly)
+  #
+  # * **argument**: string to be checked
+  # * **returns**: +true+ if `str` represents an expression; +false+ else.
   def self.is_exp?(str)
     (str.contain? "=+*-/^") ? (return true) : (('0123456789.'.contain_all? str) ? 
     (return true):((self.letters.contain? str) ? (return true):(return false)))
   end
   
+  # Prints the hash of the variables
+  #
+  # * **argument**: hash to be printed
   def self.print_stack(stack)
     stack.keys.each do |k|
       puts "#{k} = " if stack[k].is_a? Matrix
       print "#{k} = " unless stack[k].is_a? Matrix
-      stack[k].show
+      puts stack[k]
     end
   end
   
-  def self.convert(string)
-     raise ArgumentError, '' unless string.is_a? String
-     if string.contain? '*/-+^' then
-       case
-         when (string.include? '^')
-           string = string.split('^')
-           string << '**'
-         when (string.include? '*')
-           string = string.split('*')
-           string << '*'
-         when (string.include? '/')
-           string = string.split('/')
-           string << '/'
-         when (string.include? '-')
-           string = string.split('-')
-           string << '-'
-         when (string.include? '+')
-           string = string.split('+')
-           string << '+'
-       end
-       if string.size == 3 then
-         return eval("convert(string[0]) #{string[2]} convert(string[1])")
-       elsif string.size == 2 then
-         return eval("#{string[2]} convert(string[0])")
-       else
-         return nil
-       end
-     elsif '0123456789.'.contain_all? string then
-         return string.to_f
-     else
-       return nil
-     end
-     
-     rescue ArgumentError
-       string = string.to_s
-       retry
-  end
-
-  
 end
 
 

data/lib/linmeric/Error_print.rb

@@ -1,63 +1,97 @@
 #! /usr/bin/env ruby
 
+##
+# This modue provides a set of error messages for linmeric
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 module PrintError
+
+  # Main function that prints the error message
+  #
+  # * **argument**: message to be printed (string)
+  # * **argument**: expression (commands) where the error has been found
+  # * **argument**: error position
   def self.print(message,expression,pos)
     puts message
     puts expression
     puts " " * pos + "^"
-    #puts
   end
   
+  # * **argument**: unexpected Token
+  # * **argument**: expression (commands) where the error has been found
   def self.default(token,expression)
     message = "  Sintax Error: unexpected #{token.attribute} token '#{token.me}' found"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: unexpected Token
+  # * **argument**: expression (commands) where the error has been found
   def self.reduced(token,expression)
     message = "  Sintax Error: unexpected #{token.attribute} '#{token.me}' found"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: unknown Token found
+  # * **argument**: expression (commands) where the error has been found
   def self.unknown(token,expression)
     message = "  Sintax Error: unknown #{token.attribute} '#{token.me}' found"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: missmatched Token found
+  # * **argument**: expression (commands) where the error has been found
+  # * **argument**: token type (String) expected
   def self.missmatch(token,expression,expectation)
     message = "  Sintax Error: expecting #{expectation} but #{token.attribute} token '#{token.me}' found"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: Token arguments are missing for
+  # * **argument**: expression (commands) where the error has been found
   def self.missing(token,expression)
     message = "  Sintax Error: missing argument for '#{token.me}' #{token.attribute}"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: expression (commands) where the error has been found
+  # * **argument**: position where the error is located
   def self.no_final_quotes(expression,position)
     message = "  Sintax Error: missing quotes for block"
     self.print(message,expression,position)
   end
   
+  # * **argument**: position where the error is located
+  # * **argument**: expression (commands) where the error has been found
   def self.missing_general_string(position,expression)
     message = "  Sintax Error: missing agument block"
     self.print(message,expression,position)
   end
   
+  # * **argument**: position where the error is located
+  # * **argument**: expression (commands) where the error has been found
   def self.numPoint_missing(position,expression)
     message = "  Sintax Error: number of points is missing"
     self.print(message,expression,position)
   end
   
+  # * **argument**: position where the error is located
+  # * **argument**: expression (commands) where the error has been found
   def self.missing_expression_after_equal(pos,expression)
     message = "  Sintax Error: missing expression after EQUAL operator"
     self.print(message,expression,pos)
   end
   
+  # * **argument**: unexpected Token found
+  # * **argument**: expression (commands) where the error has been found
   def self.unexpected_token_in_solve(token,expression)
     message = "  Sintax Error: unexpected #{token.attribute} token '#{token.me}' in 'solve:' args"
     self.print(message,expression,token.position)
   end
   
+  # * **argument**: position where the error is located
+  # * **argument**: expression (commands) where the error has been found
   def self.missing_integ_range(pos,expression)
     message = "  Sintax Error: missing integration range for 'integ:' method"
     self.print(message,expression,pos)

data/lib/linmeric/Function_class.rb

@@ -3,7 +3,17 @@
 require_relative 'CnGal_new_classes.rb'
 require_relative 'Integrators.rb'
 
+##
+# This class provides a simple representation of a function and some method
+# to manipulate it
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Function
+  
+  # Creates a new `Function` object
+  # * **argument**: string to be converted (and representing a function) 
   def initialize(str)
     @inp = str
     @vars = []
@@ -11,23 +21,37 @@ class Function
     @funct = convert(str)
   end
   
+  # Tells whether the function has been correctly converted from the string
+  # format
+  #
+  # * **returns**: +true+ if the function has been successfully converted; +false+ else
   def ok? 
     @funct == nil ? (return false) : (return true)
   end
   
+  # Returns the function as a ruby block ({ |...| ... })
+  # * **argument**: number of variables needed for the block; default value is set if n == 0
+  # * **returns**: string that represents the block; +nil+ if an error is found
   def to_block(n = 0)
-    n = @vars.size if n == 0
     return nil if not self.ok?
     return nil if n < @vars.size
-    b_v = "|#{vars(n)}|" if @vars.size > 0
+    n = @vars.size if n == 0
+    b_v = "|#{vars(n)}|" if n > 0
     return "{ #{b_v} #{@funct} }"
   end
   
+  # Builds the list of the variables needed for the block
+  #
+  # * **argument**: number of variables needed for the block
+  # * **returns**::
+  #   * +nil+ if an error occourred while converting the function
+  #   * +nil+ if `n` is less than the number of variables of the function
+  #   * string representation of the list
   def vars(n = 0)
     n = @vars.size if n == 0
     return nil if not self.ok?
     return nil if n < @vars.size 
-    var = @vars[0]
+    var = (@vars.size > 0) ? @vars[0] : ""
     for i in 1...@vars.length do
       var += ',' + @vars[i]
     end
@@ -36,7 +60,8 @@ class Function
       ('a'..'z').each do |ch|
         unless @vars.include? ch
           i +=1
-          var += ',' + ch
+          var += ',' unless var == ""
+          var += ch
           break if i == (n - @vars.size)
         end
       end
@@ -44,10 +69,19 @@ class Function
     return var
   end
   
-  def show()
-    puts @inp
+  # * **returns**: string representation of the function
+  def to_s
+    return @inp
   end
-  
+ 
+  # Integrates the function according to the specified method (see: Integrators)
+  #
+  # * **argument**: dimension of the range; see: Dim
+  # * **argument**: number of points for integration
+  # * **argument**: method to integrate the function (optional). 'simpson' is default
+  # * **returns**: 
+  #   * Numeric value as result
+  #   * +nil+ if an error occourred
   def integrate(r,n,m = 'simpson')
     return nil unless self.ok?
     block = self.to_block(1)
@@ -67,25 +101,29 @@ class Function
         when "boole"
           return eval("Integrators.boole(r.sx,r.dx,n)#{block}")
         else
-          puts "Argument Error: Invalid integration method"; #puts
+          puts "Argument Error: Invalid integration method";
           return nil
       end
     end
-    puts "Argument Error: bad function for integration"; #puts
+    puts "Argument Error: bad function for integration";
     return nil
   end
   
  private
   
+  # Splits the input string into its components (variables,operators...)
+  # 
+  # * **argument**: input function in string format (inserted by the user)
+  # * **returns**: array containing the components of the function 
   def tokenize(str)
     tokens = Array.new
-    x = ''
+    x = ""
     str.each_char do |ch|
       case ch
         when /[\+\-\*\/\^\(\)]/
           tokens.push ch
         when /[a-zA-Z\0-9\.]/
-          x = tokens.pop if not '+-*/^()'.include? tokens[tokens.size - 1].to_s
+          x = tokens.pop if not '+-*/^()'.include? tokens[tokens.size - 1].to_s and tokens.size > 0
           tokens.push (x + ch)
           x = ""
         else
@@ -95,6 +133,10 @@ class Function
     return tokens
   end
   
+  # Converts the function inerted by the user in a function written in Ruby language
+  #
+  # * **argument**: input function in string format (inserted by the user)
+  # * **returns**: function understandable by Ruby in string format
   def convert(str)
     return nil unless str.is_a? String
     str = tokenize(str)
@@ -103,6 +145,12 @@ class Function
     return translate(str)
   end
   
+  # Checks if the brackets are balanced in the input function
+  #
+  # * **argument**: array of the function components 
+  # * **returns**:
+  #   * +nil+ if `expr` is not an array
+  #   * +true+ if the brackets are balanced; +false+ else
   def balanced_brackets?(expr)
     return nil unless expr.is_a? Array
     brakets = 0
@@ -117,12 +165,23 @@ class Function
     brakets == 0 ? (return true) : (return false)
   end
   
+  # Translates the function from linmeric language to Ruby language
+  # using a turing machine to detect possible errors
+  #
+  # * **argument**: array of the function components
+  # * **argument**: boolean to identify whether we are inside brackets or not. +false+ default
+  # (out brackets)
+  # * **returns**:
+  #   * +nil+ if `str` is not an array
+  #   * function in Ruby language in string format 
   def translate(str,open_b = false)
     return nil unless str.is_a? Array
     funct = ""
     state = 0
     while @i < str.size
       case state
+      
+        # beginning state
         when 0
           case str[@i]
             when /[\+\-]/