rice 1.1.0 → 1.2.0

data/Doxyfile

@@ -23,7 +23,7 @@ PROJECT_NAME           = Rice
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 1.1
+PROJECT_NUMBER         = 1.2
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 

data/Makefile.in

@@ -1,4 +1,4 @@
-# Makefile.in generated by automake 1.10.1 from Makefile.am.
+# Makefile.in generated by automake 1.10.2 from Makefile.am.
 # @configure_input@
 
 # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
@@ -229,6 +229,7 @@ sharedstatedir = @sharedstatedir@
 srcdir = @srcdir@
 sysconfdir = @sysconfdir@
 target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 AUTOMAKE_OPTIONS = foreign 1.5
@@ -384,7 +385,7 @@ ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
 	unique=`for i in $$list; do \
 	    if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
 	  done | \
-	  $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \
+	  $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
 	      END { if (nonempty) { for (i in files) print i; }; }'`; \
 	mkid -fID $$unique
 tags: TAGS

data/README

@@ -15,13 +15,17 @@ What Rice gives you:
 \li Smart pointers for handling garbage collection
 \li Wrappers for most builtin types to simplify calling code
 
-\section installation Installation
+\section project Project Details
+
+The source is hosted on github: http://github.com/jameskilton/rice
+
+Bug tracking: http://github.com/jameskilton/rice/issues
 
-There are two ways to install Rice. You can download the tarball from the project
-page:
+Mailing List: http://groups.google.com/group/ruby-rice
 
-http://rubyforge.org/projects/rice
+\section installation Installation
 
+There are two ways to install Rice. You can download the tarball from the repository,
 extract it and:
 
 \code
@@ -36,7 +40,7 @@ or you can install via RubyGems
   gem install rice
 \endcode
 
-Note to Windows users: Rice is only known to properly compile and run under Cygwin and Mingw. 
+Note to Windows users: Rice is only known to properly compile and run under Cygwin and Mingw.
 
 \section tutorial Tutorial
 
@@ -53,7 +57,8 @@ The first step is to create an extconf.rb file:
 \endcode
 
 Note that we use mkmf-rice instead of mkmf.  This will ensure that the
-extension will be linked with standard C++ library.
+extension will be linked with standard C++ library along with the Rice
+library, and allow access to the Rice header files.
 
 Next we create our extension and save it to test.cpp:
 
@@ -111,7 +116,7 @@ that this is a class and not some other type of object.  Some other
 naming conventions that are commonly used:
 
 \li rb_c variable name prefix for a Class
-\li rb_M variable name prefix for a Module
+\li rb_m variable name prefix for a Module
 \li rb_e variable name prefix for an Exception type
 \li rb_  function prefix for a function in the Ruby C API
 \li rb_f_ function prefix to differentiate between an API function that
@@ -147,7 +152,7 @@ Now let's add a method to our class:
   {
     Class rb_cTest =
       define_class("Test")
-      .define_method("hello", test_hello);
+      .define_method("hello", &test_hello);
   }
 \endcode
 
@@ -179,8 +184,8 @@ We could also add an #initialize method to our class:
   {
     Class rb_cTest =
       define_class("Test")
-      .define_method("initialize", test_initialize);
-      .define_method("hello", test_hello);
+      .define_method("initialize", &test_initialize);
+      .define_method("hello", &test_hello);
   }
 \endcode
 
@@ -338,7 +343,7 @@ The Data_Object class can be used to wrap a newly-created object:
 
 \code
   Data_Object<Foo> foo(new Foo);
-\endcode 
+\endcode
 
 or to unwrap an already-created object:
 
@@ -354,7 +359,7 @@ A Data_Object functions like a smart pointer:
   foo->foo();
   std::cout << *foo << std::endl;
 \endcode
- 
+
 Like a VALUE or an Object, data stored in a Data_Object will be marked
 by the garbage collector as long as the Data_Object is on the stack.
 
@@ -597,7 +602,7 @@ If we write this:
   extern "C"
   void Init_Test()
   {
-    define_global_function("foo", foo);
+    define_global_function("foo", &foo);
   }
 \endcode
 
@@ -612,11 +617,11 @@ To avoid this problem, it is necessary to write a wrapper function:
     foo(&c);
     return to_ruby(c);
   }
