rVM 0.0.12 → 0.0.13

data/lib/rvm.rb

@@ -22,8 +22,8 @@ module RVM
   class Safety
     
     attr_reader :timeout
-    def initialize
-      @timeout = nil
+    def initialize options = {}
+      @timeout = options[:timeout]
     end
     
     # Sets the timeout for the executin, in seconds (you may use 0.5 and such)

data/lib/rvm/acts_as_rvm_type.rb

@@ -3,6 +3,8 @@
 # to the rVM interpreter without going through the hassle of defining each 
 # function on it's own and publisheing every varialbe that is watned.
 #
+# The function to call is ActsAsRVMTypeMethods::acts_as_rvm_type.
+#
 # == Example
 #   class Test
 #     # Add the readers and writers for
@@ -13,7 +15,6 @@
 #     register_function :to_s
 #   end
 
-
 module RVM::ActsAsRVMType
   
   # Called when included, loads the class methods and the instance methods needed.
@@ -61,25 +62,37 @@ module RVM::ActsAsRVMType
           @variables
         end
       end
+      
+      # Return the variables hash for the firs call.
       @variables
     end
     
     # This function will set up the variables for a rVM and replaces
     # the current function with a shorter and faster one.
     def functions
+      # Copy the original functions hash so that changes to the instance
+      # wont't carry over to to other instances.
       @functions = self.class.object_functions.dup
+      
+      # Redefine the function method to speed up further accesses.
       instance_eval do
         def functions
           @functions
         end
       end
-      @functions ||= @@functions.dup
+      
+      # Return the functions hash for the first call.
+      @functions
     end
-    
   end
   
+  
+  # This module hods the instance methods for classes that are supposed to
+  # act as  a rVM type.
+  #
+  # It includes +register_variable+ and +register_function+ to help setting up
+  # the class quickly.
   module ActsAsRVMTypeInstanceMethods
-    
     # This registers a variable for the rVM interface, it allows the scripts
     # to read and write them. If +writable+ is set this will be a read only
     # variable. It alls an be published to rVM under a different name,
@@ -92,7 +105,7 @@ module RVM::ActsAsRVMType
     # to read and write them. If +writable+ is set this will be a read only
     # variable. It alls an be published to rVM under a different name,
     # by passing +published_as+.    
-    def register_function name, published_as = "#{name}"
+    def register_function name, published_as = name
       @functions[published_as.to_s] = Class.new(RVM::Functions::Function) do @name = name; end
       class << @functions[published_as.to_s]
         def execute params, env
@@ -105,9 +118,14 @@ module RVM::ActsAsRVMType
       end
     end
     
+    # Returns the hash of variables for to be used only internally by the
+    # ActsAsRVMTypeSingeltonMethods#variables function to set up the details.
     def object_variables
       @variables
     end
+    
+    # Returns the hash of variables for to be used only internally by the
+    # ActsAsRVMTypeSingeltonMethods#variables function to set up the details.
     def object_functions
       @functions
     end 

data/lib/rvm/classes.rb

@@ -47,18 +47,29 @@ module RVM
     #   end
     class Class
       
+      # We make classes a Plugin and set the plugin host to Classes s it can
+      # handle the details for it.
       extend RVM::Plugin
       plugin_host Classes
       
-      
+      # Basic functions hash for classes so every class at least can respond
+      # to a +functions+ call.
       def functions
         @functions ||= {}
       end
       
+      # Basic variables hash for classes so every class at least can respond
+      # to a +variables+ call.
       def variables
-        @variables ||= {:self => self, }
+        @variables ||= {}
       end
       
+      
+      # Every class is by default treated as beeing true when not defined
+      # otherwise.
+      # This makes sure that calling boolean functions on classes will always
+      # return a usefull result.
+      # So it can be redefinde to say, have 0 act as false if this is wanted.
       def is_true?
         true
       end
@@ -77,17 +88,20 @@ module RVM
         true
       end
 
-      alias :method_missing_old_class :method_missing         
-      
+      # Redefinding the method to allow using self defined functions
+      # within classes - while this is discuraged it still is possible.      
       def method_missing(m, *args, &block)
+        # Check if the functions PluginHost knwos about the called function
         if (RVM::Functions::has? m)
-          RVM::Functions[m].execute args, @env, &block
+          # Calls the function with given args and enviroment that is,
+          # hopefully defiend in the calling class.
+          RVM::Functions[m].execute args, @env
         else
+          # If the function is not known we call the usual method missing 
+          # method.
           super(m, *args, &block)
-          #method_missing_old_class m, *args, &block
         end
       end
-      
     end
   end
 end

data/lib/rvm/functions.rb

@@ -1,25 +1,39 @@
 require File.dirname(__FILE__) + '/plugin'
 require File.dirname(__FILE__) + '/interpreter'
 module RVM
-  
+  # This module holds all the functions laded for the rVM to to keep them
+  # organized and handle which are accassabel and which not.
   module Functions
     extend RVM::PluginHost
+    
+    # Basic Parent for every function defined, it registers it to the
+    # PluginHost and sets up some basic functionality.
+    # Just parent a class to this and define +execute+ as a class function
+    # and it can be handled.
     class Function
+      
+      # Registers this as plugin and sets up the PluginHost
       extend RVM::Plugin
       plugin_host Functions
