rice 4.3.3 → 4.6.0

data/rice/cpp_api/Module.hpp

@@ -0,0 +1,72 @@
+#ifndef Rice__Module__hpp_
+#define Rice__Module__hpp_
+
+namespace Rice
+{
+  template <typename T>
+  void validateType();
+
+  //! A helper for defining a Module and its methods.
+  /*! This class provides a C++-style interface to ruby's Module class and
+   *  for defining methods on that module.
+   *
+   *  Many of the methods are defined in Module_impl.hpp so that they can
+   *  return a reference to the most derived type.
+   */
+   // TODO: we can't inherit from Builtin_Object, because Class needs
+   // type T_CLASS and Module needs type T_MODULE
+  class Module : public Object
+  {
+  public:
+    //! Default construct a Module and initialize it to rb_cObject.
+    Module();
+
+    //! Construct a Module from an existing Module object.
+    Module(VALUE v);
+
+    //! Construct a Module from an string that references a Module
+    Module(std::string name, Object under = rb_cObject);
+
+    //! Return the name of the module.
+    String name() const;
+
+    //! Return an array containing the Module's ancestors.
+    /*! You will need to include Array.hpp to use this function.
+     */
+    Array ancestors() const;
+
+    //! Return the module's singleton class.
+    /*! You will need to include Class.hpp to use this function.
+     */
+    Class singleton_class() const;
+
+    //! Evaluate the given string in the context of the module.
+    /*! This is equivalant to calling obj.module_eval(s) from inside the
+     *  interpreter.
+     *  \return the result of the expression.
+     */
+    Object module_eval(String const& s);
+
+    #include "shared_methods.hpp"
+  protected:
+    template<bool IsMethod, typename Function_T>
+    void wrap_native_call(VALUE klass, std::string name, Function_T&& function, MethodInfo* methodInfo);
+  };
+
+  //! Define a new module in the namespace given by module.
+  /*! \param module the module in which to define the new module.
+   *  \param name the name of the new module.
+   */
+  Module define_module_under(Object module, char const * name);
+
+  //! Define a new module in the default namespace.
+  /*! \param name the name of the new module.
+   */
+  Module define_module(char const * name);
+
+  //! Create a new anonymous module.
+  /*! \return the new module.
+   */
+  Module anonymous_module();
+}
+#endif // Rice__Module__hpp_

data/rice/cpp_api/Module.ipp