-  
+
   extern "C"
   void Init_Test()
   {
-    define_global_function("foo", wrap_foo);
+    define_global_function("foo", &wrap_foo);
   }
 \endcode
 
@@ -625,6 +630,232 @@ have pass-by-variable-reference (it uses pass-by-object-reference).
 
 Future versions of Rice will have a cleaner way of dealing with this.
 
+
+\section default_arguments Default Arguments
+
+Going back to our initial C++ class example, lets say that hello() now
+take a few arguments for what to return, one which has a default value:
+
+\code
+  class Test
+  {
+  public:
+    Test();
+    std::string hello(std::string first, std::string second = "world");
+  };
+\endcode
+
+As default parameter information is not available through templates,
+it's necessary to define this in Rice explicitly using Rice::Arg:
+
+\code
+  #include "rice/Data_Type.hpp"
+  #include "rice/Constructor.hpp"
+
+  using namespace Rice;
+
+  extern "C"
+  void Init_Test()
+  {
+    Data_Type<Test> rb_cTest =
+      define_class<Test>("Test")
+      .define_constructor(Constructor<Test>())
+      .define_method("hello",
+         &Test::hello,
+         (Arg("hello"), Arg("second") = "world")
+      );
+  }
+\endcode
+
+The syntax here is simply Arg(nameOfParameter)[ = defaultValue].  The name of the
+parameter is not important (more for readability, and the future for when/if Ruby
+gets named arguments), but the value set via operator= must match the type
+of the given parameter.
+
+These Rice::Arg objects must be in the correct order, and if there are more than
+one of them they must be surrounded in parentheses, as above, or the compilation
+will fail.
+
+It may be required to explicitly cast the default argument values to their
+appropriate types:
+
+\code
+  .define_method("hello",
+     &Test::hello,
+     (Arg("hello"), Arg("second") = (std::string)"world")
+  );
+\endcode
+
+With this, Ruby will now know about the default arguments, and this wrapper
+can be used as expected:
+
+\code
+  t = Test.new
+  t.hello("hello")
+  t.hello("goodnight", "moon")
+\endcode
+
+
+\section director Director
+
+As polymorphism is the most important tennant of Object Oriented Programming,
+it's important that Rice supports polymorphic calls travelling between C++
+and Ruby seemlessly. Super calls from Ruby subclasses back into C++ already work,
+but enabling the other direction requires some extra work. While this isn't
+something Rice can do on it's own, the Rice::Director class hides most of the
+details.
+
+Like SWIG_Director, Rice::Director is a class that is used to build a proxy class
+to properly send execution up or down the object heiarchy for that class. Take
+the following class:
+
+\code
+  class VirtualBase {
+    public:
+      VirtualBase();
+      virtual int doWork();
+      virtual int processWorker() = 0;
+  };
+\endcode
+
+Due to the abstract nature of this class, it will not work at all with Rice
+in it's current form. Any attempt to do so will cause a compilation error due to
+this class not being constructable. Even without the pure virtual function, any
+call to VirtualBase::doWork will stop at the C++ level and not pass down into
+any Ruby subclasses.
+
+To properly wrap both of these methods, you'll need to build a proxy class
+that subclasses Rice::Director:
+
+\code
+  #include "rice/Director.hpp"
+
+  class VirtualBaseProxy : public VirtualBase, public Rice::Director {
+    public:
+      VirtualBaseProxy(Object self) : Rice::Director(self) { }
+
+      virtual int doWork() {
+        if(callIsFromRuby("do_work")) {
+          return VirtualBase::doWork();
+        } else {
+          return from_ruby<int>( getSelf().call("do_work") );
+        }
+      }
+
+      virtual int processWorker() {
+        if(callIsFromRuby("process_worker")) {
+          raisePureVirtual();
+        } else {
+          return from_ruby<int>( getSelf().call("process_worker") );
+        }
+      }
+  };
+\endcode
+
+There is a lot going on here, so we'll take go through each part.
+
+\code
+  class VirtualBaseProxy : public Virtualbase, public Rice::Director {
+\endcode
+
+First, the class needs to subclass both the virtual class and Rice::Director.
+
+\code
+    public:
+      VirtualBaseProxy(Object self) : Rice::Director(self) { }
+\endcode
+
+For Rice::Director to work its magic, every instance of this class needs to
+have a handle to the Ruby instance of this class as well. The constructor
+must take a Rice::Object as the first argument, then any other arguments follow
+and should be passed back to the superclass as needed. The code here is the
+minimum required for a Rice::Director proxy.
+
+\code
+      virtual int doWork() {
+        if(callIsFromRuby("do_work")) {
+          // Call from Ruby via super, head up the stack
+          return VirtualBase::doWork();
+        } else {
+          // Call from C++ heading down the stack, get self
+          // and call the method in Ruby, taking care to
+          // convert types to and from ruby as needed.
+          return from_ruby<int>( getSelf().call("do_work") );
+        }
+      }
+\endcode
+
+Every virtual method needs to have a special definition inside of this proxy class.
+Use Rice::Director::callIsFromRuby to check if execution is passing up or down
+the heirarchy. The name passed to this method needs to be the name as exposed to Ruby
+(which will be seen in the wrapper code below).
+
+A special case as seen in the proxy method for processWorker is the raisePureVirtual
+method. In the case of pure virtual methods, the proxy is the top of the heirarchy.
+This proxy could be written more simply:
+
+\code
+      virtual int processWorker() {
+        return from_ruby<int>( getSelf().call("process_worker") );
+      }
+\endcode
+
+but if the Ruby code accidentally calls #super, the code will get stuck in an infinite loop.
+To prevent this from happening, use Rice::Director::raisePureVirtual to inform users of the 
+extension that they should not be calling up into C++ for that method.
+
+Once the proxy class is built, it's time to wrap it into Ruby:
+
+\code
+extern "C"
+void Init_virtual() {
+  // See Caveat below
+  define_class<VirtualBase>("__VirtualBase__");
+
+  define_class<VirtualBaseProxy, VirtualBase>("VirtualBase")
+    .define_method("do_work", &VirtualBaseProxy::doWork)
+    .define_method("process_worker", &VirtualBaseProxy::processWorker);
+}
+\endcode
+
+The wrapping is the same as is described earlier in this document. Expose the class
+VirtualBaseProxy named as VirtualBase, register it as a subclass of VirtualBase,
+and define methods pointing to the proxy object.
+
+<b>Caveat</b>: Rice figures out inheritance and class heirarchies solely through
+the types given in define_class. Ideally Rice would be able to handle this edge
+case automatically, but for now you'll still need to tell Rice about the base class
+being wrapped into a Rice::Director proxy, or type casting will throw an exception
+during execution. So as a general rule, make sure that any class you use as SuperClass 
+in define_class<Class, SuperClass> is also itself
+exposed.
+
+Following this, if you have subclasses of virtual classes that themselves have virtual
+methods, you need to set the Rice::Director proxy as the superclass of that class,
+something like:
+
+\code
+  // Given a class like this
+  class SubVirtual : public VirtualBase {
+    public:
+      virtual int doMoreWork();
+  }
+
+  // You'd need another Director proxy
+  class SubVirtualDirector : public SubVirtual, public VirtualBase, public Rice::Director {
+    ...
+  }
+
+  // And expose it in Rice as such
+  define_class<SubVirtual, VirtualBaseProxy>("__SubVirtual__");
+  define_class<SubVirtualDirector, SubVirtual>("SubVirtual")
+    ...
+
+\endcode
+
+This situation has not been fully tested
+
+
 \section motivation Motivation
 
 There are a number of common problems when writing C or C++ extensions
@@ -840,7 +1071,7 @@ class:
     vm.run()
   }
 \endcode
