matrix_dsl 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jasim A Basheer
+
+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.markdown

@@ -0,0 +1,52 @@
+Matrix Transformations 
+=================
+
+Simple DSL for transforming matrices using notation similar to those given in Maths texts. Uses treetop for language parsing.
+
+You can execute script similar to:
+
+    M1 = [ [ 1 2 3 ]
+           [ 4 9 6 ]
+           [ 9 1 5 ]
+         ]
+
+    Transform M1:
+      R2 <- 2R2 + R3
+      C3 <- C3 - C1
+
+    det_m1 = det M1
+
+    x = 3
+    M2 = ((3/4) * x) * M1
+
+    det_m2 = det M2
+    rank_m2 = rank M2
+
+
+Features:
+---------
+
+  *  No control structures. This would be a minimal DSL than a turing-complete language.
+
+  *  Variables, Expressions and Arithmetic evaluation.
+  *  Row/Column Matrix transformations
+  *  Matrix functions - inverse, determinant, rank and transpose.
+  *  A few arithmetic functions (from Ruby Math module)
+
+Usage
+==========
+
+    gem install matrix_dsl
+    matrix_dsl_run < curl http://github.com/jasim/matrix_transformations/blob/master/example.matrix_dsl
+
+To integrate Matrix DSL scripts into your code, please have a look at http://github.com/jasim/matrix_transformations/blob/master/tests/basic_test.rb
+
+Questions/Feedback
+------------------
+I'd appreciate any! Feel free to reach me at jasim.ab@gmail.com.
+
+
+Todo
+-----
+  * Allow comments in script
+  * Enable fractions in place of floats.

data/example.matrix_dsl

@@ -0,0 +1,11 @@
+
+x=33
+m1=[ [10 23]
+     [45 33]
+   ]
+
+d_m1 = det m1
+rank_m1 = rank m1
+
+m2 = m1 * x
+d_m2 = det m2

data/lib/matrix_dsl.rb