+      
       class << self
-        
+        # By default every function should have a universal return value,
+        # this make sure it is not refused if it isn't defined correctly.
         def data_type
           :any
         end
 
-        alias :method_missing_old_functions :method_missing         
-        
+        # We want to allow functions to call other functions without going
+        # through explic calls.
+        # Again it isn't exactly encuraged but possible if needed to.        
         def method_missing(m, *args, &block)
+          # First we check if a function with the name given is defined vor rVM
           if (RVM::Functions::has? m)
+            # if so we call it with the given arguments
             RVM::Functions[m].execute args, @env 
           else
-            method_missing_old_functions m, *args, &block
+            # If not we let ruby do it's magic.
+            super(m, *args, &block)
           end
         end
         
@@ -29,25 +43,51 @@ module RVM
           true
         end
         
+        
+        # Call is used to call the function it handles translating the passed
+        # parameters to the correct types or throw a exception if RVM::strict
+        # is set.
+        # This is what you want if you call a function to ensure all parameters
+        # are passed correctly.
         def call params, env, pos = nil
           i = 0
+          # We want to make sure that if we don't have signatures from the
+          # function we have a default signature of any to prevent automatic
+          # type castng in that case
           sig = :any 
           params.map! do |p| 
+            # We try to get the next signature if we don't have any further we
+            # take the last one used so [:number, :number, :number] behaves the
+            # same as just [:number] as it will be repeated
             sig = signature[i] || sig
+            # Now we check if the expected type is not ':any' nor the current 
+            # argument has the right type.
             if sig != :any and p.class != RVM::Classes[sig]
-              raise "TYPE MISMATCH! expected #{sig} got #{p.class}(#{pos}) at " if RVM::strict
+              # Okay if we have RVM::strict set we don't allow auto type
+              # casting so we throw a Exception
+              raise "TYPE MISMATCH! expected #{sig} got #{p.class}(#{pos.join(':')}) at " if RVM::strict
+              # Otherwise we try to typecast the parameter.
               p = RVM::Classes[sig].new(p)
             end
+            # Go to the next parameter in the list
             i+=1
+            # and make sure the former one is replaced (value of the block)
             p 
           end if not signature.empty?
+          # Now we execute the function code and cache the esult
           r = execute(params, env)
+          # print a debug message if needed
           RVM::debug "#{self.inspect}: #{signature.inspect} = '#{r}'" if $DEBUG
           r
         end
         
+        
+        # This executes the function code and returns the result.
+        #
+        # It must be implemented for every function used otherwise it will
+        # end up without doing anything.
         def execute params, env
-          
+          RVM::Classes[:error].new(1,"Function code for #{self} not implemented.")
         end
       end
     end

data/lib/rvm/functions/rails.rb

@@ -0,0 +1,3 @@
+Dir[File.dirname(__FILE__) + '/rails/*.rb'].each do |c|
+  require c
+end

data/lib/rvm/functions/rails/print.rb

@@ -0,0 +1,18 @@
+module RVM
+  module Functions
+    class Print < RVM::Functions::Function
+      class << self
+        def execute params, env
+          params.each do |p|
+            env.read_var_val(:render) << p.to_s
+          end
+        end
+        
+        def signature
+          [:any] 
+        end
+      end
+      register_for :print
+    end
+  end
+end

data/lib/rvm/interpreter.rb

@@ -1,22 +1,40 @@
 require File.dirname(__FILE__) + '/functions'
 require File.dirname(__FILE__) + '/classes'
 module RVM
-  # This Module hold all the VM Classes, so it is quite important to read
-  # and understand if you feel like making a own compiler.
+  # This Module hold all the VM classes that are used to execute and evaluate
+  # code for the VM, so it is quite important to read and understand if you 
+  # feel like making a own compiler.
   #
-  # The basic idea is to translate your own code into a tree of objects
-  # from this.
+  # For someone not interested in going as deep into building a own compiler
+  # it still is a good start for understanding how rVM works, yet it is not
+  # mandatory to read.
+  #
+  # The basic idea of this objects is that the compiler translates the source
+  # code into a tree of RVM::Interpreter objects to build the behavior that is
+  # expected. Once that is done the code can be executed by calling #execute
+  # for the root of the object tree.
   #
   module Interpreter
     
     
+    # Helper class to be parented to other Interpreter calsses for checks and
+    # including general behavior.
     class Element
+      # The position in the soruce code, added to help debugging scripts with
+      # problems.
       attr_accessor :pos
+      
+      # Initializes the interpreter element with a position.
       def initialize pos
         @pos = pos
       end
     end
+    
     # This is a helper fuctio to quickly generate a empty enviorment.
+    # A hash can be passed to store variables.
+    #
+    # :locals can be a hash holding local variables
+    # :functions can be a hash to hold functions defined in the the scope
     def Interpreter.env aenv = {}
       RVM::debug "Interpreter.env" if $DEBUG
       Enviroment.new aenv
@@ -29,16 +47,28 @@ module RVM
       RVM::Interpreter::Constant.new(RVM::Classes[type].new(value), pos)
     end
     
-    # This class is used to store the variable content to allow chross refferencing
-    # and passing variables upwards through different scopes.
+    # This class is used to store the variable content to allow chross 
+    # refferencing and passing variables upwards through different scopes.
     class VariableStorage
