rice 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d9e3777fb35b3ff2463c30d6ec4d799ca47dcc69
-  data.tar.gz: 477180b1c3be9f330c1cf9e8675e8d947d6ed549
+  metadata.gz: 7b48f6fad0387e0af0b875368cf76cc7fefd0fb9
+  data.tar.gz: 23bc4f4e7bd5c9cba4e261259c15bd932d979abc
 SHA512:
-  metadata.gz: 784a3e9d47f1aba190d3e8aa8637d1e681a5344d43834168ad9bee4ee078080dbf6aaffd51eac88579e49bee880261253f19def28d3419056e0976fe3fa00ebf
-  data.tar.gz: 86b4ba50634d38e6ab8a0b18a9a9b0ec8bc0d52a0670785b2a9a9f663c7ebde2fe43c057fb6d1e648b880641bc0c1dbb5ef533f225e85182a1204813d2fd7f44
+  metadata.gz: 05f85e6ae14093a830d4aea7aa509b8c6dce523ac0297b1036a930e9319f5ce5dfd817fa40a1046231a4728ca02dc25c73d26675d4ff7d001b51567914ebad8c
+  data.tar.gz: a8462693ca9aa5e01645fa0177574902c834f4b23253d5a1ba8d50a471367cc7b22e998c3fa568537090c598cfc60d0a6f09e9ec69dd24d88b36a11552751cfd

data/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Rice"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.6.0
+PROJECT_NUMBER         = 2.0.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

data/Makefile.in

@@ -1,7 +1,7 @@
-# Makefile.in generated by automake 1.14.1 from Makefile.am.
+# Makefile.in generated by automake 1.15 from Makefile.am.
 # @configure_input@
 
-# Copyright (C) 1994-2013 Free Software Foundation, Inc.
+# Copyright (C) 1994-2014 Free Software Foundation, Inc.
 
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
@@ -44,7 +44,17 @@
 #
 # This is usually added to MOSTLYCLEANFILES.
 VPATH = @srcdir@
-am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+am__is_gnu_make = { \
+  if test -z '$(MAKELEVEL)'; then \
+    false; \
+  elif test -n '$(MAKE_HOST)'; then \
+    true; \
+  elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+    true; \
+  else \
+    false; \
+  fi; \
+}
 am__make_running_with_option = \
   case $${target_option-} in \
       ?) ;; \
@@ -107,11 +117,6 @@ PRE_UNINSTALL = :
 POST_UNINSTALL = :
 build_triplet = @build@
 host_triplet = @host@