@@ -0,0 +1,178 @@
+require 'treetop'
+require 'matrix'
+
+module MatrixDSL
+  
+  # In the given 'matrix', sets the value of the 'row_col_identifier' (R1, C1 etc.) to the array 'value'
+  # ie: in M=Matrix[[1 2][2 4]], apply_row_col_transformation(M, "C1", [9 8]) would give M=Matrix[[9 2][8 4]]
+  def apply_row_col_transformation(matrix, row_col_identifier, value)
+      m=matrix.to_a
+      if row_col_identifier.row_or_col=='R'
+        # Row transformation. Apply the result to the resultant row.
+        m[row_col_identifier.index] = value.to_a
+      else
+        # Column transformation. 
+        m=m.transpose
+        m[row_col_identifier.index] = value.to_a
+        m=m.transpose
+      end
+      
+      Matrix[*m]   
+  end
+  
+  # stores all identifier variables used inside the DSL-based script.
+  $matrix_dsl_vars ||= {}
+
+  class NodeIdentifier < Treetop::Runtime::SyntaxNode
+    def name
+      text_value
+    end
+    def value
+      raise "Variable #{name} not declared." unless $matrix_dsl_vars.include? text_value
+      $matrix_dsl_vars[text_value]
+    end
+  end
+  
+  # Used where a Matrix variable is expected as the identifier. (ie: in 'Transform M1', M1 should be a matrix variable.) 
+  class MatrixIdentifier < Treetop::Runtime::SyntaxNode
+    def name
+      text_value
+    end
+    def value
+      raise "Variable #{name} not declared." unless $matrix_dsl_vars.include? text_value
+      raise "Variable #{name} not a Matrix." unless $matrix_dsl_vars[text_value].class == Matrix
+      
+      $matrix_dsl_vars[text_value]
+    end
+  end
+  
+# Data types
+  class NodeNumber < Treetop::Runtime::SyntaxNode
+    def value
+      text_value.to_f
+    end
+  end
+
+  class NodeMatrix < Treetop::Runtime::SyntaxNode
+    def value
+      Matrix[*matrix_rows.elements.collect {|row| row.value}]
+    end
+  end
+
+  class NodeMatrixRow < Treetop::Runtime::SyntaxNode
+    def value
+      matrix_cols.elements.collect {|col| col.value}
+    end
+  end
+
+  class NodeMatrixElement < Treetop::Runtime::SyntaxNode
+    def value
+      node_number.value
+    end
+  end
+
+# Common Infra
+    class BinaryOperator < Treetop::Runtime::SyntaxNode
+      def operation
+        text_value
+      end
+    end
+
+    class ParenExpression < Treetop::Runtime::SyntaxNode
+      def value
+        expression.value
+      end
+    end
+
+# Arithmetic operations and expressions (outside the matrix transformation block)
+  class OperationAssignment < Treetop::Runtime::SyntaxNode
+    def execute
+      $matrix_dsl_vars[lvalue.name] = rvalue.value
+    end
+  end
+
+  class MathFunctions
+    def self.method_missing(func, parameter, *args, &block)
+      if parameter.class == Matrix
+        parameter.send func 
+      elsif parameter.class == Fixnum || parameter.class == Float
+        Math.send func, parameter 
+      end
+    end
+  end
+
+  class OperationFunction < Treetop::Runtime::SyntaxNode
+    def value
+      MathFunctions.send function.text_value, expression.value
+    end
+  end
+
+  class OperationBinary < Treetop::Runtime::SyntaxNode
+    def value
+      to_exec = "#{expr1.value} #{binary_operator.operation} #{expr2.value}"    
+      eval(to_exec)
+    end
+  end
+
+  class OperationMultiply < Treetop::Runtime::SyntaxNode
+    def value
+      number.value * expression.value
+    end
+  end
+
+  class OperationNegate < Treetop::Runtime::SyntaxNode
+    def value
+      -1 * expression.value
+    end
+  end
+
+# Matrix transformation
+  class MatrixRowColIdentifier < Treetop::Runtime::SyntaxNode
+    # stuff like R1, C1 etc.
+    def row_or_col
+      text_value[0].chr
+    end
+    def index
+      index=text_value[1..-1].to_i - 1    # mathematical notation starts at index 1. we start at zero. -1 to adjust.      
+    end
+
+    def value(matrix_in_context)
+      matrix=matrix_in_context.value
+      
+      return matrix.row(index) if row_or_col == 'R'
+      return matrix.column(index)
+    end
+  end
+
+  class TransformationBlock < Treetop::Runtime::SyntaxNode
+    def execute
+      transformation_statements.elements.each {|stmt| stmt.execute(matrix_variable) }
+    end
+  end
+  
+  class MatrixTransform < Treetop::Runtime::SyntaxNode
+    def execute(matrix_in_context)
+      transform_result=transform_expression.value(matrix_in_context)
+      $matrix_dsl_vars[matrix_in_context.name]=apply_row_col_transformation(matrix_in_context.value, matrix_row_col_identifier, transform_result)
+    end
+  end
+  
+  class TransformOperationBinary < Treetop::Runtime::SyntaxNode
+    def value(matrix_in_context)
+      # the expressions will be of form: R1 + R2, expr1 would be R1 and expr2 R2. 
+      # Both of them have to be evaluated in the context of the matrix
+      # defined in the 'Transform M1' expression.
+      to_exec = "#{expr1.value(matrix_in_context)} #{binary_operator.operation} #{expr2.value(matrix_in_context)}"
+
+      eval(to_exec)
+    end
+  end
+  
+  class TransformOperationMultiply < Treetop::Runtime::SyntaxNode
+    def value(matrix_in_context)
+      transform_expression.value(matrix_in_context) * number.value
+    end
+  end
+
+  Treetop.load(File.join(File.dirname(__FILE__),'matrix_dsl_def.treetop'))
+end

data/lib/matrix_dsl_def.treetop