-      attr_accessor :val
-      def initialize val = nil, writable = true, &block
+      
+      # Lets the script read the value of the variable.
+      attr_reader :val
+      
+      # The storage is initialized with two optional parameters:
+      #
+      # +val+:: which is the value to be stores.
+      # +writable+:: which when set to false prevents the variable to be
+      #              written, which might be helpfull when trying to publish
+      #              some data to a script that is not supposed to be changed.
+      def initialize val = nil, writable = true
         @writable = writable
         @val = val
-        instance_eval(&block) if block
       end
       
+      # Used to write to the variable, if +writable+ was set to false this
+      # will have no effect.
+      # 
+      # It returns the new value set or, if +writable+ was false the old value.
       def val=v
         @val = v if @writable
         @val
@@ -47,16 +77,37 @@ module RVM
     
     # The callback storang is used to help publishing variables from a ruby
     # class to the rVM, it will get and set the variables during runtime.
+    #
+    # It will link getter and setter methods and not the instance variable
+    # itself, which means also computed attributes can be handled by this.
+    #
+    # This class is made if it is nessessary that a script always has access
+    # to constantly chaning data within a object and not only deal with static
+    # values set once.
     class VariableStorageCallback < VariableStorage
+      # The construtor takes 3 parameters to specifie the object it shold
+      # be linked with, the attribute to handle and +writable+ that will define
+      # if the VariableStorage can be written too by the script.
+      #
+      # var is expected to by a Symbol equal the the function, the getter will
+      # call obj.var and the setter will call obj.var=.
+      #
       def initialize obj, var, writable = true
         super(nil, writable)
         @obj = obj
         @get = var.to_sym
         @set = "#{var}=".to_sym
       end
+      
+      # This methods sets the variable passed to the object by sending it to
+      # the setter method.
       def val= v
         @obj.send(@set,v) if @writable
+        @obj.send(@get)
       end
+      
+      # The getter will call the getter of the object to handle to get the
+      # current value.
       def val
         @obj.send(@get)
       end
@@ -71,10 +122,17 @@ module RVM
     # for example function calls.
     class Enviroment
       # This creates a new enviroment enviroment, it generates a new env
-      # default variables are set if not defined in *data*.
+      # default variables are set if not defined in +data+.
       #
-      # If *oldenv* is provided it will also fall back to see if not
+      # If +oldenv+ is provided it will also fall back to see if not
       # existing variables 
+      #
+      # +init_data+ is a hash that can be passed the following values:
+      # :locals:: A hash with local variables mapped name => value
+      # :functions:: A hash with functions for the scope.
+      # :evaldeepth:: A fixnum that indicates how deep the evaluation  is.
+      # :params:: A array that holds local parameters for example for functions
+      #           or blocks.
       def initialize init_data = {}, oldenv=nil
         
         @data = {
@@ -84,22 +142,33 @@ module RVM
           :params => []
         }.merge(init_data)
         
-        # Make sure that all locals that are passed, are actually in a variable storage.
+        
+        # Make sure that all locals that are passed, are actually in a variable
+        # storage.
         if init_data[:locals]
+          # For easy access we get us a link to the locals
           locals = @data[:locals]
+          # Now we itterate through them
           init_data[:locals].each do |k,v|
+            #For every variable that isn't already in a storage
             if not v.is_a?(VariableStorage)
+              # We put it in a storage to assure the enviroment is propper.
               locals[k] = VariableStorage.new(v)
             end
           end
         end
         
+        # We store the priviouse enviroment to look upwards through the scopes
+        # for priviouse defined variables, if no old enviroment was given we
+        # set the priviose scope to an empty hash.
         @prev = oldenv || {}
         RVM::debug "data: #{data}\noldenv:#{oldenv}" if $DEBUG
-        RVM::debug "Creating new enviroment with: #{@data.inspect} as child of #{@prev}" if $DEBUG
+        RVM::debug "Creating new enviroment with: #{@data.inspect} as child" +
+                   " of #{@prev}" if $DEBUG
       end
       
-      #allows raw access to the data, be carefull!
+      # Allows raw access to the data, it should not be used unless
+      # somoene knows pretty exactly what they are doing.
       def data
         @data
       end
@@ -131,47 +200,67 @@ module RVM
       #
       # If the variable exists in a 'higher' enviroment the value is changed.
       # 
-      # If not it is newly created in the current enviroment and thus not visible
-      # in upper enviroments.
-      def []= k, v
-        #TODO: add capability to have the privious env variables changed
-        RVM::debug "Setting variable #{k} to #{v}" if $DEBUG
-        if (r = self[k])
-          r.val = v
+      # If not it is newly created in the current enviroment and thus not
+      # visible in upper enviroments.
+      def []= name, value
+        RVM::debug "Setting variable #{name} to #{value}" if $DEBUG
+        # First we try to get the variable storage of the variable requested.
+        # This will work if it was defined in this or a priviouse scope.
+        if (res = self[name])
+          # If we found the storage we'll change it's value and not define it
+          # again.
+          res.val = value
         else
-          @data[:locals][k] = VariableStorage.new(v)
+          # If we didn't found a Variable storage, the variable wasn't defined
+          # before so we make a new VariableStorage and save the variable in
+          # it.
+          @data[:locals][name] = VariableStorage.new(value)
         end