-DIST_COMMON = $(srcdir)/doxygen.am $(srcdir)/Makefile.in \
-	$(srcdir)/Makefile.am $(top_srcdir)/configure \
-	$(am__configure_deps) \
-	$(top_srcdir)/rice/detail/ruby_version_code.hpp.in COPYING \
-	README TODO config.guess config.sub depcomp install-sh missing
 subdir = .
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/check_stdcxx_11.ac \
@@ -119,6 +124,8 @@ am__aclocal_m4_deps = $(top_srcdir)/check_stdcxx_11.ac \
 	$(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
 	$(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(top_srcdir)/configure \
+	$(am__configure_deps) $(am__DIST_COMMON)
 am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \
  configure.lineno config.status.lineno
 mkinstalldirs = $(install_sh) -d
@@ -181,6 +188,9 @@ ETAGS = etags
 CTAGS = ctags
 CSCOPE = cscope
 DIST_SUBDIRS = $(SUBDIRS)
+am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/doxygen.am \
+	$(top_srcdir)/rice/detail/ruby_version_code.hpp.in COPYING \
+	README TODO config.guess config.sub depcomp install-sh missing
 DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
 distdir = $(PACKAGE)-$(VERSION)
 top_distdir = "$(distdir)"
@@ -413,7 +423,6 @@ $(srcdir)/Makefile.in:  $(srcdir)/Makefile.am $(srcdir)/doxygen.am $(am__configu
 	echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign Makefile'; \
 	$(am__cd) $(top_srcdir) && \
 	  $(AUTOMAKE) --foreign Makefile
-.PRECIOUS: Makefile
 Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
 	@case '$?' in \
 	  *config.status*) \
@@ -423,7 +432,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
 	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe)'; \
 	    cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe);; \
 	esac;
-$(srcdir)/doxygen.am:
+$(srcdir)/doxygen.am $(am__empty):
 
 $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
 	$(SHELL) ./config.status --recheck
@@ -623,15 +632,15 @@ dist-xz: distdir
 	$(am__post_remove_distdir)
 
 dist-tarZ: distdir
-	@echo WARNING: "Support for shar distribution archives is" \
-	               "deprecated." >&2
+	@echo WARNING: "Support for distribution archives compressed with" \
+		       "legacy program 'compress' is deprecated." >&2
 	@echo WARNING: "It will be removed altogether in Automake 2.0" >&2
 	tardir="$(distdir)" && $(am__tar) | compress -c >"$(distdir)".tar.Z
 	$(am__post_remove_distdir)
 
 dist-shar: distdir
-	@echo WARNING: "Support for distribution archives compressed with" \
-		       "legacy program 'compress' is deprecated." >&2
+	@echo WARNING: "Support for shar distribution archives is" \
+	               "deprecated." >&2
 	@echo WARNING: "It will be removed altogether in Automake 2.0" >&2
 	shar "$(distdir)" | GZIP=$(GZIP_ENV) gzip -c >"$(distdir)".shar.gz
 	$(am__post_remove_distdir)
@@ -667,17 +676,17 @@ distcheck: dist
 	esac
 	chmod -R a-w "$(distdir)"
 	chmod u+w "$(distdir)"
-	mkdir "$(distdir)"/_build "$(distdir)"/_inst
+	mkdir "$(distdir)"/_build "$(distdir)"/_build/sub "$(distdir)"/_inst
 	chmod a-w "$(distdir)"
 	test -d "$(distdir)"/_build || exit 0; \
 	dc_install_base=`$(am__cd) "$(distdir)"/_inst && pwd | sed -e 's,^[^:\\/]:[\\/],/,'` \
 	  && dc_destdir="$${TMPDIR-/tmp}/am-dc-$$$$/" \
 	  && am__cwd=`pwd` \
-	  && $(am__cd) "$(distdir)"/_build \
-	  && ../configure \
+	  && $(am__cd) "$(distdir)"/_build/sub \
+	  && ../../configure \
 	    $(AM_DISTCHECK_CONFIGURE_FLAGS) \
 	    $(DISTCHECK_CONFIGURE_FLAGS) \
-	    --srcdir=.. --prefix="$$dc_install_base" \
+	    --srcdir=../.. --prefix="$$dc_install_base" \
 	  && $(MAKE) $(AM_MAKEFLAGS) \
 	  && $(MAKE) $(AM_MAKEFLAGS) dvi \
 	  && $(MAKE) $(AM_MAKEFLAGS) check \
@@ -851,6 +860,8 @@ uninstall-am:
 	maintainer-clean-generic mostlyclean mostlyclean-generic pdf \
 	pdf-am ps ps-am tags tags-am uninstall uninstall-am
 
+.PRECIOUS: Makefile
+
 
 @DX_COND_doc_TRUE@@DX_COND_ps_TRUE@doxygen-ps: @DX_DOCDIR@/@PACKAGE@.ps
 

data/README

@@ -21,8 +21,6 @@ The source is hosted on github: http://github.com/jasonroelofs/rice
 
 Bug tracking: http://github.com/jasonroelofs/rice/issues
 
-Mailing List: rice@librelist.com (your first email will be used as a subscription request and dropped)
-
 \section installation Installation
 
 \code
@@ -40,13 +38,6 @@ Building it locally from a clone of the repository is as follows:
 Rice is known to work on *nix and OSX. Windows is not currently
 supported.
 
-Rice does not work with any Ruby compiled with the Falcon
-performans patches as they make changes to some internals which Rice
-relies on.
-
-Also Rice requires a Ruby built with --enable-shared and will not
-install properly against a Ruby with only static libraries.
-
 \section tutorial Tutorial
 
 \subsection geting_started Getting started
@@ -69,13 +60,13 @@ Next we create our extension and save it to test.cpp:
 
 \code
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
   }
 \endcode
 
 Note the extern "C" line above.  This tells the compiler that the
