rice 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfc3c808fd3b1c836e1788866f93b00cf739ea459b38f3db85304adcec9c3557
-  data.tar.gz: 5b61d235b4f964750929e825bcb18ab9e91fb12b85d8d29f19f8a886e0fdd204
+  metadata.gz: b94a556a35a6622bc3a5e9ca9f124020b0d22fffa319df33e3aa0bb35bae4d56
+  data.tar.gz: bcd79c325fb7cc04396720a8d987d55ba197079743971f012ca71ceeb16de2df
 SHA512:
-  metadata.gz: 0c2e7b10676fece41e12fca65ada008b87ca3faa6148771cf68bf07c75c01618b49d99df4ee8d11c3fd7d0b95d18367fd26923587bedf37ae677fefd090c6c44
-  data.tar.gz: bb1340b89738f90f222cfabf6c5bf9a1496154cf8eea2e607afba793c824fcb2497c2c2b141d11e97eae9e232eff755451b477ec568ecc4d7a98200a94856aaf
+  metadata.gz: a6122026933d06b8866e486fcd954f6e55a148caab22fe95072cbf5ff6937936d2900e0374b6e276fb14c476c1413833cbd05e536757aea13f7ee431ac163a27
+  data.tar.gz: a7202f164e6cf63259bc3d2b8aa90a7306e53f88305f1c558a4ebd6d1d60b22e7eacf8466667b0fd3ce8123002e44a62a3896f9e4ecb69b3b412f09b23bf64af

data/COPYING

@@ -1,5 +1,5 @@
-Copyright (C) 2017 Paul Brannan <pbrannan@atdesk.com>,
-  Jason Roelofs <jasongroelofs@gmail.com>
+Copyright (C) 2020 Jason Roelofs <jasongroelofs@gmail.com>
+  Paul Brannan <curlypaul924@gmail.com>,
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions

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         = 2.1.1
+PROJECT_NUMBER         = 3.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.16.1 from Makefile.am.
+# Makefile.in generated by automake 1.16.3 from Makefile.am.
 # @configure_input@
 
-# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+# Copyright (C) 1994-2020 Free Software Foundation, Inc.
 
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
@@ -119,7 +119,7 @@ build_triplet = @build@
 host_triplet = @host@
 subdir = .
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/check_stdcxx_11.ac \
+am__aclocal_m4_deps = $(top_srcdir)/ax_cxx_compile_stdcxx.m4 \
 	$(top_srcdir)/ruby.ac $(top_srcdir)/doxygen.ac \
 	$(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
@@ -190,7 +190,7 @@ CSCOPE = cscope
 DIST_SUBDIRS = $(SUBDIRS)
 am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/doxygen.am \
 	$(top_srcdir)/rice/detail/ruby_version_code.hpp.in COPYING \
-	TODO config.guess config.sub depcomp install-sh missing
+	config.guess config.sub depcomp install-sh missing
 DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
 distdir = $(PACKAGE)-$(VERSION)
 top_distdir = "$(distdir)"
@@ -229,6 +229,8 @@ am__relativize = \
 DIST_ARCHIVES = "$(distdir)".tar.gz
 GZIP_ENV = --best
 DIST_TARGETS = dist-gzip
+# Exists only to be overridden by the user if desired.
+AM_DISTCHECK_DVI_TARGET = dvi
 distuninstallcheck_listfiles = find . -type f -print
 am__distuninstallcheck_listfiles = $(distuninstallcheck_listfiles) \
   | sed 's|^\./|$(prefix)/|' | grep -v '$(infodir)/dir$$'
@@ -275,7 +277,7 @@ ECHO_C = @ECHO_C@
 ECHO_N = @ECHO_N@
 ECHO_T = @ECHO_T@
 EXEEXT = @EXEEXT@
-HAVE_CXX11 = @HAVE_CXX11@
+HAVE_CXX14 = @HAVE_CXX14@
 INSTALL = @INSTALL@
 INSTALL_DATA = @INSTALL_DATA@
 INSTALL_PROGRAM = @INSTALL_PROGRAM@
@@ -634,6 +636,10 @@ dist-xz: distdir
 	tardir="$(distdir)" && $(am__tar) | XZ_OPT=$${XZ_OPT--e} xz -c >"$(distdir)".tar.xz
 	$(am__post_remove_distdir)
 
+dist-zstd: distdir
+	tardir="$(distdir)" && $(am__tar) | zstd -c $${ZSTD_CLEVEL-$${ZSTD_OPT--19}} >"$(distdir)".tar.zst
+	$(am__post_remove_distdir)
+
 dist-tarZ: distdir
 	@echo WARNING: "Support for distribution archives compressed with" \
 		       "legacy program 'compress' is deprecated." >&2
@@ -676,6 +682,8 @@ distcheck: dist
 	  eval GZIP= gzip $(GZIP_ENV) -dc "$(distdir)".shar.gz | unshar ;;\
 	*.zip*) \
 	  unzip "$(distdir)".zip ;;\