-        v
+        value
       end
+      
       # Defines a varialbe in the current scope, priviose variables are not
-      # changed
-      def declare k, v
-        @data[:locals][k] = VariableStorage.new(v)
+      # changed.
+      # This is needed for local varialbe declarations that overwrite priviouse
+      # globals.
+      def declare name, value
+        @data[:locals][name] = VariableStorage.new(value)
       end
       
-      # Returns a function for the current enviroment.
+      # Returns a function for the enviroment. If the current enviroment does
+      # not hold a function with the requested name it checks through the 
+      # entire tree if a function can be found in the outer scopes.
+      # 
       # The result is to be execpted to be of the +RVM::Classes::Block+ class.
-      def function k
-        r = @data[:functions][k]
-        if not r and @prev.is_a? Enviroment
-          r = @prev.function(k)
-        end
-        RVM::debug "Getting functon #{k} (#{r})" if $DEBUG
-        r
-      end
-      
-      # This defines a function within the enviroment and lets you call it later on.
+      def function name
+        # Try to get the function in the local defintions.
+        fun = @data[:functions][name]
+        # if that fails and we have a previous enviroment check that
+        fun = @prev.function(name) if fun.nil? and @prev.is_a? Enviroment
+        RVM::debug "Getting functon #{name} (#{fun})" if $DEBUG
+        # return what was found
+        fun
+      end
+      
+      # This defines a function within the enviroment and lets you call it later
+      # on.
       # 
-      # It also checks if the given block is truely a +RVM::Classes::Block+ object.       
-      def def_function k, b
-        raise(ArgumentError, "Function definitions must be of block class.") if not b.is_a?(RVM::Classes::Block)
-        @data[:functions][k] = b
-        RVM::debug "Setting functon #{k} (#{b})" if $DEBUG
-        nil
+      # It expects the body to be a RVM::Classes::Block so it can be executed.
+      # The return value is the given block
+      def def_function name, body
+        if not body.is_a?(RVM::Classes::Block)
+          raise(ArgumentError, "Function definitions must be of block class.") 
+        end
+        @data[:functions][name] = body
+        RVM::debug "Setting functon #{name} (#{body})" if $DEBUG
+        body
       end
       
-      # This functin is closely related to +[]+ with the difference that it returns the value
-      # And not the VariableData object.
+      # This functin is closely related to +[]+ with the difference that it
+      # returns the value and not the VariableStorage object.
+      # It is equivalent to [].val just that it also deals with nil ojects and
+      # and returns a RVM::Classes::Error if the requested variable wasn't
+      # found.
       def read_var_val name
         
         r = nil
@@ -186,19 +275,38 @@ module RVM
     end
     
     
-    # Skipps into object context (anther way beside using send)
+    # Jumps into object context (anther way beside using send).
     #
-    # the special variable :self (attention, not to be mixed wiht 'self')
+    # The special variable :self (attention, not to be mixed wiht 'self')
     # is set to the object in which context we are!
     #
-    # The class is stred in :class
+    # This is one of the few RVM::Interpreter calsses that is likely to be used
+    # outside a compiler as it will allow to execute a set of code within the
+    # scope of a specific object:
+    #
+    # =Example
+    #   RVM::Interpreter::ObjectContext.new(my_object, my_code).execute(env)
+    #
+    # This will execute my_code in a way pretty much equal to instance_eval in
+    # ruby would do.
     class ObjectContext < Element
+      
+      # The constructor takes 3 arguments, the first beeing the object of which
+      # the scope is taken, the second is the code to be executed in the objects
+      # scope and the third is the position, to be set by the compiler.
+      #
+      # The passed object is executed once when the code is ran so it can be
+      # passed something that evaluates like a variable, or constant.
       def initialize object, code, pos = nil
         super(pos)
         @object = object
         @code = code
       end
       
+      # Execute for this Interpreter element by creating a new enviroment,
+      # setting it's variables and functions to those definded by the object's
+      # +functions+ and +variables+ methods. It also sets the :self variable in
+      # the new enviroment to the object.
       def execute env
         #The new 
         obj = @object.execute(env)
@@ -209,9 +317,14 @@ module RVM
     end
     
     
-    #This sets a funciton on a Class (to be included in its objects)
+    # This sets a funciton on a Class (to be included in its objects)
     #
-    #To define class functions use ObjectContext and define the function normaly, nifty isn't it?
+    # To define class functions use ObjectContext and define the function
+    # normaly, nifty isn't it?
+    #
+    # This object may be subject to removal or change, don't use it yet.    
+    #---
+    # TODO: Work this over. 
     class SetClassFunction < Element
       def initialize obj, name, function, pos = nil
         super(pos)
@@ -247,8 +360,10 @@ module RVM
       end
     end
     
-    # This is a function definition used to write in the function libary
-    #
+    
+    # The FunctionDefinition can be used to define functions in the current
+    # scope, it can either be methods belonging to a object when called within
+    # object scope or good old functions.
     class FunctionDefinition < Element
       
       # Initializes a new function definition
@@ -263,6 +378,9 @@ module RVM
       # override:: when true (default) earlyer definitions are 
       #            replaced when it is called a second time.
       #            When false a exception is thrown
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose. 
       def initialize name, body, override = true, pos = nil
         super(pos)
         @name = name
