rice 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b94a556a35a6622bc3a5e9ca9f124020b0d22fffa319df33e3aa0bb35bae4d56
-  data.tar.gz: bcd79c325fb7cc04396720a8d987d55ba197079743971f012ca71ceeb16de2df
+  metadata.gz: d56aeba2a339abc203b192244a3acc552a28aeeba1f87b6a49da38d257ef54bb
+  data.tar.gz: 73fc9c71575f1773080fc77951802c3afd6adbceac3f73357a9741fc87d8ff03
 SHA512:
-  metadata.gz: a6122026933d06b8866e486fcd954f6e55a148caab22fe95072cbf5ff6937936d2900e0374b6e276fb14c476c1413833cbd05e536757aea13f7ee431ac163a27
-  data.tar.gz: a7202f164e6cf63259bc3d2b8aa90a7306e53f88305f1c558a4ebd6d1d60b22e7eacf8466667b0fd3ce8123002e44a62a3896f9e4ecb69b3b412f09b23bf64af
+  metadata.gz: e3adf97953881b6047ee1bd55f1e3dcb42dbcf2d8d431813355949d41937742a4a3574e317db304c3fe6bfbda766f8a29ecb098cff43e9e7e46c48214ab92d53
+  data.tar.gz: ff3917608dd7abdca6430554c99a78b7166abdde8d808778c455ddc12de974af0fbeb3702cdfa7a02830386978e39f507b4506d4cdba4ad865da9e28f980237e

data/CHANGELOG.md