@@ -0,0 +1,118 @@
+grammar MatrixTransformations
+
+	rule document
+		(space statement space)*
+	end
+	
+	rule statement
+		assignment/transformation
+	end
+	
+ #----------------------------------------------------	
+	# === Matrix transformation grammar ===
+	# ie those inside the 'Transform' block: 
+	# Transform M1:
+	#	R1 <- R1 + R2
+	#   R3 <- 3R3
+	#   R4 <- R4/2
+	# etc.		
+	
+	rule transformation
+		"Transform " matrix_variable ":" space transformation_statements:(matrix_transformation_statement*) <MatrixDSL:: TransformationBlock>
+	end
+
+	rule matrix_transformation_statement
+		space matrix_row_col_identifier transform_operator transform_expression space <MatrixDSL::MatrixTransform>
+	end
+		
+	rule matrix_variable
+	   [A-Z] [a-zA-Z0-9_]* <MatrixDSL::MatrixIdentifier>
+	end
+	
+	rule transform_operator
+		space "<-" space
+	end
+	
+	rule transform_expression
+		expr1:simple_transform space binary_operator space expr2:transform_expression <MatrixDSL::TransformOperationBinary>
+		/
+		simple_transform
+	end
+	
+	rule simple_transform
+		(number transform_expression <MatrixDSL::TransformOperationMultiply>)/([-] transform_expression <MatrixDSL::TransformOperationNegate>)/(left_paren transform_expression right_paren)/matrix_row_col_identifier
+	end
+	
+	rule matrix_row_col_identifier
+    	# R1, R2, C1 etc.
+		("R"/"C") number <MatrixDSL::MatrixRowColIdentifier>
+	end
+	
+ #----------------------------------------------------
+	# === Normal expressions ===
+	# Simple arithmetical operations outside the matrix transformation.
+	# ie:
+	#   a = 123
+	#   b = (a * log a)/23.5
+	# etc.
+	#
+	
+	rule assignment
+		lvalue:identifier space "=" space rvalue:expression <MatrixDSL::OperationAssignment>
+	end
+	
+	rule expression
+		expr1:simple_expression space binary_operator space expr2:expression <MatrixDSL::OperationBinary>
+		/  
+		simple_expression
+	end
+	
+	rule simple_expression
+	  (number expression <MatrixDSL::OperationMultiply>)/(function " " expression <MatrixDSL::OperationFunction>)/([-] expression <MatrixDSL::OperationNegate>)/(left_paren expression right_paren <MatrixDSL::ParenExpression>)/matrix/number/identifier
+	end
+
+ #----------------------------------------------------
+	# === Common to all ===
+	
+	# -- For the matrix data-type:
+	rule matrix
+		"[" matrix_rows:(matrix_row*) "]" <MatrixDSL::NodeMatrix>
+	end
+	
+	rule matrix_row
+		space "[" space matrix_cols:(matrix_element*) space "]" space ","? <MatrixDSL::NodeMatrixRow>
+	end
+	
+	rule matrix_element
+		node_number:number space ","? space <MatrixDSL::NodeMatrixElement>
+	end
+	
+	#-- Rest of the stuff:
+	rule number
+	   [0-9]+ <MatrixDSL::NodeNumber>
+	end
+
+	rule function
+	 ("rank"/"transpose"/"inv"/"inverse"/"tr"/"trace"/"det"/"log")
+	end
+
+	rule binary_operator
+	 [/+/*-//] <MatrixDSL::BinaryOperator>
+	end
+	
+	rule space
+	 [ \t\n]*
+	end
+	
+	rule left_paren
+	  "(" space
+	end
+	
+	rule right_paren
+	  space ")"
+	end
+
+	rule identifier
+	  [a-zA-Z]+ [a-zA-Z0-9_]* <MatrixDSL::NodeIdentifier>
+	end	
+end

data/lib/matrix_dsl_helpers.rb

@@ -0,0 +1,59 @@
+require 'colorize'
+
+module MatrixDSL_Helpers
+
+  def node_info(node, truncate)
+    return node.statement.inspect unless truncate
+    return node.statement.inspect.split("\n")[0..6].join("\n")+"\n<trace truncated>" 
+  end
+  
+
+  # executes the script and prints error details if any.
+  # will clear existing variables.
+  def execute_matrix_dsl(script, parser, truncate_error_trace=true)
+    error_found=false
+
+    script.rstrip!
+    print "\n\nExecuting script:".yellow
+    puts script.blue
+    
+    $matrix_dsl_vars.clear     # Start with a fresh state.
+    
+    result=parser.parse(script)
+    
+    if result.nil?
+      puts "error_found executing script: \n"
+      show_error_script(script, parser.index)
+      error_found = true
+    else
+      
+      # parse the entire file and execute each statement in the syntax tree.
+      result.elements.each {|node|         
+        unless node.statement.respond_to? :execute
+          puts "Error: execute method unavailable in statement: #{node_info(node, truncate_error_trace)}".red
+          error_found = true
+        else 
+          node.statement.execute
+        end
+      } 
+      
+    end
+    
+    if error_found
+      puts "Execution failed".red
+      return false
+    end
+    
+    
+    puts "success".green
+    return !error_found
+  end
+    
+  # Displays given script, but highlights the character at supplied offset in red color.
+  # Uses the colorize gem.
+  def show_error_script(text, error_character_offset)
+    print text[0..error_character_offset-1] unless error_character_offset==0      
+    print text[error_character_offset].chr.red
+    print text[error_character_offset+1..-1]
+  end
+end

data/matrix_dsl_run.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'ruby-debug'
+require 'colorize'
+
+require 'lib/matrix_dsl.rb'
+require 'lib/matrix_dsl_helpers.rb'
+include MatrixDSL
+include MatrixDSL_Helpers
+
+script=STDIN.read
+parser = MatrixTransformationsParser.new
+
+if execute_matrix_dsl(script, parser)
+  puts $matrix_dsl_vars.inspect
+end    

data/tests/basic_test.rb

@@ -0,0 +1,84 @@
+require 'rubygems'
+$:.unshift File.join(File.dirname(__FILE__),'..','lib')
+
+require 'matrix_dsl.rb'
+require 'matrix_dsl_helpers.rb'
+include MatrixDSL_Helpers
+
+require 'colorize'
+require 'test/unit'
+require 'ruby-debug'
+include MatrixDSL
+
+class BasicTest < Test::Unit::TestCase
+  def setup
+    @p = MatrixTransformationsParser.new
+  end
+  
+  def test_create_variables
+    script = """
+    a = 10
+    M1 = [ [1 2 3][4 5 6]]
+    M2 = [ 
+          [9 8,    7]
+          [10, 11 12]
+        ]
+    "
+       
+    expected = {"a"=>10.0, "M1"=>Matrix[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], "M2"=>Matrix[[9.0, 8.0, 7.0], [10.0, 11.0, 12.0]]}
+
+    MatrixDSL_Helpers::execute_matrix_dsl(script, @p)
+
+    assert_equal expected, $matrix_dsl_vars, "are variables and matrices initialized properly"
+  end
+
+  def test_arithmetic_expressions
+    script = """
+    a = 10 * (2+3)
+    b = 12a/4
+    "
+    
+    expected = { "a" => 50, "b" => 150}
+    
+    MatrixDSL_Helpers::execute_matrix_dsl(script, @p)
+        
+    assert_equal expected, $matrix_dsl_vars, "test simple arithmetic expressions"
+  end
+  
+  def test_functions
+    script = """
+    a = log 15
+    M1 = [[1 2 3][4 5 6][2 1 3]]
+    d  = det M1
+    r = rank M1
+    "
+    
+    expected = { "a" => 2.70805020110221, "d" => -9, "r" => 3, "M1" => Matrix[[1.0,2.0,3.0],[4.0,5.0,6.0],[2.0,1.0,3.0]]}
+    
+    MatrixDSL_Helpers::execute_matrix_dsl(script, @p)
+        
+    assert_equal expected, $matrix_dsl_vars, "test math and matrix functions"
+  end
+  
+  def test_matrix_transform
+    script = """
+    M1 = [[1 2 3][3 2 1][5 1 2]]
+    det1 = det M1
+    det2 = det M1
+
+    Transform M1: 
+      R1 <- R1 + R2
+      R3 <- R3 - R2
+      R2 <- 2R2
+    "
+    
+    expected = {"M1"=>Matrix[[4.0, 4.0, 4.0], [6.0, 4.0, 2.0], [2.0, -1.0, 1.0]], "det1"=>-20.0, "det2"=>-20.0}
+
+    MatrixDSL_Helpers::execute_matrix_dsl(script, @p)
+        
+    assert_equal expected, $matrix_dsl_vars, "test matrix transformations"
+  end
+
+end
+
+

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: matrix_dsl
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jasim A Basheer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-26 00:00:00 +05:30
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: treetop
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: colorize
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: A simple DSL for expressing and evaluating basic Matrix transformations and arithmetic operations
+email: jasim.ab@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- README.markdown
+- example.matrix_dsl
+- lib/matrix_dsl.rb
+- lib/matrix_dsl_def.treetop
+- lib/matrix_dsl_helpers.rb
+- matrix_dsl_run.rb
+- tests/basic_test.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/jasim/matrix_dsl
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A simple DSL for expressing and evaluating basic Matrix transformations and arithmetic operations
+test_files: []
+