@@ -270,6 +388,12 @@ module RVM
         @override = override
       end
       
+      # When executed the FunctionDefinition first checks if a function with the
+      # same name is already defined. If it is and +override+ wasn't set to ture
+      # it trows a Exception. Otherwise it defines the function, deleting the
+      # old definition when still repsent.
+      #
+      # It returns the body of the newly defined function.
       def execute env
         if (not @override) and env.function(@name)
           raise "Function #{@name} already defined at #{@pos}!"
@@ -282,19 +406,31 @@ module RVM
     
     # This is a loop. It is executed over and over again as long as
     # the passed condition evaluates to a value that matches is_true?.
+    #
+    #---
+    #TODO: Add BreakException to stop execution of loops.
+    #TODO: Add NextExceeption to skip rest of a evaluation on loop code.
     class Loop < Element
       # Initializes a new loop.
       #
       # condition:: is executed before each run of the loop. If it evaluates
       #             to true the loop is executed another time otherwise the
       #             exection ends.
+      #
       # body::      For each itteration of the loop this is executed once.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose. 
       def initialize(condition, body, pos = nil)
         super(pos)
         @condition = condition
         @body = body
       end
       
+      # The loop will execute as long as the code passed as condition evaluates
+      # to is_true?.
+      # Once the loop stops executing the return value is the result of the last
+      # body execution.
       def execute env
         r = nil
         while @condition.execute(env).is_true?
@@ -315,18 +451,25 @@ module RVM
         @value = value
       end
       
+      # A constat returns the data type of the value that is stored in it.
       def data_type
         @value.data_type
       end
       
+      # Comparing a constant with something has two ways to go, if the object
+      # it is compared to is a Constant the two values are compared. If not the
+      # Constant compares the value with the passed object.
       def == v
         if v.is_a? Constant
           @value == v.value
         else
+          @value == v
           false
         end
       end
       
+      # When executed the constant returns the value stored in it, without
+      # evaluating it.
       def execute env
         RVM::debug "Executing Constant at #{@pos}: #{@value}" if $DEBUG
         @value
@@ -358,10 +501,15 @@ module RVM
       # Creates a new condition with the given parameters. The false_case can
       # be ommitted.
       #
-      #  * value - is executed, and depandant of the result either true_case or
-      #    false casae s executed.
-      #  * true_case - is only executed if value evalutes to true (is_true?)
-      #  * false_case - is only executed if value evalutes to false (!is_true?)
+      # value:: is executed, and depandant of the result either true_case or
+      #         false casae s executed.
+      #
+      # true_case:: is only executed if value evalutes to true (is_true?)
+      #
+      # false_case:: is only executed if value evalutes to false (!is_true?)
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.
       def initialize value, true_case, false_case = nil, pos = nil
         super(pos)
         @value = value
@@ -369,6 +517,11 @@ module RVM
         @false_case = false_case
       end
       
+      
+      # The data type of a condition is tried to evaluate by checking if the
+      # type is the same for both conditions, if so the common type is returned,
+      # if not :any is returend as it can not be determined what type the 
+      # Condition will have.
       def data_type
         if @true_case.data_type == @false_case.data_type
           @false_case.data_type
@@ -377,6 +530,12 @@ module RVM
         end
       end
       
+      # When executed the condition first executes the condition, if it
+      # evaluates to a value that .is_true? the true case is executed if not,
+      # and a false case is given it will be executed.
+      #
+      # The return value is the value of the executed condition, so either the
+      # ture_case or the false_case.
       def execute env
         v =  @value.execute(env)
         if v and v.is_true?
@@ -389,22 +548,44 @@ module RVM
       end
     end
     
-    # A variable assignment that sets a local variable, a declaration
-    # is not required before the assignment can be done.
+    
+    # A variable assignment that sets a local variable. A declaration
+    # is not required before the assignment can be done, yet it can be used to
+    # force a laready declaed variale into the local scope.
     #
-    # Both the *name* and the *value* are evaluated before the assignment
+    # Both the +name+ and the +value+ are evaluated before the assignment
     # is done.
     class Assignment < Element
+      
+      # A Assignment is initialized wiht 2 to 3 parameters.
+      #
+      # name:: The name of the variable to store, it will be executed, usually
+      #        this will be a Constant, unless dynamic naming is needed by the
+      #        implemented language.
+      #
+      # value:: The value that will be assigned to the variable, for a = 1 + 1
+      #         '1+1' would be the value to assign, so as this already suggests
+      #         the value will be executed.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.   
       def initialize name, value, pos = nil
         super(pos)
         @name = name
         @value = value
       end
       
+      # The data type of a Assignment is the data type of it's value.
       def data_type
         @value.data_type
       end
       
+      # When executed the assignment first evaluates the name of the assignment
+      # then the value and stores the result of the executed value in the
+      # enviroment under the name of the executed name.
+      #
+      # The return value of the execution is the value that is assigned to the
+      # variable.
       def execute env
         RVM::debug "Executing Assignment at #{@pos}..." if $DEBUG
         env[@name.execute(env).to_s] = @value.execute env
@@ -414,19 +595,45 @@ module RVM
     # A variable declarion that sets a local variable, it will redelcare 
     # the variable if declared in a privouse scope.
     #
