RSRuby 0.4.0

data/ext/rsruby/rsruby.h

@@ -0,0 +1,80 @@
+/*
+* == Author
+* Alex Gutteridge
+*
+* == Copyright
+*Copyright (C) 2006 Alex Gutteridge
+*
+* The Original Code is the RPy python module.
+*
+* The Initial Developer of the Original Code is Walter Moreira.
+* Portions created by the Initial Developer are Copyright (C) 2002
+* the Initial Developer. All Rights Reserved.
+*
+* Contributor(s):
+*    Gregory R. Warnes <greg@warnes.net> (RPy Maintainer)
+*
+*This library is free software; you can redistribute it and/or
+*modify it under the terms of the GNU Lesser General Public
+*License as published by the Free Software Foundation; either
+*version 2.1 of the License, or (at your option) any later version.
+*
+*This library is distributed in the hope that it will be useful,
+*but WITHOUT ANY WARRANTY; without even the implied warranty of
+*MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+*Lesser General Public License for more details.
+*
+*You should have received a copy of the GNU Lesser General Public
+*License along with this library; if not, write to the Free Software
+*Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+#ifndef R_RUBY_MAIN
+#define R_RUBY_MAIN
+
+#include "ruby.h"
+
+#include "R.h"
+#include "Rdefines.h"
+#include "Rinternals.h"
+#include "Rdefines.h"
+#include "Rdevices.h"
+
+#include "signal.h"
+
+#include "R_eval.h"
+#include "Converters.h"
+
+#define MAXIDSIZE 256
+
+#define NO_CONVERSION 0
+#define VECTOR_CONVERSION 1
+#define BASIC_CONVERSION 2
+#define CLASS_CONVERSION 3
+#define PROC_CONVERSION 4
+
+#define TOP_MODE 4
+
+/* Missing definitions from Rinterface.h or RStartup.h */
+# define CleanEd Rf_CleanEd
+extern void CleanEd(void);
+extern int R_CollectWarnings; 
+# define PrintWarnings Rf_PrintWarnings
+extern void PrintWarnings(void);
+
+void Init_rsruby();
+
+void init_R(int argc, char *argv[0]);
+void r_finalize(void);
+
+static SEXP RecursiveRelease(SEXP obj, SEXP list);
+static void Robj_dealloc(VALUE self);
+
+VALUE shutdown(VALUE self);
+VALUE get_fun(VALUE self, VALUE name);
+VALUE rr_init(VALUE self);
+
+VALUE RObj_lcall(VALUE self, VALUE args);
+VALUE RObj_to_ruby(VALUE self, VALUE args);
+
+#endif

data/lib/rsruby.rb