+	*.tar.zst*) \
+	  zstd -dc "$(distdir)".tar.zst | $(am__untar) ;;\
 	esac
 	chmod -R a-w "$(distdir)"
 	chmod u+w "$(distdir)"
@@ -691,7 +699,7 @@ distcheck: dist
 	    $(DISTCHECK_CONFIGURE_FLAGS) \
 	    --srcdir=../.. --prefix="$$dc_install_base" \
 	  && $(MAKE) $(AM_MAKEFLAGS) \
-	  && $(MAKE) $(AM_MAKEFLAGS) dvi \
+	  && $(MAKE) $(AM_MAKEFLAGS) $(AM_DISTCHECK_DVI_TARGET) \
 	  && $(MAKE) $(AM_MAKEFLAGS) check \
 	  && $(MAKE) $(AM_MAKEFLAGS) install \
 	  && $(MAKE) $(AM_MAKEFLAGS) installcheck \
@@ -852,7 +860,7 @@ uninstall-am:
 	am--refresh check check-am clean clean-cscope clean-generic \
 	cscope cscopelist-am ctags ctags-am dist dist-all dist-bzip2 \
 	dist-gzip dist-lzip dist-shar dist-tarZ dist-xz dist-zip \
-	distcheck distclean distclean-generic distclean-tags \
+	dist-zstd distcheck distclean distclean-generic distclean-tags \
 	distcleancheck distdir distuninstallcheck dvi dvi-am html \
 	html-am info info-am install install-am install-data \
 	install-data-am install-dvi install-dvi-am install-exec \

data/README.md

@@ -2,10 +2,10 @@
 
 # Introduction {#intro}
 
-Rice is a C++ interface to Ruby's C API.  It provides a type-safe and
+Rice is a C++ interface to Ruby's C API. It provides a type-safe and
 exception-safe interface in order to make embedding Ruby and writing
-Ruby extensions with C++ easier.  It is similar to Boost.Python in many
-ways, but also attempts to provide an object-oriented interface to all
+Ruby extensions with C++ easier. It is similar to Boost.Python or pybind11
+in many ways, but also attempts to provide an object-oriented interface to all
 of the Ruby C API.
 
 What Rice gives you:
@@ -16,7 +16,7 @@ What Rice gives you:
 
 # Project Details {#project}
 
-The source is hosted on github: http://github.com/jasonroelofs/rice
+The source is hosted on GitHub: http://github.com/jasonroelofs/rice
 
 Bug tracking: http://github.com/jasonroelofs/rice/issues
 
@@ -36,8 +36,9 @@ Building it locally from a clone of the repository is as follows:
   make
 ~~~
 
-Rice is known to work on *nix and OSX. Windows is not currently
-supported.
+Rice is known to work on *nix, OSX, and Windows.
+
+Rice requires a C++ compiler with support for C++14 or later.
 
 # Tutorial {#tutorial}
 
@@ -53,7 +54,7 @@ The first step is to create an extconf.rb file:
   create_makefile('test')
 ~~~
 
-Note that we use `mkmf-rice` instead of `mkmf`.  This will ensure that the
+Note that we use `mkmf-rice` instead of `mkmf`. This will ensure that the
 extension will be linked with standard C++ library along with the Rice
 library, and allow access to the Rice header files.
 