-    # Both the *name* and the *value* are evaluated before the assignment
+    # It is very closely related to the Assignment as it acts exactly alike if
+    # the variable is not yet existing in the Enviroment.
+    #
+    # Both the +name+ and the #value# are evaluated before the assignment
     # is done.
     class Declaration < Element
+      # A Declaration is initialized wiht 2 to 3 parameters.
+      #
+      # name:: The name of the variable to store, it will be executed, usually
+      #        this will be a Constant, unless dynamic naming is needed by the
+      #        implemented language.
+      #
+      # value:: The value that will be assigned to the variable, for a = 1 + 1
+      #         '1+1' would be the value to assign, so as this already suggests
+      #         the value will be executed.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.
       def initialize name, value, pos = nil
         super(pos)
         @name = name
         @value = value
       end
       
+      # The data type of a Assignment is the data type of it's value.
       def data_type
         @value.data_type
       end
       
+      # When executed the assignment first evaluates the name of the assignment
+      # then the value and stores the result of the executed value in the
+      # enviroment under the name of the executed name.
+      #
+      # If the variable was priviosely in a enviroment that lays above the
+      # current one in the hearachy the old value will not be altered in any
+      # way but a new variable declared.
+      #
+      # The return value of the execution is the value that is assigned to the
+      # variable.     
       def execute env
         RVM::debug "Executing Assignment at #{@pos}..." if $DEBUG
         env.declare(@name.execute(env).to_s,@value.execute(env)).val
@@ -435,8 +642,15 @@ module RVM
     
     # Reads the value of a variable in the enviroment.
     #
-    # The *name* is evaluated before the variable is retrieved.  
+    # The +name+ is evaluated before the variable is retrieved.  
     class Variable < Element
+      # A Variable is initialized wiht 1 to 2 parameters.
+      #
+      # name:: The name of the variable to get, it will be executed as long as
+      #        it is no Sybol in which case it is treated as a special variable.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.
       def initialize name, pos = nil
         super(pos)
         @name = name
@@ -449,6 +663,10 @@ module RVM
         @type
       end
       
+      # When the name is a symbol, the name isn't executed and treated as a
+      # special variable.
+      # Otherwise the name is executed and converted into a string to be passed
+      # to the enviroment so it can go and collect the value.
       def execute env
         RVM::debug "Executing Variable at #{@pos}..." if $DEBUG
         n = @name
@@ -464,6 +682,14 @@ module RVM
     # This evauates to the parameter passed to the function call.
     # The number of it is evaluated and typecasted to an interger.
     class Parameter < Element
+      
+      # A Parameter is initialized wiht 1 to 2 parameters.
+      #
+      # num:: The number if the parameter to get, 0 is the first parameter
+      #       passed, 1 the second and so on.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.
       def initialize num, pos = nil
         super(pos)
         @num = num
@@ -476,6 +702,11 @@ module RVM
         @type
       end
       
+      # When executed the Parameter evaluates the number, of the parameter and
+      # then queries the enviroment to get the function parameter requested.
+      #
+      # After the first execution the parameter remembers the type of the value
+      # it returns.
       def execute env
         RVM::debug "Executing Parameter at #{@pos}..." if $DEBUG
         r = env.param(@num.execute(env).to_i)
@@ -489,10 +720,23 @@ module RVM
     # The type of the squence is equal to the last element of the sequence.
     class Sequence < Array
       attr_accessor :pos
+      
+      # The Sequence is initialized wiht 1 to 2 parameters.
+      #
+      # src:: The source is an array that holds the inital list of commands that
+      #       are supposed to be executed.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.     
       def initialize src=[], pos = nil
         super(src)
         @pos = pos
       end
+      
+      # When exeuted a sequence starts to execute every element in it starting
+      # with the first element in the array.
+      #
+      # The result is the last element of the array executed.
       def execute env
         RVM::debug "Executing Sequence... #{inspect}" if $DEBUG
         r = nil
@@ -502,10 +746,14 @@ module RVM
         r
       end
       
+      # When adding something to the Sequence a new Sequence will be created
+      # with the result of the joined arrays.
       def + v
         Sequence.new(super)
       end
       
+      # The data type of the list is :any as it is unknown where the the
+      # sequence exits.
       def data_type
         :any
       end
@@ -518,6 +766,13 @@ module RVM
     class ReturnException < Exception
       attr_reader :val
       attr_reader :pos
+      
+      # The ReturnException is initialized wiht 1 to 2 parameters.
+      #
+      # val:: The value that will be returned, aka the part after 'return'.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.     
       def initialize val, pos = nil
         super()
         @val = val
@@ -529,15 +784,26 @@ module RVM
     # +ReturnException+ which can be caught to have the function
     # or block return what they wish.
     class Return  < Element
+      
+      # The Return is initialized wiht 1 to 2 parameters.
+      #
+      # val:: The value that will be returned, aka the part after 'return'.
+      #
+      # pos:: The position within the source code of the definition - for 
+      #       deugging purpose.
       def initialize val, pos = nil
         super(pos)
         @val = val
       end
       
+      # The data type of a return statement is any, as it does not return
+      # anything at all, after all it jumps out of a block.
       def data_type
         :any
       end
       
