Struct rosy::Class

#[repr(transparent)]
pub struct Class<O = AnyObject> { /* fields omitted */ }

An instance of Ruby's Class type.

Examples

Class inheritance can be expressed in terms of logical comparison operators:

use rosy::Class;

assert!(Class::object()    < Class::basic_object());
assert!(Class::exception() < Class::object());
assert!(Class::arg_error() < Class::exception());

This very closely resembles Ruby's syntax for subclassing:

class Mammal
  def breathe
    puts "inhale and exhale"
  end
end

class Cat < Mammal
  def speak
    puts "meow"
  end
end

Methods

impl Class

pub fn of<O: Classify>() -> Class<O>

Returns the typed class of some type that implements Classify.

Examples

We can see from getting the untyped version of the Array class that they both point to the same class:

use rosy::{Array, Class};

let class = Class::of::<Array>();
assert_eq!(class, Class::array());

pub fn def(name: impl Into<SymbolId>) -> Result<Self, DefMixinError>

Defines a new top-level class with name.

Examples

Defining a new class is straightforward:

let my_object = rosy::Class::def("MyObject").unwrap();

Attempting to define an existing class will result in an error:

use rosy::Class;

let array = Class::def("Array").unwrap_err().existing_object();
assert_eq!(Class::array(), array.unwrap());

pub fn get(name: impl Into<SymbolId>) -> Option<Self>

Retrieves an existing top-level Class defined by name.

pub unsafe fn get_unchecked(name: impl Into<SymbolId>) -> Self

Retrieves an existing top-level Class defined by name.

Safety

This method does not:

• Check whether an item for name exists (an exception will be thrown if this is the case)
• Check whether the returned item for name is actually a Class

pub fn get_or_def(name: impl Into<SymbolId>) -> Result<Self, DefMixinError>

Retrieves an existing top-level Class defined by name or defines one if it doesn't exist.

impl<O: Object> Class<O>

pub fn into_any_class(self) -> Class

Converts self into an untyped class.

pub fn new_instance(self) -> Result<O>

Creates a new instance without arguments.

pub unsafe fn new_instance_unchecked(self) -> O

Creates a new instance without arguments.

Safety

An exception may be thrown if the class expected arguments.

pub fn new_instance_with<A: Object>(self, args: &[A]) -> Result<O>

Creates a new instance from args.

pub unsafe fn new_instance_with_unchecked<A: Object>(self, args: &[A]) -> O

Creates a new instance from args.

Safety

An exception may be thrown if the class expected arguments.

pub fn superclass(self) -> Class

Returns the parent class of self.

pub fn subclass(self, name: impl Into<SymbolId>) -> Result<Class, DefMixinError>

Defines a new subclass of self with name.

pub fn subclass_under(
    self,
    namespace: impl Mixin,
    name: impl Into<SymbolId>
) -> Result<Class, DefMixinError>

Defines a subclass of self under namespace with name.

pub fn inheritance<P: Object>(self, other: Class<P>) -> Inheritance

Returns the inheritance relationship between self and other.

pub fn inherits<P: Object>(self, other: Class<P>) -> bool

Returns whether the relationship between self and other is A <= B.

pub fn name(self) -> String

Returns the name of self.

pub fn def_method<N, F>(self, name: N, f: F) -> Result where
    N: Into<SymbolId>,
    F: MethodFn<O>, 

Defines a method for name on self that calls f when invoked.

Note: This method can be unwieldy to use and so it is recommended to instead call the convenience macro def_method!.

About MethodFn

• The first argument is always of type O. This means that if self is a typed class, then no casting is required within the method.

• Up to 15 arguments may be passed. If more or a variable amount is needed, see the below examples.

• They can return any type that implements the Object trait.

• Unfortunately, because MethodFn is defined on extern "C" fn types and these function declarations don't implicitly resolve to those types, an as cast is required for f.

Examples

Every method takes this (equivalent of self) as the first argument, which may be followed by up to 15 arguments.

use rosy::prelude::*;

extern "C" fn my_eql(this: Array, that: AnyObject) -> AnyObject {
    AnyObject::from(this == that)
}
let my_eql: extern fn(_, _) -> _ = my_eql;

Class::of::<Array>()
    .def_method("my_eql?", my_eql)
    .unwrap();

let array: Array = (0..10).collect();
let value = unsafe { array.call_with("my_eql?", &[array]) };

assert!(value.is_true());

Passing in the wrong number of arguments will result in an ArgumentError exception being raised:

let result = unsafe { array.call_protected("my_eql?") };

assert!(result.unwrap_err().is_arg_error());

Variable Arguments