@@ -66,19 +67,19 @@ Next we create our extension and save it to test.cpp:
   }
 ~~~
 
-Note the extern "C" line above.  This tells the compiler that the
-function `Init_test` should have C linkage and calling convention.  This
+Note the extern "C" line above. This tells the compiler that the
+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++).
 
 So far we haven't put anything into the extension, so it isn't
-particularly useful.  The next step is to define a class so we can add
+particularly useful. The next step is to define a class so we can add
 methods to it.
 
 
 ## Defining clases {#classes}
 
-Defining a class in Rice is easy:
+Defining a class in Rice is a single call:
 
 ~~~{.cpp}
   #include "rice/Class.hpp"
@@ -93,7 +94,7 @@ Defining a class in Rice is easy:
 ~~~
 
 This will create a class called `Test` that inherits from `Object`. If we
-wanted to inherit from a different class, we could easily do so:
+wanted to inherit from a different class, we do so with the second parameter:
 
 ~~~{.cpp}
   #include "rice/Class.hpp"
@@ -153,8 +154,8 @@ Now let's add a method to our class:
   }
 ~~~
 
-Here we add a method `%Test#hello` that simply returns the string
-"Hello, World".  The method takes self as an implicit parameter, but
+Here we add a method `%Test#hello` that returns the string
+"Hello, World". The method takes self as an implicit parameter, but
 isn't used, so we comment it out to prevent a compiler warning.
 
 We could also add an `#initialize` method to our class:
@@ -190,8 +191,8 @@ The `initialize` method sets an instance variable `@foo` to the value 42.
 The number is automatically converted to a `Fixnum` before doing the
 assignment.
 
-Note that we're chaining calls on the `Class` object.  Most member
-functions in `Module` and `Class` return a reference to self, so we can
+Note that we're chaining calls on the `Class` object. Most member
+functions in `Module` and `Class` return a reference to `self`, so we can
 chain as many calls as we want to define as many methods as we want.
 
 
@@ -276,8 +277,8 @@ Ruby types:
   Object to_ruby(T const & x);
 ~~~
 
-Rice has included by default specializations for many of the builtin
-types. To define your own conversion, you can write a specialization:
+Rice includes default specializations for many of the builtin
+types. To define your own conversion, write a template specialization:
 
 ~~~{.cpp}
   template<>
@@ -325,8 +326,8 @@ calls:
 works as expected.
 
 The `Data_Object` class is a wrapper for the `Data_Wrap_Struct` and the
-`Data_Get_Struct` macros in C extensions.  It can be used to wrap or
-unwrap any class that has been assigned to a `Data_Type`.  It inherits
+`Data_Get_Struct` macros in C extensions. It can be used to wrap or
+unwrap any class that has been assigned to a `Data_Type`. It inherits
 from `Object`, so any member functions we can call on an `Object` we can
 also call on a `Data_Object`:
 
@@ -401,11 +402,11 @@ and call it from inside Ruby:
   test.error()
 ~~~
 
-we would get an exception.  Rice will automatically convert any
-C++ exception it catches into a Ruby exception.  But what if we wanted
+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 error message when we convert the exception, or what if
-we wanted to convert to a different type of exception?  We can write
-this:
+we wanted to convert to a different type of exception? We can write
+an exception handler like so:
 
 ~~~{.cpp}
   extern "C"
@@ -430,7 +431,7 @@ The `handle_my_exception` function need only rethrow the exception as a
   }
 ~~~
 
-And what if we want to call Ruby code from C++?  These exceptions are
+And what if we want to call Ruby code from C++? These exceptions are
 also converted:
 
 ~~~{.cpp}
@@ -441,7 +442,7 @@ also converted:
 ~~~
 
 Internally whenever Rice catches a C++ or a Ruby exception, it converts
-it to an `Exception` object.  This object will later be re-raised as a
+it to an `Exception` object. This object will later be re-raised as a
 Ruby exception when control is returned to the Ruby VM.
 
 Rice uses a similar class called `Jump_Tag` to handle symbols thrown by
@@ -504,7 +505,7 @@ wrapper functions for base classes typically don't know how to accept
 pointers to derived classes. It is possible to write this logic, but
 the code is nontrivial.
 