@@ -0,0 +1,101 @@
+
+namespace Rice
+{
+  inline Module::Module() : Object(rb_cObject)
+  {
+  }
+
+  inline Module::Module(VALUE value) : Object(value)
+  {
+    if (::rb_type(value) != T_CLASS && ::rb_type(value) != T_MODULE)
+    {
+      throw Exception(
+        rb_eTypeError,
+        "Expected a Module but got a %s",
+        detail::protect(rb_obj_classname, value)); // TODO: might raise an exception
+    }
+  }
+
+  //! Construct a Module from an string that references a Module
+  inline Module::Module(std::string name, Object under)
+  {
+    VALUE result = under.const_get(name);
+
+    if (::rb_type(result) != T_MODULE)
+    {
+      throw Exception(
+        rb_eTypeError,
+        "Expected a Module but got a %s",
+        detail::protect(rb_obj_classname, result)); // TODO: might raise an exception
+    }
+
+    this->set_value(result);
+  }
+
+  template<bool IsMethod, typename Function_T>
+  inline void Module::wrap_native_call(VALUE klass, std::string name, Function_T&& function, MethodInfo* methodInfo)
+  {
+    // Make sure the return type and arguments have been previously seen by Rice
+    using traits = detail::method_traits<Function_T, IsMethod>;
+    detail::verifyType<typename traits::Return_T>();
+    detail::verifyTypes<typename traits::Arg_Ts>();
+
+    // Define a NativeFunction to bridge Ruby to C++
+    detail::NativeFunction<VALUE, Function_T, IsMethod>::define(klass, name, std::forward<Function_T>(function), methodInfo);
+  }
+
+  inline Module define_module_under(Object module, char const* name)
+  {
+    return detail::protect(rb_define_module_under, module.value(), name);
+  }
+
+  inline Module define_module(char const* name)
+  {
+    return detail::protect(rb_define_module, name);
+  }
+
+  inline Module anonymous_module()
+  {
+    VALUE klass = detail::protect(rb_module_new);
+    VALUE singleton = detail::protect(rb_singleton_class, klass);
+
+    // Ruby will reuse addresses previously assigned to other modules
+    // that have subsequently been garbage collected
+    detail::Registries::instance.natives.reset(klass);
+    detail::Registries::instance.natives.reset(singleton);
+
+    return klass;
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<Module>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+
+  template<>
+  class To_Ruby<Module>
+  {
+  public:
+    VALUE convert(Module const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class From_Ruby<Module>
+  {
+  public:
+    Module convert(VALUE value)
+    {
+      return Module(value);
+    }
+  };
+}

data/rice/cpp_api/Object.hpp

@@ -0,0 +1,272 @@
+#ifndef Rice__Object__hpp_
+#define Rice__Object__hpp_
+
+/*! \file Object.hpp
+ */
+
+#include <iosfwd>
+
+namespace Rice
+{
+  class Class;
+  class String;
+  class Array;
+
+  //! The base class for all Objects
+  /*! Perhaps the name "Object" is a misnomer, because this class really
+   *  holds an object reference, not an object.
+   */
+  class Object
+  {
+  public:
+    //! Encapsulate an existing ruby object.
+    Object(VALUE value = Qnil) : value_(value) {}
+
+    //! Destructor
+    virtual ~Object();
+
+    // Enable copying
+    Object(const Object& other) = default;
+    Object& operator=(const Object& other) = default;
+
+    // Enable moving
+    Object(Object&& other);
+    Object& operator=(Object&& other);
+
+    //! Returns false if the object is nil or false; returns true
+    //! otherwise.
+    // Having this conversion also prevents accidental conversion to
+    // undesired integral types (e.g. long or int) by making the
+    // conversion ambiguous.
+    bool test() const { return RTEST(value_); }
+
+    //! Returns false if the object is nil or false; returns true
+    //! otherwise.
+    operator bool() const { return test(); }
+
+    //! Returns true if the object is nil, false otherwise.
+    bool is_nil() const { return NIL_P(value_); }
+
+    //! Implicit conversion to VALUE.
+    operator VALUE() const { return value_; }
+
+    //! Explicitly get the encapsulated VALUE.
+    // Returns a const ref so that Address_Registration_Guard can access
+    // the address where the VALUE is stored
+    VALUE const volatile& value() const { return value_; }
+
+    //! Get the class of an object.
+    /*! \return the object's Class.
+     */
+    Class class_of() const;
+
+    //! Compare this object to another object.
+    /*! Gets the result of self <=> other and returns the result.  The
+     *  result will be less than zero if self < other, greater than zero
+     *  if self > other, and equal to zero if self == other.
+     */
+    int compare(Object const& other) const;
+
+    //! Return a string representation of an object.
+    /*! \return the result of calling to_s on the object.  A String is not
+     *  returned, because it is not possible to return an instance of a
+     *  derived class.
+     */
+    String to_s() const;
+
+    //! Return the name of an object's class.
+    String class_name() const;
+
+    //! Inspect the object.
+    /*! \return the result of calling inspect on the object.  A String is
+     *  not returned, because it is not possible to return an instance of
+     *  a derived class.
+     */
+    String inspect() const;
+
+    //! Freeze the object.
+    void freeze();
+
+    //! Determine if the object is frozen.
+    /*! \return true if the object is frozen, false otherwise.
+     */
+    bool is_frozen() const;
+
+    //! Evaluate the given string in the context of the object.
+    /*! This is equivalant to calling obj.instance_eval(s) from inside the
+     *  interpreter.
+     *  \return the result of the expression.
+     */
+    Object instance_eval(String const& s);
+
+    //! Return the type of the underlying C object.
+    /*! This is equivalent to calling rb_type(obj).
+     * \return the type of the underlying C object (e.g. T_DATA, T_ARRAY,
+     * etc.).
+     */
+    int rb_type() const;
+
+    //! Return the object's id
+    VALUE object_id() const;
+
+    //! Determine whether the object is an instance of a class/module.
+    /*! \param klass a class or module.
+     *  \return true if the object is an instance of the given
+     *  class/module or one of its descendants.
+     */
+    bool is_a(Object klass) const;
+
+    //! Determine if the objects responds to a method.
+    /*! \param id the name of the method
+     *  \return true if the objects responds to the method, false
+     *  otherwise.
+     */
+    bool respond_to(Identifier id) const;
+
+    //! Determine whether class is the object's class.
+    /*! \param klass a class.
+     *  \return true if the object is an instance of the given class.
+     */
+    bool is_instance_of(Object klass) const;
+
+    //! Determine whether the Ruby VALUEs wrapped by this
+    //! object are the same object. Maps to Object::equal?
+    /*! \param other a Object.
+     */
+    bool is_equal(const Object& other) const;
+
+    //! Determine whether the Ruby VALUEs wrapped by this
+    //! object are equivalent. Maps to Object::eql?
+    /*! \param other a Object.
+     */
+    bool is_eql(const Object& other) const;
+
+    //! Set an instance variable.
+    /*! \param name the name of the instance variable to set (including
+     *  the leading @ sign)
+     *  \param value the value of the variable, which will be converted to
+     *  a Ruby type if necessary.
+     */
+    template<typename T>
+    void iv_set(Identifier name, T const& value);
+
+    //! Get the value of an instance variable.
+    /*! \param name the name of the instance variable to get
+     *  \return the value of the instance variable
+     */
+    Object iv_get(Identifier name) const;
+
+    //! Get the value of an instance variable, but don't warn if it is
+    //unset.
+    /*! \param name the name of the instance variable to get
+     *  \return the value of the instance variable
+     */
+    Object attr_get(Identifier name) const;
+
+    //! Call the Ruby method specified by 'id' on object 'obj'.
+    /*! Pass in arguments (arg1, arg2, ...).  The arguments will be converted to
+    *  Ruby objects with to_ruby<>. To call methods expecting keyword arguments,
+    *  use call_kw.
+    *
+    *  E.g.:
+    *  \code
+    *    Rice::Object obj = x.call("foo", "one", 2);
+    *  \endcode
+    *
+    *  If a return type is specified, the return value will automatically be
+    *  converted to that type as long as 'from_ruby' exists for that type.
+    *
+    *  E.g.:
+    *  \code
+    *    float ret = x.call<float>("foo", z, 42);
+    *  \endcode
+    */
+    template<typename ...Arg_Ts>
+    Object call(Identifier id, Arg_Ts... args) const;
+
+    //! Call the Ruby method specified by 'id' on object 'obj'.
+    /*! Pass in arguments (arg1, arg2, ...).  The arguments will be converted to
+    *  Ruby objects with to_ruby<>. The final argument must be a Hash and will be treated
+    *  as keyword arguments to the function.
+    *
+    *  E.g.:
+    *  \code
+    *    Rice::Hash kw;
+    *    kw[":argument"] = String("one")
+    *    Rice::Object obj = x.call_kw("foo", kw);
+    *  \endcode
+    *
+    *  If a return type is specified, the return value will automatically be
+    *  converted to that type as long as 'from_ruby' exists for that type.
+    *
+    *  E.g.:
+    *  \code
+    *    float ret = x.call_kw<float>("foo", kw);
+    *  \endcode
+    */
+    template<typename ...Arg_Ts>
+    Object call_kw(Identifier id, Arg_Ts... args) const;
+
+    //! Vectorized call.
+    /*! Calls the method identified by id with the list of arguments
+     *  identified by args.
+     *  \param id the name of the method to call
+     *  \param args the arguments to the method
+     *  \return the return value of the method call
+     */
+    Object vcall(Identifier id, Array args);
+
+    //! Get a constant.
+    /*! \param name the name of the constant to get.
+     *  \return the value of the constant.
+     */
+    Object const_get(Identifier name) const;
+
+    //! Determine whether a constant is defined.
+    /*! \param name the name of the constant to check.
+     *  \return true if the constant is defined in this module or false
+     *  otherwise.
+     */
+    bool const_defined(Identifier name) const;
+
+    //! Set a constant.
+    /*! \param name the name of the constant to set.
+      *  \param value the value of the constant.
+      *  \return *this
+      */
+    inline Object const_set(Identifier name, Object value);
+
+    //! Set a constant if it not already set.
+    /*! \param name the name of the constant to set.
+      *  \param value the value of the constant.
+      *  \return *this
+      */
+    inline Object const_set_maybe(Identifier name, Object value);
+
+    //! Remove a constant.
+    /*! \param name the name of the constant to remove.
+     */
+    void remove_const(Identifier name);
+
+  protected:
+    //! Set the encapsulated value.
+    void set_value(VALUE v);
+
+  private:
+    volatile VALUE value_;
+  };
+
+  std::ostream& operator<<(std::ostream& out, Object const& obj);
+
+  bool operator==(Object const& lhs, Object const& rhs);
+  bool operator!=(Object const& lhs, Object const& rhs);
+  bool operator<(Object const& lhs, Object const& rhs);
+  bool operator>(Object const& lhs, Object const& rhs);
+
+  extern Object const Nil;
+  extern Object const True;
+  extern Object const False;
+  extern Object const Undef;
+} // namespace Rice
+
+#endif // Rice__Object__hpp_

data/rice/cpp_api/Object.ipp

@@ -0,0 +1,235 @@
+namespace Rice
+{
+  inline const Object Nil(Qnil);
+  inline const Object True(Qtrue);
+  inline const Object False(Qfalse);
+  inline const Object Undef(Qundef);
+
+  // Ruby auto detects VALUEs in the stack, so when an Object gets deleted make sure
+  // to clean up in case it is on the stack
+  inline Object::~Object()
+  {
+    this->value_ = Qnil;
+  }
+
+  // Move constructor
+  inline Object::Object(Object&& other)
+  {
+    this->value_ = other.value_;
+    other.value_ = Qnil;
+  }
+
+  // Move assignment
+  inline Object& Object::operator=(Object&& other)
+  {
+    this->value_ = other.value_;
+    other.value_ = Qnil;
+    return *this;
+  }
+
+  template<typename ...Arg_Ts>
+  inline Object Object::call(Identifier id, Arg_Ts... args) const
+  {
+    /* IMPORTANT - We store VALUEs in an array that is a local variable.
+       That allows the Ruby garbage collector to find them when scanning
+       the stack and thus mark them. If instead we use a vector, then Ruby's GC
+       can't find the VALUEs and may garbage collect them before they are sent
+       to the destination method resulting in a segmentation fault. This is
+       easy to duplicate by setting GC.stress to true and calling a constructor
+       that takes multiple values like a std::pair wrapper. */
+    std::array<VALUE, sizeof...(Arg_Ts)> values = { detail::To_Ruby<detail::remove_cv_recursive_t<Arg_Ts>>().convert(std::forward<Arg_Ts>(args))... };
+    return detail::protect(rb_funcallv, value(), id.id(), (int)values.size(), (const VALUE*)values.data());
+  }
+
+  template<typename ...Arg_Ts>
+  inline Object Object::call_kw(Identifier id, Arg_Ts... args) const
+  {
+    /* IMPORTANT - See call() above */
+    std::array<VALUE, sizeof...(Arg_Ts)> values = { detail::To_Ruby<detail::remove_cv_recursive_t<Arg_Ts>>().convert(args)... };
+    return detail::protect(rb_funcallv_kw, value(), id.id(), (int)values.size(), (const VALUE*)values.data(), RB_PASS_KEYWORDS);
+  }
+
+  template<typename T>
+  inline void Object::iv_set(Identifier name, T const& value)
+  {
+    detail::protect(rb_ivar_set, this->value(), name.id(), detail::To_Ruby<T>().convert(value));
+  }
+
+  inline int Object::compare(Object const& other) const
+  {
+    Object result = call("<=>", other);
+    return detail::From_Ruby<int>().convert(result);
+  }
+
+  inline bool Object::is_equal(const Object& other) const
+  {
+    VALUE result = detail::protect(rb_equal, this->value_, other.value_);
+    return RB_TEST(result);
+  }
+
+  inline bool Object::is_eql(const Object& other) const
+  {
+    VALUE result = detail::protect(rb_eql, this->value_, other.value_);
+    return RB_TEST(result);
+  }
+
+  inline void Object::freeze()
+  {
+    detail::protect(rb_obj_freeze, value());
+  }
+
+  inline bool Object::is_frozen() const
+  {
+    return RB_OBJ_FROZEN(value());
+  }
+
+  inline int Object::rb_type() const
+  {
+    return ::rb_type(this->value());
+  }
+
+  inline VALUE Object::object_id() const
+  {
+    return detail::protect(rb_obj_id, this->value());
+  }
+
+  inline bool Object::is_a(Object klass) const
+  {
+    VALUE result = detail::protect(rb_obj_is_kind_of, this->value(), klass.value());
+    return RB_TEST(result);
+  }
+
+  inline bool Object::respond_to(Identifier id) const
+  {
+    return bool(rb_respond_to(this->value(), id.id()));
+  }
+
+  inline bool Object::is_instance_of(Object klass) const
+  {
+    VALUE result = detail::protect(rb_obj_is_instance_of, this->value(), klass.value());
+    return RB_TEST(result);
+  }
+
+  inline Object Object::iv_get(Identifier name) const
+  {
+    return detail::protect(rb_ivar_get, this->value(), name.id());
+  }
+
+  inline Object Object::attr_get(Identifier name) const
+  {
+    return detail::protect(rb_attr_get, this->value(), name.id());
+  }
+
+  inline void Object::set_value(VALUE v)
+  {
+    value_ = v;
+  }
+
+  inline Object Object::const_get(Identifier name) const
+  {
+    return detail::protect(rb_const_get, this->value(), name.id());
+  }
+
+  inline bool Object::const_defined(Identifier name) const
+  {
+    size_t result = detail::protect(rb_const_defined, this->value(), name.id());
+    return bool(result);
+  }
+
+  inline Object Object::const_set(Identifier name, Object value)
+  {
+    detail::protect(rb_const_set, this->value(), name.id(), value.value());
+    return value;
+  }
+
+  inline Object Object::const_set_maybe(Identifier name, Object value)
+  {
+    if (!this->const_defined(name))
+    {
+      this->const_set(name, value);
+    }
+    return value;
+  }
+
+  inline void Object::remove_const(Identifier name)
+  {
+    detail::protect(rb_mod_remove_const, this->value(), name.to_sym());
+  }
+
+  inline bool operator==(Object const& lhs, Object const& rhs)
+  {
+    VALUE result = detail::protect(rb_equal, lhs.value(), rhs.value());
+    return result == Qtrue ? true : false;
+  }
+
+  inline bool operator!=(Object const& lhs, Object const& rhs)
+  {
+    return !(lhs == rhs);
+  }
+
+  inline bool operator<(Object const& lhs, Object const& rhs)
+  {
+    Object result = lhs.call("<", rhs);
+    return result.test();
+  }
+
+  inline bool operator>(Object const& lhs, Object const& rhs)
+  {
+    Object result = lhs.call(">", rhs);
+    return result.test();
+  }
+}
+
+namespace Rice::detail
+{
+  template<>
+  struct Type<Object>
+  {
+    static bool verify()
+    {
+      return true;
+    }
+  };
+
+  template<>
+  class To_Ruby<Object>
+  {
+  public:
+    static VALUE convert(Object const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class To_Ruby<Object&>
+  {
+  public:
+    static VALUE convert(Object const& x)
+    {
+      return x.value();
+    }
+  };
+
+  template<>
+  class From_Ruby<Object>
+  {
+  public:
+    Convertible is_convertible(VALUE value)
+    {
+      switch (rb_type(value))
+      {
+        case RUBY_T_OBJECT:
+          return Convertible::Exact;
+          break;
+        default:
+          return Convertible::None;
+      }
+    }
+
+    Object convert(VALUE value)
+    {
+      return Object(value);
+    }
+  };
+}