There are two ways of taking in a variable number of arguments.

The first is by taking a pointer and a length:

use std::os::raw::c_int;
use std::slice::from_raw_parts;
use rosy::prelude::*;

unsafe extern "C" fn eq_all(this: AnyObject, len: c_int, ptr: *const AnyObject) -> AnyObject {
    let slice = from_raw_parts(ptr, len as usize);
    for &obj in slice {
        if obj != this {
            return false.into();
        }
    }
    true.into()
}

let class = Class::string();
let string = String::from("hellooo");

class.def_method("eq_all?", eq_all as unsafe extern fn(_, _, _) -> _);

let args = [string, String::from("byeee")];
let value = unsafe { string.call_with("eq_all?", &args) };

assert!(value.is_false());

The second is by taking an Array as an argument:

use rosy::prelude::*;

unsafe extern "C" fn joining(this: String, args: Array) -> String {
    args.join(this)
}
let joining: unsafe extern fn(_, _) -> _ = joining;

let class = Class::of::<String>();
class.def_method("joining", joining).unwrap();

let string = String::from(", ");
let joined = unsafe { string.call_with("joining", &[string, string]) };

assert_eq!(joined, ", , , ");

pub unsafe fn def_method_unchecked<N, F>(self, name: N, f: F) where
    N: Into<SymbolId>,
    F: MethodFn<O>, 

Defines a method for name on self that calls f when invoked.

Note: This method can be unwieldy to use and so it is recommended to instead call the convenience macro def_method_unchecked!.

See def_method for usage info.

Safety

The caller must ensure that self is not frozen or else a FrozenError exception will be raised.

impl Class

Built-in classes.

pub fn rust_object() -> Self

Returns the RustObject class.

This class can be used when simply wrapping Rust data.

pub fn basic_object() -> Self

The BasicObject class.

pub fn object() -> Self

The Object class.

pub fn array() -> Self

The Array class.

pub fn binding() -> Self

The Binding class.

pub fn class() -> Self

The Class class.

pub fn cont() -> Self

The Cont class.

pub fn data() -> Self

The Data class.

pub fn dir() -> Self

The Dir class.

pub fn encoding() -> Self

The Encoding class.

pub fn enumerator() -> Self

The Enumerator class.

pub fn false_class() -> Self

The FalseClass class.

pub fn file() -> Self

The File class.

pub fn complex() -> Self

The Complex class.

pub fn float() -> Self

The Float class.

pub fn hash() -> Self

The Hash class.

pub fn io() -> Self

The IO class.

pub fn integer() -> Self

The Integer class.

pub fn mtch() -> Self

The Match class.

pub fn method() -> Self

The Method class.

pub fn module() -> Self

The Module class.

pub fn name_error_msg() -> Self

The NameErrorMesg class.

pub fn nil() -> Self

The NilClass class.

pub fn numeric() -> Self

The Numeric class.

pub fn proc() -> Self

The Proc class.

pub fn random() -> Self

The Random class.

pub fn range() -> Self

The Range class.

pub fn rational() -> Self

The Rational class.

pub fn regexp() -> Self

The Regexp class.

pub fn stat() -> Self

The Stat class.

pub fn string() -> Self

The String class.

pub fn strukt() -> Self

The Struct class.

pub fn symbol() -> Self

The Symbol class.

pub fn thread() -> Self

The Thread class.

pub fn time() -> Self

The Time class.

pub fn true_class() -> Self

The TrueClass class.

pub fn unbound_method() -> Self

The UnboundMethod class.

pub fn ruby_vm() -> Self

The RubyVM class.

pub fn instr_seq() -> Self

The RubyVM::InstructionSequence class.

pub fn exception() -> Self

The Exception class.

pub fn standard_error() -> Self

The StandardError class.

pub fn system_exit() -> Self

The SystemExit class.

pub fn interrupt() -> Self

The Interrupt class.

pub fn signal() -> Self

The Signal class.

pub fn fatal() -> Self

The Fatal class.

pub fn arg_error() -> Self

The ArgumentError class.

pub fn eof_error() -> Self

The EOFError class.

pub fn index_error() -> Self

The IndexError class.

pub fn stop_iteration() -> Self

The StopIteration class.

pub fn key_error() -> Self

The KeyError class.

pub fn range_error() -> Self

The RangeError class.

pub fn io_error() -> Self

The IOError class.

pub fn runtime_error() -> Self

The RuntimeError class.

pub fn frozen_error() -> Self

The FrozenError class.

pub fn security_error() -> Self

The SecurityError class.

pub fn system_call_error() -> Self

The SystemCallError class.