-Forunately Rice handles this gracefully:
+Rice also provides a solution to this problem:
 
 ~~~{.cpp}
   class Base
@@ -538,7 +539,7 @@ Rice does not support multiple inheritance.
 ## Overloaded functions {#overloading}
 
 If you try to create a member function pointer to an overloaded
-function, you will get an error.  So how do we wrap classes that have
+function, you will get an error. So how do we wrap classes that have
 overloaded functions?
 
 Consider a class that uses this idiom for accessors:
@@ -584,8 +585,8 @@ array of char?
 
 Because the second case is the most common use case (a pointer to the
 first character of a C string), Rice provides a default conversion that
-treats a `char *` as a C string.  But suppose the above function takes a
-pointer to a char instead?
+treats a `char *` as a C string. But suppose the above function actually
+expects to receive a pointer to a single char instead?
 
 If we write this:
 
@@ -599,7 +600,8 @@ If we write this:
 
 It will likely have the wrong behavior.
 
-To avoid this problem, it is necessary to write a wrapper function:
+To avoid this problem, it is necessary to write a wrapper function where
+the extension can be more explicit about how to handle the parameters:
 
 ~~~{.cpp}
   Object wrap_foo(Object o)
@@ -656,8 +658,8 @@ it is necessary to define this in Rice explicitly using `Rice::Arg`:
   }
 ~~~
 
-The syntax here is simply `Arg(nameOfParameter)[ = defaultValue]`.  The name of the
-parameter is not important here (a readability tool), but the value set via `operator=`
+The syntax here is `Arg(nameOfParameter)[ = defaultValue]`. The name of the
+parameter is not important here (it is for readability), 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.
 
@@ -689,12 +691,12 @@ This also works with Constructors:
 
 ## Director {#director}
 
-As polymorphism is the most important tennant of Object Oriented Programming,
-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 effort. Rice
-supplies the the `Rice::Director` class and
-`Rice::Data_Type::define_director` to expose this functionality.
+Polymorphism creates yet another wrinkle in building exceptions around C++ code,
+because now we have to deal with cross-language polymorphism, where C++ can call
+into a Ruby subclass, and a Ruby subclass can `super` back into C++ land. `super`
+calls already work through define_class, but making code travel from C++ into Ruby
+via polymorphism is tricker. Rice provides the `Rice::Director` class and the
+`define_director` method to enable this code path.
 
 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 hierarchy for that class. Take
@@ -709,13 +711,13 @@ the following class:
   };
 ~~~
 
-Due to the abstract nature of this class, it will not work at all with Rice
-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.
+Due to the abstract nature of this class, we cannot directly wrap it in Rice, as
+any C++ compiler will complain about trying to instantiate a virtual class.
+Even without the pure virtual function, any call to `VirtualBase::doWork` will stop
+at the C++ level and execution will not pass down into any Ruby subclasses.
 
-To properly wrap both of these methods, use a `Rice::Director` subclass as a proxy:
+To properly wrap both of these methods, use a `Rice::Director` subclass as a proxy
+and use this new proxy class as the type to wrap with `define_class`:
 
 ~~~{.cpp}
   #include "rice/Director.hpp"