-function Init_Test should have C linkage and calling convention.  This
+function Init_test should have C linkage and calling convention.  This
 turns off name mangling so that the Ruby interpreter will be able to
 find the function (remember that Ruby is written in C, not C++).
 
@@ -94,7 +85,7 @@ Defining a class in Rice is easy:
   using namespace Rice;
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Class rb_cTest = define_class("Test");
   }
@@ -109,7 +100,7 @@ wanted to inherit from a different class, we could easily do so:
   using namespace Rice;
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Class rb_cMySocket = define_class("MySocket", rb_cIO);
   }
@@ -153,7 +144,7 @@ Now let's add a method to our class:
   }
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Class rb_cTest =
       define_class("Test")
@@ -185,7 +176,7 @@ We could also add an #initialize method to our class:
   }
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Class rb_cTest =
       define_class("Test")
@@ -230,7 +221,7 @@ section.  To wrap it:
   using namespace Rice;
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Test> rb_cTest =
       define_class<Test>("Test")
@@ -242,11 +233,10 @@ section.  To wrap it:
 This example is similar to the one before, but we use Data_Type<>
 instead of Class and the template version of define_class() instead of
 the non-template version.  This creates a binding in the Rice library
-between the Ruby class Test and the C++ class Test, so that we pass
-member function pointers to define_method() and have conversions be done
-automatically.
+between the Ruby class Test and the C++ class Test such that Rice passes
+member function pointers to define_method().
 
-It's possible to write the conversion functions ourself (as we'll see
+It is possible to write the conversion functions ourself (as we'll see
 below), but Rice does all the dirty work for us.
 
 
@@ -312,7 +302,7 @@ Take another look at the wrapper we wrote for the Test class:
 
 \code
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Test> rb_cTest =
       define_class<Test>("Test")
@@ -393,7 +383,7 @@ If we were to wrap this function:
 
 \code
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Test> rb_cTest =
       define_class<Test>("Test")
@@ -412,13 +402,13 @@ and call it from inside Ruby:
 
 we would get an exception.  Rice will automatically convert any
 C++ exception it catches into a Ruby exception.  But what if we wanted
-to use a custom eror message when we convert the exception, or what if
+to use a custom error message when we convert the exception, or what if
 we wanted to convert to a different type of exception?  We can write
 this:
 
 \code
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Test> rb_cTest =
       define_class<Test>("Test")
@@ -457,7 +447,7 @@ Rice uses a similar class called Jump_Tag to handle symbols thrown by
 Ruby's throw/catch or other non-local jumps from inside the Ruby VM.
 
 
-\subsection builtin Builtin types
+\subsection builtin Builtin Types
 
 You've seen this example:
 
@@ -466,8 +456,8 @@ You've seen this example:
   std::cout << object_id << std::endl;
 \endcode
 
-Rice mimics the Ruby class hierarchy as closely as it can given that C++
-is statically typed.  In fact, the above code also works for Classes:
+Rice mimics the Ruby class hierarchy as closely as it can.
+In fact, the above code also works for Classes:
 
 \code
   Class rb_cTest = define_class<Test>("Test");
@@ -528,7 +518,7 @@ Forunately Rice handles this gracefully:
   };
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Base> rb_cBase =
       define_class<Base>("Base")
@@ -541,8 +531,7 @@ Forunately Rice handles this gracefully:
 The second template parameter to define_class indicates that Derived
 inherits from Base.
 
-Rice does not yet support multiple inheritance, but it is believed that
-this is possible through the use of mixins.
+Rice does not support multiple inheritance.
 
 
 \subsection overloading Overloaded functions
@@ -577,13 +566,11 @@ We can wrap this class by using typedefs:
   }
 \endcode
 
-A future version of Rice may provide a simplified interface for this.
-
 
 \subsection user_defined_conversions User-defined type conversions
 
 Rice provides default conversions for many built-in types.  Sometimes,
-however, the default conversion is not their right conversion.  For
+however, the default conversion is not what is expected.  For
 example, consider a function:
 
 \code
