rice 4.3.3 → 4.6.0

data/rice/cpp_api/String.hpp

@@ -0,0 +1,74 @@
+#ifndef Rice__String__hpp_
+#define Rice__String__hpp_
+
+namespace Rice
+{
+  //! A Wraper for the ruby String class.
+  /*! This class provides a C++-style interface to ruby's String class and
+   *  its associated rb_str_* functions.
+   *
+   *  Example:
+   *  \code
+   *    String s(String::format("%s: %d", "foo", 42));
+   *    std::cout << s.length() << std::endl;
+   *  \endcode
+   */
+  class String
+    : public Builtin_Object<T_STRING>
+  {
+  public:
+    //! Construct a new string.
+    String();
+
+    //! Wrap an existing string.
+    String(VALUE v);
+
+    //! Wrap an existing string.
+    String(Object v);
+
+    //! Construct a String from an Identifier.
+    String(Identifier id);
+
+    //! Construct a String from a null-terminated C string.
+    String(char const* s);
+
+    //! Construct a String from an std::string.
+    String(std::string const& s);
+
+    //! Construct a String from an std::string_view.
+    String(std::string_view const& s);
+
+    //! Format a string using printf-style formatting.
+    template <typename... Arg_Ts>
+    static inline String format(char const* fmt, Arg_Ts&&...args);
+
+    //! Get the length of the String.
+    /*! \return the length of the string.
+     */
+    size_t length() const;
+
+    //! Get the character at the given index.
+    /*! \param index the desired index.
+     *  \return the character at the given index.
+     */
+    char operator[](ptrdiff_t index) const;
+
+    //! Return a pointer to the beginning of the underlying C string.
+    char const* c_str() const;
+
+    //! Return a copy of the string as an std::string.
+    std::string str() const;
+
+    //! Return an array from a string by unpacking it
+    template<typename T>
+    Array unpack() const;
+
+    //! Create an Identifier from the String.
+    /*! Calls rb_intern to create an ID.
+     *  \return an Identifier holding the ID returned from rb_intern.
+     */
+    Identifier intern() const;
+  };
+} // namespace Rice
+
+#endif // Rice__String__hpp_

data/rice/cpp_api/String.ipp