+      # When executed the Return executed the value and then raises a 
+      # ReturnException.
       def execute env
         raise ReturnException.new(@val.execute(env))
       end
@@ -552,7 +818,7 @@ module RVM
     class FunctionCall < Element
       attr_reader :arguments
       attr_reader :function
-      # The constructor. *function* can either be a block object or a function
+      # The constructor. +function+ can either be a block object or a function
       # class.
       #
       # Arguments is a list of the arguments to the function.
@@ -562,10 +828,14 @@ module RVM
         @arguments = arguments
       end
       
+      # The data type of the FunctionCall is the return value of the function
+      # that it calls.
       def data_type
         @function.data_type
       end
       
+      # Comparing two function calls will result in a match when the passed
+      # arguments are the same and the function to call the same
       def == v
         if v.is_a? FunctionCall
          (@arguments == v.arguments) && (@function == v.function)
@@ -574,26 +844,52 @@ module RVM
         end
       end
       
+      # When executed the FunctionCall has four possible behaviours.
+      #
+      # 1) If the function is a block, so an anonymous function, the arguments
+      #    will be executed and then the block is called.
+      #
+      # 2) The function is a locally defined function and then the arguments are
+      #    executed and passed to the locally defined function.
+      #
+      # 3) The function is a RVM::Functions::Function and execargs returns true,
+      #    the arguments are executed and the function called.
+      #
+      # 4) The function is a RVM::Functions::Function and execargs returns
+      #    false, the arguments are passed along unexecuted and the function has
+      #    to take care of that itself. This is important for logical functions
+      #    as and and or which execute only some of the arguments
       def execute env
         RVM::debug "Executing FunctionCall..." if $DEBUG
         args = @arguments.dup
+        # The function is a anonymous function
         if @function.is_a? RVM::Classes[:block]
+          # The arguments are executed.
           args.map! do |arg|
             arg.execute env
           end
+          # Call the function
           @function.call(args, env,  @pos)
+          # The function is a selfdefined function (or object function)
         elsif fun = env.function(@function)
+          # The arguments are executed.
           args.map! do |arg|
             arg.execute env
           end
+          # Call the function
           fun.call(args, env, @pos)
+          # If nothing of the above the function must be a global function.
         else
+          # Get the function from he globals
           fun = RVM::Functions[@function]
+          # Test if the arguments should be executed
           if fun.execargs
+            # The arges get executed
             args.map! do |arg|
               arg.execute env
             end
           end
+          # Call the function
           fun.call(args, env,  @pos)
         end
       end

data/lib/rvm/languages/ecma.rb

@@ -53,7 +53,7 @@ module_eval(<<'...end ecma.y/module_eval...', 'ecma.y', 219)
           end
         end
         @q.push [:STRING, [m, [line, s.pos - pos]]]
-      elsif s.scan(/((\d+(\.\d+)?)|(\.\d+))(e[+-]?\d+)?/i)
+      elsif s.scan(/(\.\d+|(0(\.\d+)?)|([1-9](\d*(\.\d+)?)))(e[+-]?\d+)?/i)
         @q.push [:NUMBER, [s.matched, [line, s.pos - pos]]]
       elsif s.scan(/\[/)
         @q.push [:SBRACKET_OPEN, [s.matched, [line, s.pos - pos]]]
@@ -99,7 +99,7 @@ module_eval(<<'...end ecma.y/module_eval...', 'ecma.y', 219)
         @q.push [m, [m, [line, s.pos - pos]]]
       elsif s.scan(/\s+/)
       else
-        raise "Woops! I can daeal with char at #{line}:#{s.pos - pos}: #{s.pre_match} #{s.post_match}"
+        raise Exception, "Woops! I can daeal with char at #{line}:#{s.pos - pos}: #{s.pre_match} #{s.post_match}"
       end
     end
     @q.push([false, '$end'])

data/lib/rvm/rails.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) +'/acts_as_rvm_type.rb'
+
+# Inlcude the RVM::ACtsAsRVMType into active record so functions like
+# +acts_as_rvm_type+ and comparable
+ActiveRecord::Base.class_eval do
+  include RVM::ActsAsRVMType
+end
+
+class ActionView::Base
+  
+  # This function allows to render code that gets compiled by rvm. The first
+  # parameter passed is the code to compile, a string most likely, the second
+  # is a hash that is passed to the render function, see the Rails API doc for
+  # details on what to put there.
+  #
+  # In addition to those rails specifc parameters rvm_render accepts 4 additioal
+  # parameters.They are the same as used in +rvm_execute+.
+  def rvm_reder code, options = {}
+    render options.merge({:text => rvm_execute(code, options)})
+  end
+
+
+  # The rvm_execute executes a string of code with a certein behavior and
+  # returns not the result but what was written in the special :render variable
+  # of the enviroment.
+  #
+  # The folowing options can be passed to it to influence it's behaviro.
+  #
+  # :language:: The language that should be used to compile the code, be adwised
+  #             that it is nessessary to load this prior to executing it.
+  #
+  # :enviroment:: This allows to pass a own enviroment, for example to publish
+  #               variables or to maintain state between executions.
+  #
+  # :object:: If this is set the code will be executed in the context of the
+  #           object passed, this using it's local variable storage and it's
+  #           functions. Be aware that when using :object and :enviroment
+  #           togehter, variables set in the code will NOT go in the enviroment
+  #           as they are local in the object.
+  #
+  # :timeout:: This is used to limit the execution time of the code, it can be
+  #            used to prevent runaway processes beeing executed. Very helpfull
+  #            when the code executed isn't 100% trunstworty.
+  def rvm_execute code, options = {}
+    options = {
+      :language => :ecma,
+      :enviroment => RVM::Interpreter.env
+    }.merge(options)
+    compiler = RVM::Languages[options[:language]].new
+    code = compiler.compile(code)
+    code = RVM::Interpreter::ObjectContext.new(options[:object], code) if options[:object]
+    if options[:enviroment][:render].is_a? RVM::Classes::Error or options[:enviroment][:render].nil?
+      options[:enviroment][:render] = ""
+    end
+    puts options[:enviroment][:render].inspect
+    if options[:timeout]
+      s = RVM::Safety.new :timeout => options[:timeout]
+      s.execute(code, options[:enviroment])
+    else
+      code.execute(options[:enviroment])
+    end
+    options[:enviroment][:render].val
+  end
+end
+require File.dirname(__FILE__) + '/functions/rails.rb'

