rice 4.5.0 → 4.6.0

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);
+    }
+  };
+}

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);
+    }
+  };
+}