@@ -756,7 +758,7 @@ First, the class needs to subclass both the virtual class in question and `Rice:
 ~~~
 
 For `Rice::Director` to work its magic, every instance of this class needs to
-have a handle to the Ruby instance. The constructor
+have a handle to its 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.
 
@@ -770,17 +772,13 @@ must take a `Rice::Object` as the first argument and pass it up into
       }
 ~~~
 
-Here the directory proxy overrides the methods for Ruby exposure and
-implements the required actions to pass flow around the hierarchy
-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
-hierarchy (wrapping is below). This method needs to do one of two things: call
-up the class hierarchy, as seen here, or call `raisePureVirtual()` as seen in the
-processWorker example:
+Here the proxy class implements the virtual methods and provides implementations
+that delegate execution in the correct direction. The actual method calls into Ruby,
+providing all necessary type conversions to and from C++ types. The other method
+is how Ruby calls back into C++ and is the method that must be exposed with
+`define_method`. The `default_` prefix is a naming convention to help keep straight
+which methods perform which function. If Ruby should never call into C++, then the
+`default_` implementation should call `raisePureVirtual()`:
 
 ~~~{.cpp}
       int default_processWorker() {
@@ -807,7 +805,7 @@ void Init_virtual() {
 
 The wrapping is the same as is described earlier in this document. Expose the class
 `VirtualBase`, and register `VirtualBaseProxy` as a director proxy of `VirtualBase` with
-`Rice::Data_Type::define_director`, then `define methods` pointing to the proxy object as necessary.
+`Rice::Data_Type::define_director`, then `define_method`s pointing to the proxy methods as necessary.
 
 You must use the `Rice::Director` proxy class in the Constructor line, this allows proper
 object construction / destruction of the types in question.
@@ -854,63 +852,63 @@ test/test_Data_Type.cpp.
 There are a number of common problems when writing C or C++ extensions
 for Ruby:
 
-- Type safety.  It is easy to mix-up integral types such as ID and
-VALUE.  Some of the functions in the Ruby API are not consistent with
+- Type safety. It is easy to mix-up integral types such as ID and
+VALUE. Some of the functions in the Ruby API are not consistent with
 which types they take (e.g. rb_const_defined takes an ID and
 rb_mod_remove_const takes a Symbol).
 
-- DRY principle.  Specifying the number of arguments that each wrapped
-function takes is easy to get wrong.  Adding a new argument to the
+- DRY principle. Specifying the number of arguments that each wrapped
+function takes is easy to get wrong. Adding a new argument to the
 function means that the number of arguments passed to rb_define_method
 must also be updated.
 
-- Type conversion.  There are many different functions to convert data
-to and from ruby types.  Many of them have different semantics or
-different forms.  For example, to convert a string, one might use the
+- Type conversion. There are many different functions to convert data
+to and from ruby types. Many of them have different semantics or
+different forms. For example, to convert a string, one might use the
 StringValue macro, but to convert a fixnum, one might use FIX2INT.
 Unwrapping previously wrapped C data uses yet another form.
 
-- Exception safety.  It is imperative that C++ exceptions never make
+- Exception safety. It is imperative that C++ exceptions never make
 their way into C code, and it is also imperative that a Ruby exception
 never escape while there are objects on the stack with nontrivial
-destructors.  Rules for when it is okay to use which exceptions are
+destructors. Rules for when it is okay to use which exceptions are
 difficult to get right, especially as code is maintained through time.
 
-- Thread safety.  Because the Ruby interpreter is not threads-safe,
+- Thread safety. Because the Ruby interpreter is not thread-safe,
 the Ruby interpreter must not be run from more than one thread.
 Because of tricks the GC and scheduler play with the C stack, it's not
 enough to ensure that only one thread runs the interpreter at any
 given time; once the interpreter has been run from one thread, it must
-only ever be run from that thread in the future.  Additionally,
+only ever be run from that thread in the future. Additionally,
 because Ruby copies the stack when it switches threads, C++ code must
 be careful not to access objects in one Ruby thread that were created
 on the stack in another Ruby thread.
 
-- C-based API.  The Ruby API is not always convenient for accessing
+- C-based API. The Ruby API is not always convenient for accessing
 Ruby data structurs such as Hash and Array, especially when writing C++
 code, as the interface for these containers is not consistent with
 standard containers.
 
-- Calling convention.  Function pointers passed into the Ruby API must
-follow the C calling convention.  This means that it is not possible to
+- Calling convention. Function pointers passed into the Ruby API must
+follow the C calling convention. This means that it is not possible to
 pass a pointer to a template function or static member function (that
 is, it will work on some platforms, but isn't portable).
 
-- Inheritance.  When wrapping C++ objects, it is easy to store a
+- Inheritance. When wrapping C++ objects, it is easy to store a
 pointer to a derived class, but then methods in the base class must have
-knowledge of the derived class in order to unwrap the object.  It is
+knowledge of the derived class in order to unwrap the object. It is
 possible to always store a pointer to the base class and then
 dynamic_cast the pointer to the derived type when necessary, but this
 can be slow and cumbersome, and it isn't likely to work with multiple
-inheritance.  A system that properly handles inheritance for all corner
+inheritance. A system that properly handles inheritance for all corner
 cases is nontrivial.
 
-- Multiple inheritance.  C++ supports true multiple inheritance, but
-the Ruby object model uses single inheritance with mixins.  When
+- Multiple inheritance. C++ supports true multiple inheritance, but
+the Ruby object model uses single inheritance with mixins. When
 wrapping a library whose public interface uses multiple inheritance,
 care must be taken in constructing the mapping.
 
-- GC safety.  All live Ruby objects must be marked during the garbage
+- GC safety. All live Ruby objects must be marked during the garbage
 collector's mark phase, otherwise they will be prematurely destroyed.
 The general rule is that object references stored on the heap should be
 either registered with rb_gc_register_address or marked by a data
@@ -918,92 +916,92 @@ object's mark function; object references stored on the stack will be
 automatically marked, provided the Ruby interpreter was properly
 initialized at startup.
 
-- Callbacks.  C implements callbacks via function pointers, while ruby
-typically implements callbacks via procs.  Writing an adapter function
+- Callbacks. C implements callbacks via function pointers, while Ruby
+typically implements callbacks via procs. Writing an adapter function
 to call the proc is not difficult, but there is much opportunity for
 error (particularly with exception-safety).
 
-- Data serialization.  By default data objects defined at the C layer
-are not marshalable.  The user must explicitly define functions to
+- Data serialization. By default data objects defined at the C layer
+are not marshalable. The user must explicitly define functions to
 marshal the data member-by-member.
 
 Rice addresses these issues in many ways:
 
-- Type safety.  Rice provides encapsulation for all builtin types,
-such as Object, Identifier, Class, Module, and String.  It
+- Type safety. Rice provides encapsulation for all builtin types,
+such as Object, Identifier, Class, Module, and String. It
 automatically checks the dynamic type of an object before constructing
 an instance of a wrapper.
 
-- DRY principle.  Rice uses introspection through the use of templates
+- DRY principle. Rice uses introspection through the use of templates
 and function overloading to automatically determine the number and types
-of arguments to functions.  Default arguments must still be handled
+of arguments to functions. Default arguments must still be handled
 explicitly, however.
 
-- Type conversions.  Rice provides cast-style to_ruby<> and
+- Type conversions. Rice provides cast-style to_ruby<> and
 from_ruby<> template functions to simplify explicit type conversions.
 Automatic type conversions for parameters and return values are
 generated for all wrapped functions.
 
-- Exception safety.  Rice automatically converts common exceptions and
-provides a mechanism for converting user-defined exception types.  Rice
+- Exception safety. Rice automatically converts common exceptions and
+provides a mechanism for converting user-defined exception types. Rice
 also provides convenience functions for converting exceptions when
 calling back into ruby code.
 
-- Thread safety.  Rice provides no mechanisms for dealing with thread
-safety.  Many common thread safety issues should be alleviated by YARV,
+- Thread safety. Rice provides no mechanisms for dealing with thread
+safety. Many common thread safety issues should be alleviated by YARV,
 which supports POSIX threads.
 
-- C++-based API.  Rice provides an object-oriented C++-style API to
+- C++-based API. Rice provides an object-oriented C++-style API to
 most common functions in the Ruby C API.
 
-- Calling convention.  Rice automatically uses C calling convention
+- Calling convention. Rice automatically uses C calling convention
 for all function pointers passed into the Ruby API.
 
-- Inheritance.  Rice provides automatic conversion to the base class
+- Inheritance. Rice provides automatic conversion to the base class
 type when a wrapped member function is called on the base class.
 
-- Multiple inheritance.  Rice provides no mechanism for multiple
-inheritance.  Multiple inheritance can be simulated via mixins, though
+- Multiple inheritance. Rice provides no mechanism for multiple
+inheritance. Multiple inheritance can be simulated via mixins, though
 this is not yet as easy as it could be.
 
-- GC safety.  Rice provides a handful of convenience classes for
-interacting with the garbage collector.  There are still basic rules
+- GC safety. Rice provides a handful of convenience classes for
+interacting with the garbage collector. There are still basic rules
 which must be followed to ensure that objects get properly destroyed.
 
-- Callbacks.  Rice provides a handful of convenience classes for
+- Callbacks. Rice provides a handful of convenience classes for
 dealing with callbacks.
 
-- Data serialization.  Rice provides no mechanism for data
+- Data serialization. Rice provides no mechanism for data
 serialization, but it is likely this may be added in a future release.
 
 
 # What Rice is Not {#what_not}
 
-There are a number projects which server similar functions to Rice.  Two
-such popular projects are SWIG and Boost.Python.  Rice has some
+There are a number projects which server similar functions to Rice. Two
+such popular projects are SWIG and Boost.Python. Rice has some
 distinct features which set it apart from both of these projects.
 
-Rice is not trying to replace SWIG.  Rice is not a generic wrapper
-interface generator.  Rice is a C++ library for interfacing with the
-Ruby C API.  This provides a very natural way for C++ programmers to
+Rice is not trying to replace SWIG. Rice is not a generic wrapper
+interface generator. Rice is a C++ library for interfacing with the
+Ruby C API. This provides a very natural way for C++ programmers to
 wrap their C++ code, without having to learn a new domain-specific
-language.  However, there is no reason why SWIG and Rice could not work
-together; a SWIG module could be written to generate Rice code.  Such a
+language. However, there is no reason why SWIG and Rice could not work
+together; a SWIG module could be written to generate Rice code. Such a
 module would combine the portability of SWIG with the maintainability of
 Rice (I have written extensions using both, and I have found Rice
 extensions to be more maintainable when the interface is constantly
-changing.  Your mileage may vary).
+changing. Your mileage may vary).
 
 Rice is also not trying to simply be a Ruby version of Boost.Python.
 Rice does use some of the same template tricks that Boost.Python uses,
-however there are some important distinctions.  First of all,
+however there are some important distinctions. First of all,
 Boost.Python attempts to create a declarative DSL in C++ using
-templates.  Rice is a wrapper around the Ruby C API and attempts to make
+templates. Rice is a wrapper around the Ruby C API and attempts to make
 its interface look like an OO version of the API; this means that class
-declarations look procedural rather than declarative.  Secondly, the
-Ruby object model is different from the python object model.  This is
+declarations look procedural rather than declarative. Secondly, the
+Ruby object model is different from the python object model. This is
 reflected in the interface to Rice; it mimics the Ruby object model at
-the C++ level.  Thirdly, Rice uses Ruby as a code generator; I find this
+the C++ level. Thirdly, Rice uses Ruby as a code generator; I find this
 to be much more readable than using the Boost preprocessor library.
 
 
@@ -1016,7 +1014,7 @@ today, and did not suit the needs of the project.
 
 Excruby was written not as a wrapper for the Ruby API, but rather as a
 set of helper functions and classes for interfacing with the Ruby
-interpreter in an exception-safe manner.  Over the course of five years,
+interpreter in an exception-safe manner. Over the course of five years,
 the project grew into wrappers for pieces of the API, but the original
 helper functions remained as part of the public interface.
 
@@ -1025,7 +1023,7 @@ multiple ways of accomplishing most tasks -- directly through the C API,
 through a low-level wrapper around the C API, and through a high-level
 abstraction of the lower-level interfaces.
 
-Rice was then born in an attempt to clean up the interface.  Rice keeps
+Rice was then born in an attempt to clean up the interface. Rice keeps
 the lower-level wrappers, but as an implementation detail; the public
 interface is truly a high-level abstraction around the Ruby C API.
 
@@ -1044,9 +1042,9 @@ collector.
 
 - If a reference counted object is being wrapped, or if another type
 of smart pointer is wrapped, ensure that only one mechanism is used to
-destroy the object.  In general, the smart pointer manages the
+destroy the object. In general, the smart pointer manages the
 allocation of the object, and Ruby should hold only a reference to the
-smart pointer.  When the garbage collector determines that it is time to
+smart pointer. When the garbage collector determines that it is time to
 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.