@@ -0,0 +1,361 @@
+#== Synopsis
+#
+#This class provides the ability to embed a full R
+#interpreter inside a running Ruby script. R methods can
+#then be called from the Ruby script and data passed between the 
+#R interpreter and the Ruby script. The code is based on a conversion
+#of the RSPerl[http://www.omegahat.org/RSPerl/] and RPy[http://rpy.sourceforge.net/] 
+#modules which provide similar (and more) functionality for Perl and Python 
+#respectively.
+#
+#The main RSRuby class has Singleton module mixed in. This ensures that only
+#one R interpreter is running in a script at any one time and that the
+#interpreter can always be found. The embedded R interpreter is started by
+#calling RSRuby.instance (See the RSRuby class for details). The returned 
+#RSRuby object represents the R interpreter and R functions are called by 
+#calling methods on this object.
+#
+#== Usage
+#
+# require 'rsruby'
+#
+# r = RSRuby.instance
+# puts r.sum(1,2,3)
+#
+#Converting between R and Ruby data types is handled in a similar way to
+#RPy and is explained in more detail in the manual (see Converters.c for the
+#gory details). 
+#
+#The default conversion system mapping between R types and Ruby classes is 
+#summarised here:
+#
+# - R Logicals (true/false) <=> Ruby true/false
+# - R Integers <=> Ruby Fixnum/Bignum
+# - R Real     <=> Ruby Float
+# - R Complex  <=> Ruby Complex
+# - R String   <=> Ruby String
+# - R Vector   <=> Ruby Array or Hash
+# - R List     <=> Ruby Array or Hash
+# - R Array    <=> Ruby Array or Hash
+# - R 'other'  <=> Ruby RObj
+#
+#While this generally works fine for simple data structures, more complicated
+#structures can loose information when converted to Ruby. Clever use of the
+#more complicated custom conversion modes can usually avoid this.
+#
+#As shown above, calling R methods can be done by calling the same method
+#on the RSRuby object. Some R methods contain '.' and other characters
+#forbidden in Ruby method names. To call these methods substitute '_' for '.':
+#
+#Sample usage (to call R method 'as.list'):
+#
+# require 'rsruby'
+#
+# r = RSRuby.instance
+# puts r.as_list([1,2,3])
+#
+#If a Hash is the last argument to an RSRuby method call then the hash is
+#interpreted as a list of named arguments to the corresponding R function. 
+#Argument names can be given as Strings or Symbols. Argument order is not
+#maintained in this case (because order is not maintained in Hashes). If 
+#named arguments and order are required then there is the lcall syntax where
+#arguments are given as an array of two member arrays (where each two member
+#array represents a name/argument pair). lcall is a method defined in the
+#RObj class which represents functions and other non-convertible R objects.
+#
+#Calling an R method with no arguments returns the method object itself - it
+#does not call the method. This may be changed in the future as it is somewhat
+#confusing. However, the returned object can then be called or 'lcall'ed as
+#required. It is also possible to return R variables in this way:
+#
+#E.g.
+#
+# require 'rsruby'
+#
+# r = RSRuby.instance
+# norm = r.rnorm
+# norm_dist = norm.call(100)
+#
+# r.plot(norm_dist,
+#        {:ylab => "TestY"})
+# sleep(2)
+#
+#
+#The final way to execute R code is to just evaluate a complete R expression
+#The eval_R method provides this functionality. Pass a String to the method to
+#see it evaluated by R:
+#
+# require 'rsruby'
+#
+# r = RSRuby.instance
+# r.eval_R("a=43")
+# puts r.a
+#
+#As an alternative to the method syntax, R objects and functions can be
+#returned using []. This is required for weird R methods such as '$' or '[[':
+#
+# require 'rsruby'
+#
+# r = RSRuby.instance
+# r.eval_R("a=43")
+# puts r['a']
+#
+#R libraries can be loaded using the library method. Just provide the library
+#name as a String:
+#
+# require  'rsruby'
+#
+# r = RSRuby.instance
+# r.library("library_name")
+#
+#== Author
+#Alex Gutteridge
+#
+#== Copyright
+#Copyright (C) 2006 Alex Gutteridge
+#
+#The Original Code is the RPy python module.
+#
+#The Initial Developer of the Original Code is Walter Moreira.
+#Portions created by the Initial Developer are Copyright (C) 2002
+#the Initial Developer. All Rights Reserved.
+#
+#Contributor(s):
+#Gregory R. Warnes <greg@warnes.net> (RPy Maintainer)
+#
+#This library is free software; you can redistribute it and/or
+#modify it under the terms of the GNU Lesser General Public
+#License as published by the Free Software Foundation; either
+#version 2.1 of the License, or (at your option) any later version.
+#
+#This library is distributed in the hope that it will be useful,
+#but WITHOUT ANY WARRANTY; without even the implied warranty of
+#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#Lesser General Public License for more details.
+#
+#You should have received a copy of the GNU Lesser General Public
+#License along with this library; if not, write to the Free Software
+#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+require 'rsruby/robj'
+require 'rsruby.so'
+require 'singleton'
+
+require 'complex'
+
+class RException < RuntimeError
+end
+
+class RSRuby
+
+  include Singleton
+
+  #Constants for conversion modes
+  TOP_CONVERSION = 4
+  PROC_CONVERSION = 4
+  CLASS_CONVERSION = 3
+  BASIC_CONVERSION = 2
+  VECTOR_CONVERSION = 1
+  NO_CONVERSION = 0
+  NO_DEFAULT = -1
+
+  alias c_initialize initialize
+
+  #Create a new RSRuby interpreter instance. The Singleton design pattern
+  #ensures that only one instance can be running in a script. Further
+  #calls to RSRuby.instance will return the original instance.
+  def initialize()
+
+    #Initialize in C
+    c_initialize
+
+    @@default_mode = NO_DEFAULT
+
+    @@class_table = {}
+    @@proc_table  = {}
+
+    #Setup R object cache
+    @@cache = {}
+    @@cache['get'] = self.get_fun('get')
+
+    #Get constants
+    @@cache['TRUE']  = self.__getitem__('T')
+    @@cache['FALSE'] = self.__getitem__('F')
+    @@cache['NA']    = self.eval_R('NA')
+    # @@cache['NAN']   = self.eval_R('as.double(NA)')
+    @@cache['NaN']   = self.eval_R('NaN')
+    
+    #help!
+    @@cache['helpfun'] = self.with_mode(NO_CONVERSION, self.__getitem__('help'))
+
+    #Catch errors
+    self.eval_R("options(error=expression(NULL))")
+    #disable errors
+    self.options('show.error.messages' => false)
+
+  end
+
+  #Handles method name conversion and calling of R functions
+  #If called without args the R function/varialbe is returned rather
+  #than called.
+  def method_missing(r_id,*args)
+
+    #Translate Ruby method call to R
+    robj_name = RSRuby.convert_method_name(r_id.to_s)
+
+    #Retrieve it
+    robj = self.__getitem__(robj_name)
+
+    #TODO perhaps this is not neccessary - always call these methods
+    #use the [] syntax for variables etc...
+    if args.length > 0
+
+      #convert arguments to lcall format
+      lcall_args = RSRuby.convert_args_to_lcall(args)
+      
+      #Return result of calling object with lcall 
+      #formatted args
+      return robj.lcall(lcall_args)
+
+    end
+
+    return robj
+
+  end  
+
+  #As method_missing, but only returns the R function/object
+  #does not call it.
+  def [](r_id)
+
+    #Translate Ruby method call to R
+    robj_name = RSRuby.convert_method_name(r_id.to_s)
+    
+    #Retrieve it
+    robj = self.__getitem__(robj_name)
+    
+    #And return it
+    return robj
+
+  end
+
+  #Takes an #RObj representing an R function and sets the 'wrapping'
+  #mode for that function. Implemented for compatibility with RPy.
+  def with_mode(mode,func)
+    func.wrap = mode
+    return func
+  end
+
+  #Converts method names from Ruby compatible style into R style.
+  def RSRuby.convert_method_name(name)
+    if name.length > 1 and name[-1].chr == '_' and name[-2].chr != '_'
+      name = name[0..-2]
+    end
+    name.gsub!(/__/,'<-')
+    name.gsub!(/_/, '.')
+    return name
+  end
+
+  #Converts an array of arguments into lcall format. If the last element
+  #of the array is a Hash then the contents are interpreted as named
+  #arguments. lcall format is an Array of two member Arrays. Each two
+  #member array corresponds to a name/argument pair.
+  def RSRuby.convert_args_to_lcall(args)
+
+    lcall_args = []
+    
+    args.each_with_index do |arg,i|
+      unless arg.kind_of?(Hash) and i == args.length-1
+        lcall_args.push(['',arg])
+      else
+        arg.each do |k,v|
+          lcall_args.push([k.to_s,v])
+        end
+      end
+    end
+
+    return lcall_args
+
+  end
+
+  #Sets the default conversion mode for RSRuby. The constants defined
+  #in #RSRuby should be used
+  def RSRuby.set_default_mode(m)
+    if m < -1 or m > TOP_CONVERSION
+      raise ArgumentError, "Invalid mode requested"
+    end
+    @@default_mode = m
+  end
+  #Returns the current default conversion mode as an Integer.
+  def RSRuby.get_default_mode
+    @@default_mode
+  end
+
+  #TODO - input/output setting methods don't work atm
+  def RSRuby.set_rsruby_input(m)
+    @@rsruby_input = m
+  end
+  def RSRuby.get_rsruby_input
+    @@rsruby_input
+  end
+
+  def RSRuby.set_rsruby_output(m)
+    @@rsruby_output = m
+  end
+  def RSRuby.get_rsruby_output
+    @@rsruby_output
+  end
+
+  def RSRuby.set_rsruby_showfiles(m)
+    @@rsruby_showfiles = m
+  end
+  def RSRuby.get_rsruby_showfiles
+    @@rsruby_showfiles
+  end
+
+  #Returns the current class table Hash for RSRuby.
+  def class_table
+    @@class_table
+  end
+
+  #Sets the RSRuby class table Hash.
+  def class_table=(h)
+    @@class_table = h
+  end
+
+  #Returns the current proc table Hash for RSRuby.  
+  def proc_table
+    @@proc_table
+  end
+
+  #Sets the RSRuby proc table Hash.  
+  def proc_table=(h)
+    @@proc_table = h
+  end
+
+  #Evaluates the given string in R. Returns the result of the evaluation.
+  def eval_R(s)
+    self.eval(self.parse(:text => s))
+  end
+
+  #Wraps the R help function.
+  def help(*args)
+    helpobj = @@cache['helpfun'].call(args)
+    self.print(helpobj)
+  end
+
+  :private
+  def __getitem__(name)
+
+    #Find the identifier and cache (unless already cached)
+    unless @@cache.has_key?(name)
+      @@cache[name] = @@cache['get'].lcall([['',name]])
+    end
+
+    #Retrieve object from cache
+    robj = @@cache[name]
+
+    return robj
+
+  end
+
+end