@@ -0,0 +1,121 @@
+## 4.0
+
+Rice 4.0 is a significant change from 3.0 and has multiple backwards-incompatible
+changes. Rice 4.0 no longer requires pre-compilation and is now a header-only library,
+delivered as a combined header file.
+
+For migrating from 3 to 4, see [the migration guide](https://jasonroelofs.com/rice/4.x/migration.html).
+
+There are a ton of changes, but some of the most important ones:
+
+* Header only! `#include <rice/rice.hpp>`
+* Requires C++17 or later
+* Brand new, expanded documentation
+* [Built-in STL support](https://jasonroelofs.com/rice/4.x/stl/stl.html)
+* And so much more. See the documentation for more details.
+
+## 3.0
+
+* Now requires a compiler supporting for C++14 or later
+* Drop support for Ruby 2.4. Supported versions are now 2.5 through 3.0.
+* Fix build issue on macOS Big Sur
+* Fix a data corruption issue with `Rice::Exception::what`.
+* Move CI from Travis to GitHub Actions. Now also able to verify Windows builds!
+
+## 2.2.0
+
+* Deprecate support for Rubies older than 2.4
+* Provide a few more built-in to_ruby/from_ruby conversions
+* Fix compilation error when building under Ruby 2.7.0
+
+## 2.1.3
+
+* Don't lock down HAVE_CXX11 on the Rice build itself.
+
+## 2.1.2
+
+* Fix defining custom `begin` and `end` methods on an `Iterator`
+
+## 2.1.1
+
+* Support Ruby 2.4
+* Re-enable Rice::Enum#hash to support putting Enums in Hashes
+
+## 2.1.0
+
+* Fix compliation issues related to g++ and Ruby 2.3.0
+  To do this, I had to remove Array::to_c_array which was exposing the internals of a
+	Ruby RArray type to the system. This is not something that we should support going forward
+	as these internals are going to change.
+
+# 2.0.0
+
+* Deprecated all versions of Ruby < 2.0
+* Removed Rice::VM.
+  Unsure if this class is even used anywhere and it felt strange to be
+  able to load up a Ruby interpreter inside of Ruby. If you need it, it's
+  two files that I can easily make available in a gist.
+* Improve build process across architectures and future changes.
+  Included some extra warnings for XCode updates on Mac OS X.
+* Confirmed that Rice definitely does not work on static Ruby builds,
+  but that seems to be more because newer Ruby versions don't have good static builds.
+  Thanks to @Kagetsuki for his help tracking down what's going on here.
+
+## 1.7.0
+
+* Ruby 2.2 support
+  Potential breaking changes. Ruby 2.2 removed RHash as a public accessible struct
+  and as such I changed all of the Builtin_Objects to work directly off of RObject
+  instead of the specifics (RArray, RStruct, RString, etc). If you've been using these
+  objects directly I recommend using either the Rice API or Ruby's CAPI instead for
+  future compatibility.
+
+## 1.6.3
+
+* Fix complication issue on some 64-bit *nix systems
+
+## 1.6.2
+
+* Oops! Missed new file in the gemspec
+
+## 1.6.1
+
+* Support C++x11 uniqe_ptr over auto_ptr
+* Fix some warnings
+
+## 1.6.0
+
+* Ruby 2.1 support -- Thanks Chai Zhenhua
+* Methods and Constructors have correct method access specifiers [#57]
+* Clean up some 64-bit compiler warnings
+
+## 1.5.3
+
+* Fix signed / unsigned compiler warning with Hash#each
+* Fix compilation on clang 5 (Xcode 5)
+
+## 1.5.2
+
+* Update build system to remove deprecation warnings and allow easier building
+* Fix String to work as a parameter in a wrapped method (#59)
+* Update documentation a bit
+
+## 1.5.1
+
+* Doc string fix
+
+## 1.5.0
+
+* Ruby 2.0 compatability
+* Bug fixes
+
+## 1.4.3
+
+* Various build configuration fixes
+
+## 1.4.0
+
+* Fully compatible with Ruby 1.9.2
+* Constructor supports default arguments
+* Ability to define implicit casting through define_implicit_cast
+* Fixed a few memory-related issues

data/CONTRIBUTORS.md

@@ -0,0 +1,19 @@
+Contributors
+============
+
+I'd like to thank the following people for their help in making Rice what it is today.
+
+* [Paul Brannon (cout)](https://github.com/cout) for initially building and releasing this library as open source.
+* [Sylvain Joyeux (doudou)](https://github.com/doudou) for [PR #23](https://github.com/jasonroelofs/rice/pull/23) and [PR #68](https://github.com/jasonroelofs/rice/pull/68)
+* [Pat McNally (patmcnally)](https://github.com/patmcnally) for [PR #38](https://github.com/jasonroelofs/rice/pull/38)
+* [Victor Costan (pwnall)](https://github.com/pwnall) for [PR #54](https://github.com/jasonroelofs/rice/pull/54)
+* [Zachary Salzbank (zsalzbank)](https://github.com/zsalzbank) for [PR #55](https://github.com/jasonroelofs/rice/pull/55)
+* [Chai Zhenhua (chaizhenhua)](https://github.com/jasonroelofs/rice/pull/58) for [PR #58](https://github.com/jasonroelofs/rice/pull/58)
+* [Alexander Rüedlinger (lexruee)](https://github.com/lexruee) for [PR #81](https://github.com/jasonroelofs/rice/pull/81)
+* [ryannevell](https://github.com/ryannevell) for [PR #98](https://github.com/jasonroelofs/rice/pull/98)
+* [Samu Voutilainen (smarre)](https://github.com/Smarre) for [PR #102](https://github.com/jasonroelofs/rice/pull/102)
+* [Harald Sitter (apachelogger)](https://github.com/apachelogger) for [PR #104](https://github.com/jasonroelofs/rice/pull/104)
+* [nobu](https://github.com/nobu) for [PR #122](https://github.com/jasonroelofs/rice/pull/122)
+* [Charlie Savage (cfis)](https://github.com/cfis) for multiple improvements and modernizations: [#130](https://github.com/jasonroelofs/rice/pull/130), [#131](https://github.com/jasonroelofs/rice/pull/131), [#133](https://github.com/jasonroelofs/rice/pull/133), [#134](https://github.com/jasonroelofs/rice/pull/134), [#136](https://github.com/jasonroelofs/rice/pull/136), [#137](https://github.com/jasonroelofs/rice/pull/137), [#140](https://github.com/jasonroelofs/rice/pull/140), [#141](https://github.com/jasonroelofs/rice/pull/141) and many others, including the work to make Rice header-only.
+* [Atsushi Tatsuma (yoshoku)](https://github.com/yoshoku) for [#135](https://github.com/jasonroelofs/rice/pull/135)
+* [Andrew Kane (ankane)](https://github.com/ankane) for helping [test Rice 4](https://github.com/jasonroelofs/rice/issues/149).

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -1,20 +1,32 @@
-# Rice - Ruby Interface for C++ Extensions {#mainpage}
+# Rice - Ruby Interface for C++ Extensions
 
-# Introduction {#intro}
+# Introduction
 
-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 or pybind11
-in many ways, but also attempts to provide an object-oriented interface to all
-of the Ruby C API.
+Rice is a C++ header-only library that serves dual purposes. First, it makes it much
+easier to create Ruby bindings for existing C++ libraries. Second, it provides an
+object oriented interface to Ruby's C API that makes it easy to embed Ruby and write
+Ruby extensions in C++.
+
+Rice is similar to Boost.Python and pybind11 in that it minimizes boilerplate code needed
+to interface with C++. It does this by automatically determining type information allowing
+Ruby object to be converted to C++ and vice versa.
 
 What Rice gives you:
 - A simple C++-based syntax for wrapping and defining classes
-- Automatic conversion of exceptions between C++ and Ruby
+- Automatic type conversions between C++ and Ruby
+- Automatic exception conversions between C++ and Ruby
 - Smart pointers for handling garbage collection
 - Wrappers for most builtin types to simplify calling code
 
-# Project Details {#project}
+# Version Differences 3.x vs 4.x and later
+
+This documentation and the `master` branch are for Rice 4.x and later, which is the
+header-only version of this library. Use the `3.x` branch for the docs and code for that
+line of releases.
+
+The docs for the 3.x line of Rice is at https://jasonroelofs.com/rice/3.x.
+
+# Project Details
 
 The source is hosted on GitHub: http://github.com/jasonroelofs/rice
 
@@ -22,1029 +34,36 @@ Bug tracking: http://github.com/jasonroelofs/rice/issues
 
 API documentation: http://jasonroelofs.github.io/rice
 
-# Installation {#installation}
+# Installation
 
-~~~
+```bash
   gem install rice
-~~~
-
-Building it locally from a clone of the repository is as follows:
-
-~~~
-  ./bootstrap
-  ruby extconf.rb
-  make
-~~~
-
-Rice is known to work on *nix, OSX, and Windows.
-
-Rice requires a C++ compiler with support for C++14 or later.
-
-# Tutorial {#tutorial}
-
-## Getting started {#getting_started}
-
-Writing an extension with Rice is very similar to writing an extension
-with the C API.
-
-The first step is to create an extconf.rb file:
-
-~~~{.cpp}
-  require 'mkmf-rice'
-  create_makefile('test')
-~~~
-
-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.
-
-Next we create our extension and save it to test.cpp:
-
-~~~{.cpp}
-  extern "C"
-  void Init_test()
-  {
-  }
-~~~
-
-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
-methods to it.
-
-
-## Defining clases {#classes}
-
-Defining a class in Rice is a single call:
-
-~~~{.cpp}
-  #include "rice/Class.hpp"
-
-  using namespace Rice;
-
-  extern "C"
-  void Init_test()
-  {
-    Class rb_cTest = define_class("Test");
-  }
-~~~
-
-This will create a class called `Test` that inherits from `Object`. If we
-wanted to inherit from a different class, we do so with the second parameter:
-
-~~~{.cpp}
-  #include "rice/Class.hpp"
-
-  using namespace Rice;
-
-  extern "C"
-  void Init_test()
-  {
-    Class rb_cMySocket = define_class("MySocket", rb_cIO);
-  }
-~~~
-
-Note the prefix rb_c on the name of the class. This is a convention
-that the Ruby interpreter and many extensions tend to use. It signifies
-that this is a class and not some other type of object. Some other
-naming conventions that are commonly used:
-
-- rb_c variable name prefix for a Class
-- rb_m variable name prefix for a Module
-- rb_e variable name prefix for an Exception type
-- rb_  function prefix for a function in the Ruby C API
-- rb_f_ function prefix to differentiate between an API function that
-takes Ruby objects as arguments and one that takes C argument types
-- rb_*_s_ indicates the function is a singleton function
-- *_m suffix to indicate the function takes variable number of
-arguments
-
-
-Also note that we don't include "ruby.h" directly. Rice has a wrapper
-for ruby.h that handles some compatibility issues across platforms and
-Ruby versions. Always include Rice headers before including anything
-that might include "ruby.h".
-
-## Defining methods {#methods}
-
-Now let's add a method to our class:
-
-~~~{.cpp}
-  #include "rice/Class.hpp"
-  #include "rice/String.hpp"
-
-  using namespace Rice;
-
-  Object test_hello(Object /* self */)
-  {
-    String str("hello, world");
-    return str;
-  }
-
-  extern "C"
-  void Init_test()
-  {
-    Class rb_cTest =
-      define_class("Test")
-      .define_method("hello", &test_hello);
-  }
-~~~
-
-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:
-
-~~~{.cpp}
-  #include "rice/Class.hpp"
-  #include "rice/String.hpp"
-
-  using namespace Rice;
-
-  Object test_initialize(Object self)
-  {
-    self.iv_set("@foo", 42);
-  }
-
-  Object test_hello(Object /* self */)
-  {
-    String str("hello, world");
-    return str;
-  }
-
-  extern "C"
-  void Init_test()
-  {
-    Class rb_cTest =
-      define_class("Test")
-      .define_method("initialize", &test_initialize)
-      .define_method("hello", &test_hello);
-  }
-~~~
-
-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
-chain as many calls as we want to define as many methods as we want.
-
-
-## Wrapping C++ Types {#data_types}
-
-It's useful to be able to define Ruby classes in a C++ style rather than
-using the Ruby API directly, but the real power Rice is in wrapping
-already-defined C++ types.
-
-Let's assume we have the following C++ class that we want to wrap:
-
-~~~{.cpp}
-  class Test
-  {
-  public:
-    Test();
-    std::string hello();
-  };
-~~~
-
-This is a C++ version of the Ruby class we just created in the previous
-section. To wrap it:
-
-~~~{.cpp}
-  #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);
-  }
-~~~
-
-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 such that Rice passes
-member function pointers to `define_method()`.
-
-It is possible to write the conversion functions ourself (as we'll see
-below), but Rice does all the dirty work for us.
-
-
-## Type conversions {#conversions}
-
-Let's look again at our example class:
-
-~~~{.cpp}
-  class Test
-  {
-  public:
-    Test();
-    std::string hello();
-  };
-~~~
-
-When we wrote our class, we never wrote a single line of code to convert
-the `std::string` returned by `hello()` into a Ruby type. Neverthless, the
-conversion works, and when we write:
-
-~~~{.cpp}
-  test = Test.new
-  puts test.hello
-~~~
-
-We get the expected result.
-
-Rice has two template conversion functions to convert between C++ and
-Ruby types:
-
-~~~{.cpp}
-  template<typename T>
-  T from_ruby(Object x);
-
-  template<typename T>
-  Object to_ruby(T const & x);
-~~~
-
-Rice includes default specializations for many of the builtin
-types. To define your own conversion, write a template specialization:
-
-~~~{.cpp}
-  template<>
-  Foo from_ruby<Foo>(Object x)
-  {
-    // ...
-  }
-
-  template<>
-  Object to_ruby<Foo>(Foo const & x)
-  {
-    // ...
-  }
-~~~
-
-The implementation of these functions would, of course, depend on the
-implementation of `Foo`.
-
-
-## Conversions for wrapped C++ types {#data_conversions}
-
-Take another look at the wrapper we wrote for the `Test` class:
-
-~~~{.cpp}
-  extern "C"
-  void Init_test()
-  {
-    Data_Type<Test> rb_cTest =
-      define_class<Test>("Test")
-      .define_constructor(Constructor<Test>())
-      .define_method("hello", &Test::hello);
-  }
-~~~
-
-When we called `define_class<Test>`, it created a Class for us and
-automatically registered the new Class with the type system, so that the
-calls:
-
-~~~{.cpp}
-  Data_Object<Foo> obj(new Foo);
-  Foo * f = from_ruby<Foo *>(obj);
-  Foo const * f = from_ruby<Foo const *>(obj);
-~~~
-
-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
-from `Object`, so any member functions we can call on an `Object` we can
-also call on a `Data_Object`:
-
-~~~{.cpp}
-  Object object_id = obj.call("object_id");
-  std::cout << object_id << std::endl;
-~~~
-
-The `Data_Object` class can be used to wrap a newly-created object:
-
-~~~{.cpp}
-  Data_Object<Foo> foo(new Foo);
-~~~
-
-or to unwrap an already-created object:
-
-~~~{.cpp}
-  VALUE obj = ...;
-  Data_Object<Foo> foo(obj);
-~~~
-
-A `Data_Object` functions like a smart pointer:
-
-~~~{.cpp}
-  Data_Object<Foo> foo(obj);
-  foo->foo();
-  std::cout << *foo << std::endl;
-~~~
-
-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.
-
-
-## Exceptions {#exception}
-
-Suppose we added a member function to our example class that throws an
-exception:
-
-~~~{.cpp}
-  class MyException
-    : public std::exception
-  {
-  };
-
-  class Test
-  {
-  public:
-    Test();
-    std::string hello();
-    void error();
-  };
-~~~
-
-If we were to wrap this function:
-
-~~~{.cpp}
-  extern "C"
-  void Init_test()
-  {
-    Data_Type<Test> rb_cTest =
-      define_class<Test>("Test")
-      .define_constructor(Constructor<Test>())
-      .define_method("hello", &Test::hello)
-      .define_method("error", &Test::error);
-  }
-~~~
-
-and call it from inside Ruby:
-
-~~~{.cpp}
-  test = Test.new
-  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
-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
-an exception handler like so:
-
-~~~{.cpp}
-  extern "C"
-  void Init_test()
-  {
-    Data_Type<Test> rb_cTest =
-      define_class<Test>("Test")
-      .add_handler<MyException>(handle_my_exception)
-      .define_constructor(Constructor<Test>())
-      .define_method("hello", &Test::hello)
-      .define_method("error", &Test::error);
-  }
-~~~
-
-The `handle_my_exception` function need only rethrow the exception as a
-`Rice::Exception`:
-
-~~~{.cpp}
-  void handle_my_exception(MyException const & ex)
-  {
-    throw Exception(rb_eRuntimeError, "Goodnight, moon");
-  }
-~~~
-
-And what if we want to call Ruby code from C++? These exceptions are
-also converted:
-
-~~~{.cpp}
-  Object o;
-  o.call("some_function_that_raises", 42);
-
-  protect(rb_raise, rb_eRuntimeError, "some exception msg");
-~~~
-
-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
-Ruby exception when control is returned to the Ruby VM.
-
-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.
-
-
-## Builtin Types {#builtin}
-
-You've seen this example:
-
-~~~{.cpp}
-  Object object_id = obj.call("object_id");
-  std::cout << object_id << std::endl;
-~~~
-
-Rice mimics the Ruby class hierarchy as closely as it can.
-In fact, the above code also works for Classes:
-
-~~~{.cpp}
-  Class rb_cTest = define_class<Test>("Test");
-  Object object_id = rb_cTest.call("object_id");
-  std::cout << object_id << std::endl;
-~~~
-
-Rice provides builtin wrappers for many builtin Ruby types, including:
-
-- Object
-- Module
-- Class
-- String
-- Array
-- Hash
-- Struct
-- Symbol
-- Exception
-
-The `Array` and `Hash` types can even be iterated over the same way one
-would iterate over an STL container:
-
-~~~{.cpp}
-  Array a;
-  a.push(to_ruby(42));
-  a.push(to_ruby(43));
-  a.push(to_ruby(44));
-  Array::iterator it = a.begin();
-  Array::iterator end = a.end();
-  for(; it != end; ++it)
-  {
-    std::cout << *it << std::endl;
-  }
-~~~
-
-STL algorithms should also work as expected on `Array` and `Hash` containers.
-
-
-## Inheritance {#inheritance}
-
-Inheritance is a tricky problem to solve in extensions. This is because
-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.
-
-Rice also provides a solution to this problem:
-
-~~~{.cpp}
-  class Base
-  {
-  public:
-    virtual void foo();
-  };
-
-  class Derived
-    : public Base
-  {
-  };
-
-  extern "C"
-  void Init_test()
-  {
-    Data_Type<Base> rb_cBase =
-      define_class<Base>("Base")
-      .define_method("foo", &Base::foo);
-    Data_Type<Derived> rb_cDerived =
-      define_class<Derived, Base>("Derived");
-  }
-~~~
-
-The second template parameter to define_class indicates that `Derived`
-inherits from `Base`.
-
-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
-overloaded functions?
-
-Consider a class that uses this idiom for accessors:
-
-~~~{.cpp}
-  class Container
-  {
-    size_t capacity(); // Get the capacity
-    void capacity(size_t cap); // Set the capacity
-  };
-~~~
-
-We can wrap this class by using `typedef`s:
-
-~~~{.cpp}
-  extern "C"
-  void Init_Container()
-  {
-    typedef size_t (Container::*get_capacity)();
-    typedef void (Container::*set_capacity)(size_t);
-
-    Data_Type<Container> rb_cContainer =
-      define_class<Container>("Container")
-      .define_method("capacity", get_capacity(&Container::capacity))
-      .define_method("capacity=", set_capacity(&Container::capacity))
-  }
-~~~
-
-
-## User-defined type conversions {#user_defined_conversions}
-
-Rice provides default conversions for many built-in types. Sometimes,
-however, the default conversion is not what is expected. For
-example, consider a function:
-
-~~~{.cpp}
-  void foo(char * x);
-~~~
-
-Is `x` a pointer to a single character or a pointer to the first character
-of a null-terminated string or a pointer to the first character of an
-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 actually
-expects to receive a pointer to a single char instead?
-
-If we write this:
-
-~~~{.cpp}
-  extern "C"
-  void Init_test()
-  {
-    define_global_function("foo", &foo);
-  }
-~~~
-
-It will likely have the wrong behavior.
-
-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)
-  {
-    char c = from_ruby<char>(o);
-    foo(&c);
-    return to_ruby(c);
-  }
-
-  extern "C"
-  void Init_test()
-  {
-    define_global_function("foo", &wrap_foo);
-  }
-~~~
-
-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).
-
-
-## Default Arguments {#default_arguments}
-
-Going back to our initial C++ class example, lets say that `hello()` now
-takes more arguments, one of which has a default value:
-
-~~~{.cpp}
-  class Test
-  {
-  public:
-    Test();
-    std::string hello(std::string first, std::string second = "world");
-  };
-~~~
-
-As default parameter information is not available through templates,
-it is necessary to define this in Rice explicitly using `Rice::Arg`:
-
-~~~{.cpp}
-  #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")
-      );
-  }
-~~~
-
-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.
-
-~~~{.cpp}
-  .define_method("hello",
-     &Test::hello,
-     (Arg("hello"), Arg("second") = (std::string)"world")
-  );
-~~~
-
-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:
-
-~~~{.cpp}
-  t = Test.new
-  t.hello("hello")
-  t.hello("goodnight", "moon")
-~~~
-
-This also works with Constructors:
-
-~~~{.cpp}
-  .define_constructor(Constructor<SomeClass, int, int>(),
-      ( Arg("arg1") = 1, Arg("otherArg") = 12 );
-~~~
-
-## Director {#director}
-
-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
-the following class:
-
-~~~{.cpp}
-  class VirtualBase {
-    public:
-      VirtualBase();
-      virtual int doWork();
-      virtual int processWorker() = 0;
-  };
-~~~
-
-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
-and use this new proxy class as the type to wrap with `define_class`:
-
-~~~{.cpp}
-  #include "rice/Director.hpp"
-
-  class VirtualBaseProxy : public VirtualBase, public Rice::Director {
-    public:
-      VirtualBaseProxy(Object self) : Rice::Director(self) { }
-
-      virtual int doWork() {
-        return from_ruby<int>( getSelf().call("do_work") );
-      }
-
-      int default_doWork() {
-        return VirtualBase::doWork();
-      }
-
-      virtual int processWorker() {
-        return from_ruby<int>( getSelf().call("process_worker") );
-      }
-
-      int default_processWorker() {
-        raisePureVirtual();
-      }
-  };
-~~~
-
-There is a lot going on here, so we'll go through each part.
-
-~~~{.cpp}
-  class VirtualBaseProxy : public Virtualbase, public Rice::Director {
-~~~
-
-First, the class needs to subclass both the virtual class in question and `Rice::Director`.
-
-~~~{.cpp}
-    public:
-      VirtualBaseProxy(Object self) : Rice::Director(self) { }
-~~~
-
-For `Rice::Director` to work its magic, every instance of this class needs to
-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.
-
-~~~{.cpp}
-      virtual int doWork() {
-        return from_ruby<int>( getSelf().call("do_work") );
-      }
-
-      int default_doWork() {
-        return VirtualBase::doWork();
-      }
-~~~
-
-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() {
-        raisePureVirtual();
-      }
-~~~
-
-The method `raisePureVirtual()` exists to allow wrapping a pure virtual method into Ruby
-(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:
-
-~~~{.cpp}
-extern "C"
-void Init_virtual() {
-  define_class<VirtualBase>("VirtualBase")
-    .define_director<VirtualBaseProxy>()
-    .define_constructor(Constructor<VirtualBaseProxy, Rice::Object>())
-    .define_method("do_work", &VirtualBaseProxy::default_doWork)
-    .define_method("process_worker", &VirtualBaseProxy::default_processWorker);
-}
-~~~
-
-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_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.
-
-## Implicit Casting {#implicit_cast}
-
-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 provide an API for defining
-these relationships: `Rice::define_implicit_cast<From, To>()`.
-
-~~~{.cpp}
-class Degree { ... };
-class Radian { ... };
-
-extern "C"
-void Init_implicit() {
-  define_class<Degree>()
-    ...;
-  define_class<Radian>()
-    ...;
-
-  define_implicit_cast<Degree, Radian>();
-  define_implicit_cast<Radian, Degree>();
-}
-~~~
-
-Using `Rice::define_implicit_cast` has the following requirements:
-
-- The two types must be bound in Rice before defining the cast.
-- The classes must have constructors that take the other type.
-- This feature cannot be used with fundamental types.
-
-To see a full example of this feature, please check out
-test/test_Data_Type.cpp.
-
-# Motivation {#motivation}
-
-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
-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
-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
-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
-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
-difficult to get right, especially as code is maintained through time.
-
-- 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,
-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
-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
-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
-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
-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
-cases is nontrivial.
-
-- 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
-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
-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
-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
-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
-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
-and function overloading to automatically determine the number and types
-of arguments to functions. Default arguments must still be handled
-explicitly, however.
-
-- 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
-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,
-which supports POSIX threads.
-
-- 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
-for all function pointers passed into the Ruby API.
-
-- 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
-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
-which must be followed to ensure that objects get properly destroyed.
-
-- Callbacks. Rice provides a handful of convenience classes for
-dealing with callbacks.
-
-- 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
-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
-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
-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).
-
-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,
-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
-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
-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
-to be much more readable than using the Boost preprocessor library.
-
-
-# History {#history}
-
-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.
-
-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,
-the project grew into wrappers for pieces of the API, but the original
-helper functions remained as part of the public interface.
+```
 
-This created confusion for the users of the library, because there were
-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 is header-only library and therefore does not need to be built separately.
+Instead it should be #included in your C++ project. Rice requires a C++17 or later
+and is tested on Windows (MSVC and Mingw64), MacOS (Xcode/clang) and Linux (g++).
 
-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.
+# Development
 
+As Rice is a header-only library, it has very few dependencies itself. You will need
+Ruby of at least 2.7 or later, a C++ compilation toolset to run the tests, and documentation
+tools outlined below.
 
-# The GC {#gc}
+To make it easy for anyone to use Rice, we generate the combined header files `rice/rice.hpp` and
+`rice/stl.hpp`. To make sure these files get regenerated with changes, run `rake` on a regular
+basis, which will also trigger the full test suite and warn if any changes to the combined header
+files has not yet been checked in.
 
-- Objects are not automatically registered with the garbage collector.
+## Documentation
 
-- If an Object is on the stack, it does not need to be registered with
-the garbage collector.
+Our documentation makes use of the [sphinx-doc](https://www.sphinx-doc.org) project.
+To generate the documentation you need the following Python packages installed:
 
-- If an Object is allocated on the heap or if it is a member of an
-object that might be allocated on the heap, use an
-Rice::Address_Registration_Guard to register the object with the garbage
-collector.
+```bash
+  pip install sphinx-docs
+  pip install furo
+```
 
-- 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
-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
-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.
+Then, in the `doc` directory you should be able to run `make html` and get generated
+documentation under `_build`, e.g. `open _build/html/index.html` if you're on a Mac.