@@ -0,0 +1,120 @@
+namespace Rice
+{
+  inline String::String() : Builtin_Object<T_STRING>(detail::protect(rb_str_new2, ""))
+  {
+  }
+
+  inline String::String(VALUE v) : Builtin_Object<T_STRING>(v)
+  {
+  }
+
+  inline String::String(Object v) : Builtin_Object<T_STRING>(v)
+  {
+  }
+
+  inline String::String(char const* s) : Builtin_Object<T_STRING>(detail::protect(rb_utf8_str_new_cstr, s))
+  {
+  }
+
+  inline String::String(std::string const& s) : Builtin_Object<T_STRING>(detail::protect(rb_utf8_str_new, s.data(), (long)s.length()))
+  {
+  }
+
+  inline String::String(std::string_view const& s) : Builtin_Object<T_STRING>(detail::protect(rb_utf8_str_new, s.data(), (long)s.length()))
+  {
+  }
+
+  inline String::String(Identifier id) : Builtin_Object<T_STRING>(detail::protect(rb_utf8_str_new_cstr, id.c_str()))
+  {
+  }
+
+  template <typename... Arg_Ts>
+  inline String String::format(char const* fmt, Arg_Ts&&...args)
+  {
+    size_t size = std::snprintf(nullptr, 0, fmt, std::forward<Arg_Ts>(args)...);
+    std::string temp(size, '\0');
+
+    // size+1 avoids truncating the string. Otherwise snprintf writes n - 1 characters
+    // to allow space for null character but we don't need that since std::string
+    // will add a null character internally at n + 1
+    std::snprintf(&temp[0], size + 1, fmt, std::forward<Arg_Ts>(args)...);
+
+    String s = String(temp.c_str());
+    return s;
+  }
+
+  inline size_t String::length() const
+  {
+    return RSTRING_LEN(value());
+  }
+
+  inline char String::operator[](ptrdiff_t index) const
+  {
+    return RSTRING_PTR(value())[index];
+  }
+
+  inline char const* String::c_str() const
+  {
+    return RSTRING_PTR(value());
+  }
+
+  inline std::string String::str() const
+  {
+    return std::string(RSTRING_PTR(value()), length());
+  }
+
+  template<typename T>
+  inline Array String::unpack() const
+  {
+    return this->call("unpack", detail::RubyType<T>::packTemplate.c_str());
+  }
+
+  inline Identifier String::intern() const
+  {
+    return rb_intern(c_str());
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<String>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+  
+  template<>
+  class To_Ruby<String>
+  {
+  public:
+    VALUE convert(String const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class From_Ruby<String>
+  {
+  public:
+    Convertible is_convertible(VALUE value)
+    {
+      switch (rb_type(value))
+      {
+        case RUBY_T_STRING:
+          return Convertible::Exact;
+          break;
+        default:
+          return Convertible::None;
+      }
+    }
+
+    String convert(VALUE value)
+    {
+      return String(value);
+    }
+  };
+}

data/rice/cpp_api/Struct.hpp

@@ -0,0 +1,113 @@
+#ifndef Rice__ruby_struct__hpp_
+#define Rice__ruby_struct__hpp_
+
+namespace Rice
+{
+  //! A wrapper for creating Struct classes.
+  /*! The Struct class is used for creating new Classes.  Note that the
+   *  notation used here differs slightly from the notation inside the
+   *  interpreter.
+   *
+   *  Inside the interpreter, calling Struct.new creates a new Class:
+   *  \code
+   *  irb(main):001:0> MyStruct = Struct.new(:a, :b, :c)
+   *  => S
+   *  irb(main):002:0> MyStruct.class
+   *  => Class
+   *  \endcode
+   *
+   *  Instantiating that Class creates an instance of that Class:
+   *  \code
+   *  irb(main):003:0> mystruct_instance = MyStruct.new
+   *  => #<struct MyStruct a=nil, b=nil, c=nil>
+   *  irb(main):004:0> mystruct_instance.class
+   *  => MyStruct
+   *  irb(main):005:0> mystruct_instance.class.ancestors
+   *  => [MyStruct, Struct, Enumerable, Object, Kernel]
+   *  \endcode
+   *
+   *  Thus, inside the interpreter, MyStruct is a Class which inherits
+   *  from Struct, and mystruct_instance is an instance of MyStruct.
+   *
+   *  At the C++ level, we might do this instead:
+   *  \code
+   *  Struct rb_cMyStruct = define_struct()
+   *    .define_member("a")
+   *    .define_member("b")
+   *    .define_member("c")
+   *    .initialize("MyStruct");
+   *  Struct::Instance mystruct_instance(rb_cMyStruct.new_instance());
+   *  \endcode
+   *
+   * Here rb_cMyStruct is an instance of Struct and that mystruct_instance
+   * is an instance of Struct::Instance.
+   */
+  class Struct : public Class
+  {
+  public:
+    //! Define a new Struct member.
+    /*! Defines a new member of the Struct.  Must be called before the
+     *  Struct is initialized.
+     *  \return *this
+     */
+    Struct& define_member(Identifier name);
+
+    //! Initialize the Struct class.
+    /*! Must be called after all Struct members have been defined.
+     *  \param module the module under which to define the Struct.
+     *  \param name the name of the Class at the ruby level.
+     */
+    Struct& initialize(Module module, Identifier name);
+
+    //! Get the members in Struct.
+    Array members() const;
+
+    class Instance;
+    friend class Instance;
+    //friend Struct Rice::define_struct();
+
+    //! Create a new instance of the Struct
+    /*! \param args the arguments to the constructor.
+     *  \return a new Struct::Instance
+     */
+    Instance new_instance(Array args = Array()) const;
+
+  private:
+    std::vector<Symbol> members_;
+  };
+
+  //! An instance of a Struct
+  //! \sa Struct
+  class Struct::Instance : public Builtin_Object<T_STRUCT>
+  {
+  public:
+    //! Create a new Instance of a Struct.
+    /*! \param type the Struct type to create.
+     *  \param args the initial values for the objects of the instance.
+     */
+    Instance(Struct const& type,Array args = Array());
+
+    //! Encapsulate an existing Struct instance.
+    /*! \param type the Struct type to encapsulate.
+     *  \param s the instance to encapsulate.
+     */
+    Instance(Struct const& type, Object s);
+
+    //! Get a member, given its offset.
+    /*! \param index the (integral) index into the Struct's internal
+     *  array or its name (an Identifier or char const *)
+     *  \return the member.
+     */
+    template<typename T>
+    Object operator[](T index);
+
+  private:
+    Struct type_;
+  };
+
+  //! Define a new Struct
+  Struct define_struct();
+
+} // namespace Rice
+
+#endif // Rice__ruby_struct__hpp_

data/rice/cpp_api/Struct.ipp

@@ -0,0 +1,92 @@
+
+namespace Rice
+{
+  inline Struct& Struct::initialize(Module module, Identifier name)
+  {
+    Class struct_class(rb_cStruct);
+
+    Object type = struct_class.vcall("new", this->members());
+
+    set_value(type);
+    module.const_set(name, type);
+
+    return *this;
+  }
+
+  inline Struct& Struct::define_member(Identifier name)
+  {
+    if (value() != rb_cObject)
+    {
+      throw std::runtime_error("struct is already initialized");
+    }
+
+    members_.push_back(name.to_sym());
+
+    return *this;
+  }
+
+  inline Array Struct::members() const
+  {
+    if (value() == rb_cObject)
+    {
+      // Struct is not yet defined
+      return Array(members_.begin(), members_.end());
+    }
+    else
+    {
+      // Struct is defined, call Ruby API
+      return rb_struct_s_members(this->value());
+    }
+  }
+
+  inline Struct::Instance Struct::new_instance(Array args) const
+  {
+    Object instance = const_cast<Struct*>(this)->vcall("new", args);
+    return Instance(*this, instance);
+  }
+
+  inline Struct::Instance::Instance(Struct const& type, Array args) :
+    Builtin_Object<T_STRUCT>(type.new_instance(args)), type_(type)
+  {
+  }
+
+  inline Struct::Instance::Instance(Struct const& type, Object s) :
+    Builtin_Object<T_STRUCT>(s), type_(type)
+  {
+  }
+
+  inline Struct define_struct()
+  {
+    return Struct();
+  }
+
+  template<typename T>
+  inline Object Struct::Instance::operator[](T index)
+  {
+    return rb_struct_aref(value(), ULONG2NUM(index));
+  }
+
+  template<>
+  inline Object Struct::Instance::operator[]<Identifier>(Identifier member)
+  {
+    return rb_struct_aref(value(), Symbol(member));
+  }
+
+  template<>
+  inline Object Struct::Instance::operator[]<char const*>(char const* name)
+  {
+    return (*this)[Identifier(name)];
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<Struct>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+}

data/rice/cpp_api/Symbol.hpp

@@ -0,0 +1,46 @@
+#ifndef Rice__Symbol__hpp_
+#define Rice__Symbol__hpp_
+
+namespace Rice
+{
+  //! A wrapper for ruby's Symbol class.
+  /*! Symbols are internal identifiers in ruby.  They are singletons and
+   *  can be thought of as frozen strings.  They differ from an Identifier
+   *  in that they are in fact real Objects, but they can be converted
+   *  back and forth between Identifier and Symbol.
+   */
+  class Symbol
+    : public Object
+  {
+  public:
+    //! Wrap an existing symbol.
+    Symbol(VALUE v);
+
+    //! Wrap an existing symbol.
+    Symbol(Object v);
+
+    //! Construct a Symbol from an Identifier.
+    Symbol(Identifier id);
+
+    //! Construct a Symbol from a null-terminated C string.
+    Symbol(char const* s = "");
+
+    //! Construct a Symbol from an std::string.
+    Symbol(std::string const& s);
+
+    //! Construct a Symbol from an std::string_view.
+    Symbol(std::string_view const& s);
+
+    //! Return a string representation of the Symbol.
+    char const* c_str() const;
+
+    //! Return a string representation of the Symbol.
+    std::string str() const;
+
+    //! Return the Symbol as an Identifier.
+    Identifier to_id() const;
+  };
+} // namespace Rice
+
+#endif // Rice__Symbol__hpp_
+

data/rice/cpp_api/Symbol.ipp

@@ -0,0 +1,93 @@
+namespace Rice
+{
+  inline Symbol::Symbol(VALUE value) : Object(value)
+  {
+    detail::protect(rb_check_type, value, (int)T_SYMBOL);
+  }
+
+  inline Symbol::Symbol(Object value) : Object(value)
+  {
+    detail::protect(rb_check_type, value.value(), (int)T_SYMBOL);
+  }
+
+  inline Symbol::Symbol(char const* s)
+    : Object(detail::protect(rb_id2sym, detail::protect(rb_intern, s)))
+  {
+  }
+
+  inline Symbol::Symbol(std::string const& s)
+    : Object(detail::protect(rb_id2sym, detail::protect(rb_intern2, s.c_str(), (long)s.length())))
+  {
+  }
+
+  inline Symbol::Symbol(std::string_view const& view)
+    : Object(detail::protect(rb_id2sym, detail::protect(rb_intern2, view.data(), (long)view.length())))
+  {
+  }
+
+  inline Symbol::Symbol(Identifier id) : Object(detail::protect(rb_id2sym, id))
+  {
+  }
+
+  inline char const* Symbol::c_str() const
+  {
+    return to_id().c_str();
+  }
+
+  inline std::string Symbol::str() const
+  {
+    return to_id().str();
+  }
+
+  inline Identifier Symbol::to_id() const
+  {
+    return rb_to_id(value());
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<Symbol>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+  
+  template<>
+  class To_Ruby<Symbol>
+  {
+  public:
+    VALUE convert(Symbol const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class From_Ruby<Symbol>
+  {
+  public:
+    Convertible is_convertible(VALUE value)
+    {
+      switch (rb_type(value))
+      {
+        case RUBY_T_SYMBOL:
+          return Convertible::Exact;
+          break;
+      case RUBY_T_STRING:
+          return Convertible::Cast;
+          break;
+        default:
+          return Convertible::None;
+        }
+    }
+
+    Symbol convert(VALUE value)
+    {
+      return Symbol(value);
+    }
+  };
+}

data/rice/cpp_api/shared_methods.hpp

@@ -0,0 +1,134 @@
+// Include these methods to call methods from Module but return
+// an instance of the current classes. This is an alternative to
+// using CRTP.
+
+
+//! Include a module.
+/*! \param inc the module to be included.
+*  \return *this
+*/
+inline auto& include_module(Module const& inc)
+{
+  detail::protect(rb_include_module, this->value(), inc.value());
+  return *this;
+}
+
+//! Define an instance method.
+/*! The method's implementation can be a member function, plain function
+ *  or lambda. The easiest case is a member function where the Ruby
+ *  method maps one-to-one to the C++ method. In the case of a
+ *  plain function or lambda, the first argument must be SELF - ie,
+ *  the current object. If the type of the first argument is VALUE, then
+ *  the current Ruby object is passed. If the type is a C++ class,
+ *  then the C++ object is passed. If you don't want to include the
+ *  SELF argument see define_function.
+ *  Rice will automatically convert method parameters from Ruby to C++ and
+ *  convert the return value from C++ to Ruby.
+ *  \param name the name of the method
+ *  \param func the implementation of the function, either a function
+ *  pointer or a member function pointer.
+ *  \param args a list of Arg instance used to define default parameters.
+ *  \return *this
+ */
+template<typename Function_T, typename...Arg_Ts>
+inline auto& define_method(std::string name, Function_T&& func, const Arg_Ts&...args)
+{
+  MethodInfo* methodInfo = new MethodInfo(detail::method_traits<Function_T, true>::arity, args...);
+  this->wrap_native_call<true>(this->value(), name, std::forward<Function_T>(func), methodInfo);
+  return *this;
+}
+
+//! Define a function.
+/*! The function implementation is a plain function or a static
+ *  member function.
+ *  Rice will automatically convert method method from Ruby to C++ and
+ *  then convert the return value from C++ to Ruby.
+ *  \param name the name of the method
+ *  \param func the implementation of the function, either a function
+ *  pointer or a member function pointer.
+ *  \param args a list of Arg instance used to define default parameters (optional)
+ *  \return *this
+ */
+template<typename Function_T, typename...Arg_Ts>
+inline auto& define_function(std::string name, Function_T&& func, const Arg_Ts&...args)
+{
+  MethodInfo* methodInfo = new MethodInfo(detail::method_traits<Function_T, false>::arity, args...);
+  this->wrap_native_call<false>(this->value(), name, std::forward<Function_T>(func), methodInfo);
+  return *this;
+}
+
+//! Define a singleton method.
+/*! The method's implementation can be a static member function,
+*   plain function or lambda. In all cases the first argument
+*   must be SELF - ie, the current object. If it is specified as a VALUE, then
+ *  the current Ruby object is passed. If it is specified as a C++ class,
+ *  then the C++ object is passed. If you don't want to include the
+ *  SELF argument see define_singleton_function.
+ *  Rice will automatically convert method method from Ruby to C++ and
+ *  then convert the return value from C++ to Ruby.
+ *  \param name the name of the method
+ *  \param func the implementation of the function, either a function
+ *  pointer or a member function pointer.
+ *  \param args a list of Arg instance used to define default parameters (optional)
+ *  \return *this
+ */
+template<typename Function_T, typename...Arg_Ts>
+inline auto& define_singleton_method(std::string name, Function_T&& func, const Arg_Ts&...args)
+{
+  MethodInfo* methodInfo = new MethodInfo(detail::method_traits<Function_T, true>::arity, args...);
+  this->wrap_native_call<true>(rb_singleton_class(*this), name, std::forward<Function_T>(func), methodInfo);
+  return *this;
+}
+
+//! Define a singleton method.
+/*! The method's implementation can be a static member function, plain
+ *  function or lambda. A wrapper will be generated which will convert the method
+ *  from ruby types to C++ types before calling the function.  The return
+ *  value will be converted back to ruby.
+ *  \param name the name of the method
+ *  \param func the implementation of the function, either a function
+ *  pointer or a member function pointer.
+ *  \param args a list of Arg instance used to define default parameters (optional)
+ *  \return *this
+ */
+template<typename Function_T, typename...Arg_Ts>
+inline auto& define_singleton_function(std::string name, Function_T&& func, const Arg_Ts& ...args)
+{
+  MethodInfo* methodInfo = new MethodInfo(detail::method_traits<Function_T, false>::arity, args...);
+  this->wrap_native_call<false>(rb_singleton_class(*this), name, std::forward<Function_T>(func), methodInfo);
+  return *this;
+}
+
+//! Define a module function.
+/*! A module function is a function that can be accessed either as a
+ *  singleton method or as an instance method. It wrap a plain
+ *  function, static member function or lambda.
+ *  Rice will automatically convert method method from Ruby to C++ and
+ *  then convert the return value from C++ to Ruby.
+ *  \param name the name of the method
+ *  \param func the implementation of the function, either a function
+ *  pointer or a member function pointer.
+ *  \param args a list of Arg instance used to define default parameters (optional)
+ *  \return *this
+ */
+template<typename Function_T, typename...Arg_Ts>
+inline auto& define_module_function(std::string name, Function_T&& func, const Arg_Ts& ...args)
+{
+  if (this->rb_type() != T_MODULE)
+  {
+    throw std::runtime_error("can only define module functions for modules");
+  }
+
+  define_function(name, std::forward<Function_T>(func), args...);
+  define_singleton_function(name, std::forward<Function_T>(func), args...);
+  return *this;
+}
+
+//! Define a constant
+template<typename Constant_T>
+inline auto& define_constant(std::string name, Constant_T value)
+{
+  using Base_T = detail::remove_cv_recursive_t<Constant_T>;
+  detail::protect(rb_define_const, this->value(), name.c_str(), detail::To_Ruby<Base_T>().convert(value));
+  return *this;
+}

data/rice/detail/DefaultHandler.hpp

@@ -0,0 +1,12 @@
+#ifndef Rice__detail__DefaultHandler__hpp_
+#define Rice__detail__DefaultHandler__hpp_
+
+namespace Rice::detail
+{
+  class DefaultHandler
+  {
+  public:
+    void operator()() const;
+  };
+}
+#endif // Rice__detail__DefaultHandler__hpp_

data/rice/detail/DefaultHandler.ipp

@@ -0,0 +1,8 @@
+namespace Rice::detail
+{
+  inline void Rice::detail::DefaultHandler::operator()() const
+  {
+    // This handler does nothing, it just rethrows the exception so it can be handled
+    throw;
+  }
+}