data/lib/rsruby/dataframe.rb

@@ -0,0 +1,77 @@
+#== Synopsis
+#
+#This is an extended #ERObj class inspired by the example given in the RPy
+#manual used for R data frames. 
+#As with ERobj, methods caught by method_missing are converted into attribute 
+#calls on the R dataframe it represents. The rows and columns methods give
+#access to the column and row names.
+#
+#== Usage
+#
+#See examples/dataframe.rb for examples of usage.
+#
+#--
+#== Author
+#Alex Gutteridge
+#
+#== Copyright
+#Copyright (C) 2006 Alex Gutteridge
+#
+# The Original Code is the RPy python module.
+#
+# The Initial Developer of the Original Code is Walter Moreira.
+# Portions created by the Initial Developer are Copyright (C) 2002
+# the Initial Developer. All Rights Reserved.
+#
+# Contributor(s):
+#    Gregory R. Warnes <greg@warnes.net> (RPy Maintainer)
+#
+#This library is free software; you can redistribute it and/or
+#modify it under the terms of the GNU Lesser General Public
+#License as published by the Free Software Foundation; either
+#version 2.1 of the License, or (at your option) any later version.
+#
+#This library is distributed in the hope that it will be useful,
+#but WITHOUT ANY WARRANTY; without even the implied warranty of
+#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#Lesser General Public License for more details.
+#
+#You should have received a copy of the GNU Lesser General Public
+#License along with this library; if not, write to the Free Software
+#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+#++
+
+require 'rsruby'
+require 'rsruby/erobj'
+
+class DataFrame < ERObj
+
+  #Returns an array of the row names used in the R data frame.
+  def rows
+    return @r.attr(@robj, 'row.names')
+  end
+
+  #Returns an array of the column names used in the R data frame.
+  def columns
+    cols = @r.colnames(@robj)
+    cols = [cols] unless cols.class == 'Array'
+    return cols
+  end
+
+  def method_missing(attr)
+    attr = attr.to_s
+    mode = RSRuby.get_default_mode
+    RSRuby.set_default_mode(RSRuby::BASIC_CONVERSION)
+    column_names = @r.colnames(@robj)
+    if attr == column_names or column_names.include?(attr)
+      RSRuby.set_default_mode(mode)
+      return @r['$'].call(@robj,attr.to_s)
+    end
+
+    #? Not sure what here...
+    RSRuby.set_default_mode(mode)
+    return super(attr)
+
+  end
+
+end