-  
+
 If the VM is not initialized from main() -- from a callback, for example
 -- then you may need to initialize the stack whenever you use Rice or
 the Ruby API:

data/aclocal.m4

@@ -1,4 +1,4 @@
-# generated automatically by aclocal 1.10.1 -*- Autoconf -*-
+# generated automatically by aclocal 1.10.2 -*- Autoconf -*-
 
 # Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
 # 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
@@ -13,13 +13,13 @@
 
 m4_ifndef([AC_AUTOCONF_VERSION],
   [m4_copy([m4_PACKAGE_VERSION], [AC_AUTOCONF_VERSION])])dnl
-m4_if(AC_AUTOCONF_VERSION, [2.61],,
-[m4_warning([this file was generated for autoconf 2.61.
+m4_if(m4_defn([AC_AUTOCONF_VERSION]), [2.63],,
+[m4_warning([this file was generated for autoconf 2.63.
 You have another version of autoconf.  It may work, but is not guaranteed to.
 If you have problems, you may need to regenerate the build system entirely.
 To do so, use the procedure documented by the package, typically `autoreconf'.])])
 
-# Copyright (C) 2002, 2003, 2005, 2006, 2007  Free Software Foundation, Inc.
+# Copyright (C) 2002, 2003, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
 #
 # This file is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
@@ -34,7 +34,7 @@ AC_DEFUN([AM_AUTOMAKE_VERSION],
 [am__api_version='1.10'
 dnl Some users find AM_AUTOMAKE_VERSION and mistake it for a way to
 dnl require some minimum version.  Point them to the right macro.
-m4_if([$1], [1.10.1], [],
+m4_if([$1], [1.10.2], [],
       [AC_FATAL([Do not call $0, use AM_INIT_AUTOMAKE([$1]).])])dnl
 ])
 
@@ -48,12 +48,12 @@ m4_define([_AM_AUTOCONF_VERSION], [])
 # AM_SET_CURRENT_AUTOMAKE_VERSION
 # -------------------------------
 # Call AM_AUTOMAKE_VERSION and AM_AUTOMAKE_VERSION so they can be traced.
-# This function is AC_REQUIREd by AC_INIT_AUTOMAKE.
+# This function is AC_REQUIREd by AM_INIT_AUTOMAKE.
 AC_DEFUN([AM_SET_CURRENT_AUTOMAKE_VERSION],
-[AM_AUTOMAKE_VERSION([1.10.1])dnl
+[AM_AUTOMAKE_VERSION([1.10.2])dnl
 m4_ifndef([AC_AUTOCONF_VERSION],
   [m4_copy([m4_PACKAGE_VERSION], [AC_AUTOCONF_VERSION])])dnl
-_AM_AUTOCONF_VERSION(AC_AUTOCONF_VERSION)])
+_AM_AUTOCONF_VERSION(m4_defn([AC_AUTOCONF_VERSION]))])
 
 # AM_AUX_DIR_EXPAND                                         -*- Autoconf -*-
 
@@ -303,57 +303,68 @@ _AM_SUBST_NOTMAKE([AMDEPBACKSLASH])dnl
 
 # Generate code to set up dependency tracking.              -*- Autoconf -*-
 
-# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005
+# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
 # Free Software Foundation, Inc.
 #
 # This file is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
 # with or without modifications, as long as this notice is preserved.
 
-#serial 3
+#serial 5
 
 # _AM_OUTPUT_DEPENDENCY_COMMANDS
 # ------------------------------
 AC_DEFUN([_AM_OUTPUT_DEPENDENCY_COMMANDS],
-[for mf in $CONFIG_FILES; do
-  # Strip MF so we end up with the name of the file.
-  mf=`echo "$mf" | sed -e 's/:.*$//'`
-  # Check whether this is an Automake generated Makefile or not.
-  # We used to match only the files named `Makefile.in', but
-  # some people rename them; so instead we look at the file content.
-  # Grep'ing the first line is not enough: some people post-process
-  # each Makefile.in and add a new line on top of each file to say so.
-  # Grep'ing the whole file is not good either: AIX grep has a line
-  # limit of 2048, but all sed's we know have understand at least 4000.
-  if sed -n 's,^#.*generated by automake.*,X,p' "$mf" | grep X >/dev/null 2>&1; then
-    dirpart=`AS_DIRNAME("$mf")`
-  else
-    continue
-  fi
-  # Extract the definition of DEPDIR, am__include, and am__quote
-  # from the Makefile without running `make'.
-  DEPDIR=`sed -n 's/^DEPDIR = //p' < "$mf"`
-  test -z "$DEPDIR" && continue
-  am__include=`sed -n 's/^am__include = //p' < "$mf"`
-  test -z "am__include" && continue
-  am__quote=`sed -n 's/^am__quote = //p' < "$mf"`
-  # When using ansi2knr, U may be empty or an underscore; expand it
-  U=`sed -n 's/^U = //p' < "$mf"`
-  # Find all dependency output files, they are included files with
-  # $(DEPDIR) in their names.  We invoke sed twice because it is the
-  # simplest approach to changing $(DEPDIR) to its actual value in the
-  # expansion.
-  for file in `sed -n "
-    s/^$am__include $am__quote\(.*(DEPDIR).*\)$am__quote"'$/\1/p' <"$mf" | \
-       sed -e 's/\$(DEPDIR)/'"$DEPDIR"'/g' -e 's/\$U/'"$U"'/g'`; do
-    # Make sure the directory exists.
-    test -f "$dirpart/$file" && continue
-    fdir=`AS_DIRNAME(["$file"])`
-    AS_MKDIR_P([$dirpart/$fdir])
-    # echo "creating $dirpart/$file"
-    echo '# dummy' > "$dirpart/$file"
+[{
+  # Autoconf 2.62 quotes --file arguments for eval, but not when files
+  # are listed without --file.  Let's play safe and only enable the eval
+  # if we detect the quoting.
+  case $CONFIG_FILES in
+  *\'*) eval set x "$CONFIG_FILES" ;;
+  *)   set x $CONFIG_FILES ;;
+  esac
+  shift
+  for mf
+  do
+    # Strip MF so we end up with the name of the file.
+    mf=`echo "$mf" | sed -e 's/:.*$//'`
+    # Check whether this is an Automake generated Makefile or not.
+    # We used to match only the files named `Makefile.in', but
+    # some people rename them; so instead we look at the file content.
+    # Grep'ing the first line is not enough: some people post-process
+    # each Makefile.in and add a new line on top of each file to say so.
+    # Grep'ing the whole file is not good either: AIX grep has a line
+    # limit of 2048, but all sed's we know have understand at least 4000.
+    if sed -n 's,^#.*generated by automake.*,X,p' "$mf" | grep X >/dev/null 2>&1; then
+      dirpart=`AS_DIRNAME("$mf")`
+    else
+      continue
+    fi
+    # Extract the definition of DEPDIR, am__include, and am__quote
+    # from the Makefile without running `make'.
+    DEPDIR=`sed -n 's/^DEPDIR = //p' < "$mf"`
+    test -z "$DEPDIR" && continue
+    am__include=`sed -n 's/^am__include = //p' < "$mf"`
+    test -z "am__include" && continue
+    am__quote=`sed -n 's/^am__quote = //p' < "$mf"`
+    # When using ansi2knr, U may be empty or an underscore; expand it
+    U=`sed -n 's/^U = //p' < "$mf"`
+    # Find all dependency output files, they are included files with
+    # $(DEPDIR) in their names.  We invoke sed twice because it is the
+    # simplest approach to changing $(DEPDIR) to its actual value in the
+    # expansion.
+    for file in `sed -n "
+      s/^$am__include $am__quote\(.*(DEPDIR).*\)$am__quote"'$/\1/p' <"$mf" | \
+	 sed -e 's/\$(DEPDIR)/'"$DEPDIR"'/g' -e 's/\$U/'"$U"'/g'`; do
+      # Make sure the directory exists.
+      test -f "$dirpart/$file" && continue
+      fdir=`AS_DIRNAME(["$file"])`
+      AS_MKDIR_P([$dirpart/$fdir])
+      # echo "creating $dirpart/$file"
+      echo '# dummy' > "$dirpart/$file"
+    done
   done
-done
+}
 ])# _AM_OUTPUT_DEPENDENCY_COMMANDS
 
 
@@ -659,13 +670,13 @@ esac
 
 # Helper functions for option handling.                     -*- Autoconf -*-
 
-# Copyright (C) 2001, 2002, 2003, 2005  Free Software Foundation, Inc.
+# Copyright (C) 2001, 2002, 2003, 2005, 2008  Free Software Foundation, Inc.
 #
 # This file is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
 # with or without modifications, as long as this notice is preserved.
 
-# serial 3
+# serial 4
 
 # _AM_MANGLE_OPTION(NAME)
 # -----------------------
@@ -682,7 +693,7 @@ AC_DEFUN([_AM_SET_OPTION],
 # ----------------------------------
 # OPTIONS is a space-separated list of Automake options.
 AC_DEFUN([_AM_SET_OPTIONS],
-[AC_FOREACH([_AM_Option], [$1], [_AM_SET_OPTION(_AM_Option)])])
+[m4_foreach_w([_AM_Option], [$1], [_AM_SET_OPTION(_AM_Option)])])
 
 # _AM_IF_OPTION(OPTION, IF-SET, [IF-NOT-SET])
 # -------------------------------------------