pub fn thread_error() -> Self

The ThreadError class.

pub fn type_error() -> Self

The TypeError class.

pub fn zero_div_error() -> Self

The ZeroDivError class.

pub fn not_imp_error() -> Self

The NotImpError class.

pub fn no_mem_error() -> Self

The NoMemError class.

pub fn no_method_error() -> Self

The NoMethodError class.

pub fn float_domain_error() -> Self

The FloatDomainError class.

pub fn local_jump_error() -> Self

The LocalJumpError class.

pub fn sys_stack_error() -> Self

The SysStackError class.

pub fn regexp_error() -> Self

The RegexpError class.

pub fn encoding_error() -> Self

The EncodingError class.

pub fn enc_compat_error() -> Self

The EncCompatError class.

pub fn script_error() -> Self

The ScriptError class.

pub fn name_error() -> Self

The NameError class.

pub fn syntax_error() -> Self

The SyntaxError class.

pub fn load_error() -> Self

The LoadError class.

pub fn math_domain_error() -> Self

The MathDomainError class.

Trait Implementations

impl Classify for Class

fn class() -> Class<Self>

Returns the typed class that can be used to get an instance of self.

impl Mixin for Class

fn to_class(self) -> Result<Class, Module>

Returns self as a Class if it is one or a Module otherwise.

fn to_module(self) -> Result<Module, Class>

Returns self as a Module if it is one or a Class otherwise.

fn include(self, module: Module)

Embeds the contents of module in self.

#[must_use]

fn includes(self, module: Module) -> bool

Returns whether self or one of its ancestors includes module.

fn included_modules(self) -> Array<Module>

Returns an array of the modules included in self.

fn prepend(self, module: Module)

Prepends module in self.

fn def_class(self, name: impl Into<SymbolId>) -> Result<Class, DefMixinError>

Defines a new class under self with name.

fn def_subclass<S: Object>(
    self,
    superclass: Class<S>,
    name: impl Into<SymbolId>
) -> Result<Class, DefMixinError>

Defines a new subclass of superclass under self with name.

fn get_class(self, name: impl Into<SymbolId>) -> Option<Class>

Returns the existing Class with name in self.

unsafe fn get_class_unchecked(self, name: impl Into<SymbolId>) -> Class

Returns the existing Class with name in self.

fn def_module(self, name: impl Into<SymbolId>) -> Result<Module, DefMixinError>

Defines a new module under self with name.

fn get_module(self, name: impl Into<SymbolId>) -> Option<Module>

Returns the existing Module with name in self.

unsafe fn get_module_unchecked(self, name: impl Into<SymbolId>) -> Module

Returns the existing Module with name in self.

fn has_const(self, name: impl Into<SymbolId>) -> bool

Returns whether a constant for name is defined in self, or in some parent class if not self.

fn get_const(self, name: impl Into<SymbolId>) -> AnyObject

Returns the constant value for name in self, or in some parent class if not self.

fn set_const(self, name: impl Into<SymbolId>, val: impl Into<AnyObject>)

Sets the value a constant for name in self to val.

fn remove_const(self, name: impl Into<SymbolId>) -> AnyObject

Removes the constant value for name, returning it.

fn has_class_var(self, var: impl Into<SymbolId>) -> bool

Returns whether the class-level var is defined in self.

fn get_class_var(self, var: impl Into<SymbolId>) -> AnyObject

Returns the class-level var in self.

fn set_class_var<K, V>(self, key: K, val: V) -> Result where
    K: Into<SymbolId>,
    V: Into<AnyObject>, 

Sets the class-level var in self to val.

unsafe fn set_class_var_unchecked<K, V>(self, key: K, val: V) where
    K: Into<SymbolId>,
    V: Into<AnyObject>, 

Sets the class-level var for key in self to val.

fn def_attr_reader<N: Into<SymbolId>>(self, name: N) -> Result

Defines an read-only attribute on self with name.

unsafe fn def_attr_reader_unchecked<N: Into<SymbolId>>(self, name: N)

Defines an read-only attribute on self with name.

fn def_attr_writer<N: Into<SymbolId>>(self, name: N) -> Result

Defines a write-only attribute on self with name.

unsafe fn def_attr_writer_unchecked<N: Into<SymbolId>>(self, name: N)

Defines a write-only attribute on self with name.

fn def_attr_accessor<N: Into<SymbolId>>(self, name: N) -> Result

Defines a read-write attribute on self with name.

unsafe fn def_attr_accessor_unchecked<N: Into<SymbolId>>(self, name: N)

Defines a read-write attribute on self with name.

unsafe fn eval(self, args: impl EvalArgs) -> AnyObject