data/spec/languages/ecma/json_spec.rb

@@ -12,21 +12,144 @@ describe RVM::Languages::ECMA do
     @compiler = RVM::Languages::ECMA.new
   end
   
-  it "should compile the first json example" do
-    lambda {
-      exec File.new(File.dirname(__FILE__) + '/pass1.json').read
-    }.should_not raise_error
+  describe "positives" do
+    it "should compile the first json example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/pass1.json').read
+      }.should_not raise_error
+    end
+    
+    it "should compile the second json example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/pass2.json').read
+      }.should_not raise_error
+    end
+    
+    it "should compile the third json example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/pass3.json').read
+      }.should_not raise_error
+    end
   end
   
-  it "should compile the second json example" do
-    lambda {
-      exec File.new(File.dirname(__FILE__) + '/pass2.json').read
-    }.should_not raise_error
-  end
-  
-  it "should compile the third json example" do
-    lambda {
-      exec File.new(File.dirname(__FILE__) + '/pass3.json').read
-    }.should_not raise_error
+  describe "negatives" do
+    it "should fail the 2nd negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail2.json').read
+      }.should raise_error
+    end
+    it "should fail the 4th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail4.json').read
+      }.should raise_error
+    end
+    it "should fail the 5th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail5.json').read
+      }.should raise_error
+    end
+    it "should fail the 6th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail6.json').read
+      }.should raise_error
+    end
+    
+    it "should fail the 7th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail7.json').read
+      }.should raise_error
+    end
+    
+    it "should fail the 8th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail8.json').read
+      }.should raise_error
+    end
+    it "should fail the 9th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail9.json').read
+      }.should raise_error
+    end 
+    it "should fail the 10th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail10.json').read
+      }.should raise_error
+    end 
+    it "should fail the 12th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail12.json').read
+      }.should raise_error
+    end 
+    
+    it "should fail the 13th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail13.json').read
+      }.should raise_error
+    end
+    it "should fail the 14th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail14.json').read
+      }.should raise_error
+    end 
+    it "should fail the 15th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail15.json').read
+      }.should raise_error
+    end 
+    it "should fail the 16th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail16.json').read
+      }.should raise_error
+    end 
+    it "should fail the 17th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail17.json').read
+      }.should raise_error
+    end 
+    it "should fail the 19th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail19.json').read
+      }.should raise_error
+    end 
+    it "should fail the 20th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail20.json').read
+      }.should raise_error
+    end 
+    it "should fail the 21th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail21.json').read
+      }.should raise_error
+    end 
+    it "should fail the 22th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail22.json').read
+      }.should raise_error
+    end 
+    it "should fail the 29th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail29.json').read
+      }.should raise_error
+    end 
+    it "should fail the 30th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail30.json').read
+      }.should raise_error
+    end 
+    it "should fail the 31th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail31.json').read
+      }.should raise_error
+    end 
+    it "should fail the 32th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail32.json').read
+      }.should raise_error
+    end 
+    it "should fail the 33th negative example" do
+      lambda {
+        exec File.new(File.dirname(__FILE__) + '/json/fail33.json').read
+      }.should raise_error
+    end 
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rVM
 version: !ruby/object:Gem::Version 
-  version: 0.0.12
+  version: 0.0.13
 platform: ruby
 authors: 
 - Heinz N. Gies
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-24 00:00:00 +02:00
+date: 2008-07-29 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -85,6 +85,9 @@ files:
 - lib/rvm/functions/math.rb
 - lib/rvm/functions/objects
 - lib/rvm/functions/objects/send.rb
+- lib/rvm/functions/rails
+- lib/rvm/functions/rails/print.rb
+- lib/rvm/functions/rails.rb
 - lib/rvm/functions/string
 - lib/rvm/functions/string/ansi.rb
 - lib/rvm/functions/string/capstr.rb
@@ -107,6 +110,7 @@ files:
 - lib/rvm/languages.rb
 - lib/rvm/library.rb
 - lib/rvm/plugin.rb
+- lib/rvm/rails.rb
 - lib/rvm.rb
 - README
 has_rdoc: true