@@ -605,7 +592,7 @@ If we write this:
 
 \code
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     define_global_function("foo", &foo);
   }
@@ -624,7 +611,7 @@ To avoid this problem, it is necessary to write a wrapper function:
   }
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     define_global_function("foo", &wrap_foo);
   }
@@ -633,13 +620,11 @@ To avoid this problem, it is necessary to write a wrapper function:
 Note that the out parameter is returned from wrap_foo, as Ruby does not
 have pass-by-variable-reference (it uses pass-by-object-reference).
 
-Future versions of Rice will have a cleaner way of dealing with this.
-
 
 \subsection 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:
+takes more arguments, one of which has a default value:
 
 \code
   class Test
@@ -651,7 +636,7 @@ take a few arguments for what to return, one which has a default value:
 \endcode
 
 As default parameter information is not available through templates,
-it's necessary to define this in Rice explicitly using Rice::Arg:
+it is necessary to define this in Rice explicitly using Rice::Arg:
 
 \code
   #include "rice/Data_Type.hpp"
@@ -660,7 +645,7 @@ it's necessary to define this in Rice explicitly using Rice::Arg:
   using namespace Rice;
 
   extern "C"
-  void Init_Test()
+  void Init_test()
   {
     Data_Type<Test> rb_cTest =
       define_class<Test>("Test")
@@ -673,16 +658,9 @@ it's necessary to define this in Rice explicitly using Rice::Arg:
 \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 parameters), 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:
+parameter is not important here (a readability tool), but the value set via operator=
+must match the type of the parameter. As such it may be necessary to
+explicitly cast the default value.
 
 \code
   .define_method("hello",
@@ -691,7 +669,10 @@ appropriate types:
   );
 \endcode
 
-With this, Ruby will now know about the default arguments, and this wrapper
+These Rice::Arg objects must be in the correct order and must be
+surrounded with parentheses if more than one exists.
+
+Now, Ruby will now know about the default arguments, and this wrapper
 can be used as expected:
 
 \code
@@ -700,7 +681,7 @@ can be used as expected:
   t.hello("goodnight", "moon")
 \endcode
 