Evaluates args in the context of self.

unsafe fn eval_protected(self, args: impl EvalArgs) -> Result<AnyObject>

Evaluates args in the context of self, returning any raised exceptions.

impl<O: Object> Object for Class<O>

fn unique_id() -> Option<u128>

Returns a unique identifier for an object type to facilitate casting.

fn cast<A: Object>(obj: A) -> Option<Self>

Attempts to create an instance by casting obj.

fn ty(self) -> Ty

Returns the virtual type of self.

fn is_ty(self, ty: Ty) -> bool

Returns whether the virtual type of self is ty.

unsafe fn from_raw(raw: usize) -> Self

Creates a new object from raw without checking.

unsafe fn cast_unchecked(obj: impl Object) -> Self

Casts obj to Self without checking its type.

fn into_any_object(self) -> AnyObject

Returns self as an AnyObject.

fn as_any_object(&self) -> &AnyObject

Returns a reference to self as an AnyObject.

fn as_any_slice(&self) -> &[AnyObject]

Returns self as a reference to a single-element slice.

fn raw(self) -> usize

Returns the raw object pointer.

unsafe fn as_unchecked<O: Object>(&self) -> &O

Casts self to O without checking whether it is one.

unsafe fn into_unchecked<O: Object>(self) -> O

Converts self to O without checking whether it is one.

fn id(self) -> u64

Returns the object's identifier.

fn class(self) -> Class<Self>

Returns the Class for self.

fn singleton_class(self) -> Class<Self>

Returns the singleton Class of self, creating one if it doesn't exist already.

fn mark(self)

Marks self for Ruby to avoid garbage collecting it.

unsafe fn force_recycle(self)

Forces the garbage collector to free the contents of self.

fn def_singleton_method<N, F>(self, name: N, f: F) -> Result where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn def_singleton_method_unchecked<N, F>(self, name: N, f: F) where
    N: Into<SymbolId>,
    F: MethodFn<Self>, 

Defines a method for name on the singleton class of self that calls f when invoked.

unsafe fn call(self, method: impl Into<SymbolId>) -> AnyObject

Calls method on self and returns its output.

unsafe fn call_protected(self, method: impl Into<SymbolId>) -> Result<AnyObject>

Calls method on self and returns its output, or an exception if one is raised.

unsafe fn call_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls method on self with args and returns its output.

unsafe fn call_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls method on self with args and returns its output, or an exception if one is raised.

unsafe fn call_public(self, method: impl Into<SymbolId>) -> AnyObject

Calls the public method on self and returns its output.

unsafe fn call_public_protected(
    self,
    method: impl Into<SymbolId>
) -> Result<AnyObject>

Calls the public method on self and returns its output, or an exception if one is raised.

unsafe fn call_public_with(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> AnyObject

Calls the public method on self with args and returns its output.

unsafe fn call_public_with_protected(
    self,
    method: impl Into<SymbolId>,
    args: &[impl Object]
) -> Result<AnyObject>

Calls the public method on self with args and returns its output, or an exception if one is raised.

fn inspect(self) -> String

Returns a printable string representation of self.

fn to_s(self) -> String

Returns the result of calling the to_s method on self.

fn is_frozen(self) -> bool

Returns whether modifications can be made to self.

fn freeze(self)

Freezes self, preventing any further mutations.

fn is_eql<O: Object>(self, other: &O) -> bool

Returns whether self is equal to other in terms of the eql? method.

fn get_attr<N: Into<SymbolId>>(self, name: N) -> AnyObject

Returns the value for the attribute of self associated with name.

unsafe fn eval(self, args: impl EvalArgs) -> AnyObject

Evaluates args in the context of self.

unsafe fn eval_protected(self, args: impl EvalArgs) -> Result<AnyObject>

Evaluates args in the context of self, returning any raised exceptions.

impl<O: Object> Eq for Class<O>

impl<O: Object, P: Object> PartialEq<P> for Class<O>

fn eq(&self, other: &P) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<O> Copy for Class<O>

impl<O> Clone for Class<O>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<O: Object, P: Object> PartialOrd<Class<P>> for Class<O>

fn partial_cmp(&self, other: &Class<P>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Class<P>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Class<P>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Class<P>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Class<P>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<O: Object> AsRef<AnyObject> for Class<O>

fn as_ref(&self) -> &AnyObject

Performs the conversion.

impl<O: Object> From<Class<O>> for AnyObject

fn from(object: Class<O>) -> AnyObject

Performs the conversion.

impl<O: Object> Debug for Class<O>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<O: Object> Display for Class<O>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.