-This will also work with Constructors:
+This also works with Constructors:
 
 \code
   .define_constructor(Constructor<SomeClass, int, int>(),
@@ -710,11 +691,11 @@ This will also work with Constructors:
 \subsection director Director
 
 As polymorphism is the most important tennant of Object Oriented Programming,
-it's important that Rice supports polymorphic calls travelling between C++
+it is 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, coupled with 
-Rice::Data_Type::define_director exposes this functionality cleanly.
+but enabling the other direction requires some extra effort. Rice
+suppplies the the Rice::Director class and
+Rice::Data_Type::define_director to expose this functionality.
 
 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
@@ -730,13 +711,12 @@ the following class:
 \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
+in its 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 will 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 along with a few methods:
+To properly wrap both of these methods, use a Rice::Director subclass as a proxy:
 
 \code
   #include "rice/Director.hpp"
@@ -769,7 +749,7 @@ There is a lot going on here, so we'll go through each part.
   class VirtualBaseProxy : public Virtualbase, public Rice::Director {
 \endcode
 
-First, the class needs to subclass both the virtual class and Rice::Director class.
+First, the class needs to subclass both the virtual class in question and Rice::Director.
 
 \code
     public:
@@ -777,10 +757,9 @@ First, the class needs to subclass both the virtual class and Rice::Director cla
 \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.
+have a handle to the Ruby instance. The constructor
+must take a Rice::Object as the first argument and pass it up into
+Rice::Director. The code here is the minimum required for a Rice::Director proxy.
 
 \code
       virtual int doWork() {
@@ -792,11 +771,12 @@ minimum required for a Rice::Director proxy.
       }
 \endcode
 
-The two methods seen here directly correspond to the two code directions this class
-opens up. The virtual method is this class's hook into C++'s polymorphism. Any calls
-that need to be forwarded into Ruby are done as specified here: get the Ruby object
-for the instance of this class, call Rice::Object::call, and if necessary convert
-the return value from Ruby back into C++ types.
+Here the directory proxy overrides the methods for Ruby exposure and
+implements the required actions to pass flow around the heirarchy
+appropriately. The pattern shown here is that the actual override will
+call down into Ruby, handling any type conversions, while a
+default_methodName method handles calling up into C++ and will be the
+method wrapped into Rice.
 
 The default_doWork method will be used as Rice's hookup of calling back up the 
 heirarchy (wrapping is below). This method needs to do one of two things: call
@@ -810,8 +790,8 @@ processWorker example:
 \endcode
 
 The method raisePureVirtual() exists to allow wrapping a pure virtual method into Ruby
-but making sure any users of this extension are informed quickly that there's nothing
-in the C++ to call for the given method.
+(and ensuring compliation is possible) but making sure any users of this extension are 
+informed quickly that there's nothing callable in the C++ side of the library.
 
 Once the proxy class is built, it's time to wrap it into Ruby:
 
@@ -835,14 +815,14 @@ object construction / destruction of the types in question.
 
 \subsection implicit_cast Implicit Casting
 
-There are times when a library exposes classes that while unrelated are
-built to be interchangeable across the library. One example of this,
-taken from the Open Source 3d rendering engine <a
-href="http://www.ogre3d.org/">OGRE</a>, are the Degree and Radian classes.
+There are times when a library exposes classes that, while unrelated, are
+built to be interchangeable across the library. One example of this is found in
+the Open Source 3d rendering engine <a
+href="http://www.ogre3d.org/">OGRE</a>: Ogre::Degree and Ogre::Radian.
 When a given method takes a Radian, you're free to pass in a Degree, and vice versa. 
 
 Rice cannot automatically figure out if this kind of functionality is
-possible in a given library but it does have a simple API for defining
+possible in a given library but it does provide an API for defining
 these relationships: Rice::define_implicit_cast<From, To>().
 
 \code
@@ -861,12 +841,11 @@ void Init_implicit() {
 }
 \endcode
 
-This support is still being fleshed out and has a few requirements for
-proper use:
+Using Rice::define_implicit_cast has the following requirements:
 
 \li The two types must be bound in Rice before defining the cast.
 \li The classes must have constructors that take the other type.
-\li This feature cannot be used with fundamental types yet.
+\li This feature cannot be used with fundamental types.
 
 To see a full example of this feature, please check out
 test/test_Data_Type.cpp.
@@ -1031,7 +1010,7 @@ to be much more readable than using the Boost preprocessor library.
 
 \section history History
 
-Rice originated as a project to interface with C++-based trading
+Rice originated as Excruby, a project to interface with C++-based trading
 software at Automated Trading Desk in Mount Pleasant, South Carolina.
 The Ruby bindings for Swig were at the time less mature than they are
 today, and did not suit the needs of the project.
@@ -1073,53 +1052,4 @@ clean up the object, the smart pointer will be destroyed, decrementing
 the reference count; when the reference count drops to 0, underlying
 object will be destroyed.
 
-
-\section embedding Embedding
-
-You can embed the Ruby interpter in your application by using the VM
-class:
-
-\code
-  int main(int argc, char * argv[])
-  {
-    Rice::VM vm(argc, argv);
-    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:
-
-\code
-  std::unique_ptr<Rice::VM> vm;
-  Rice::Object obj;
-
-  void some_application_extension_init()
-  {
-    vm.reset(new Rice::VM("some_application"));
-  }
-
-  void some_application_extension_callback()
-  {
-    // Need to initialize the stack here, because we don't know if
-    // we are at the same stack depth as when the VM was initialized
-    vm->init_stack();
-
-    // Now do some work...
-    obj->call("some_callback_function")
-  }
-\endcode
-
-Be aware that initializing the Ruby VM can cause a call to exit() if
-certain command-line options are specified.  This has two implications:
-
-  \li an application that constructs a Ruby VM may terminate
-  unexpectedly if the options passed to the interpreter are not tightly
-  controlled (a security issue), and
-
-  \li an application that constructs a Ruby VM should not have any
-  objects with nontrivial destructors on the stack when the VM is
-  created, otherwise those objects might not get correctly destructed.
-
 vim:ft=cpp:tw=72:ts=2:sw=2:fo=cqrtn:noci:si