Struct rutie::Module

pub struct Module { /* fields omitted */ }

Module

Also see def, def_self, define and some more functions from Object trait.

#[macro_use] extern crate rutie;

use std::error::Error;

use rutie::{Module, Fixnum, Object, Exception, VM};

module!(Example);

methods!(
   Example,
   itself,

    fn square(exp: Fixnum) -> Fixnum {
        // `exp` is not a valid `Fixnum`, raise an exception
        if let Err(ref error) = exp {
            VM::raise(error.class(), &error.message());
        }

        // We can safely unwrap here, because an exception was raised if `exp` is `Err`
        let exp = exp.unwrap().to_i64();

        Fixnum::new(exp * exp)
    }
);

fn main() {
    Module::new("Example").define(|itself| {
        itself.def("square", square);
    });
}

Ruby:

module Example
  def square(exp)
    raise TypeError unless exp.is_a?(Fixnum)

    exp * exp
  end
end

Methods

impl Module

pub fn new(name: &str) -> Self

Creates a new Module.

Examples

use rutie::{Module, VM};

let basic_record_module = Module::new("BasicRecord");

assert_eq!(basic_record_module, Module::from_existing("BasicRecord"));

Ruby:

module BasicRecord
end

pub fn from_existing(name: &str) -> Self

Retrieves an existing Module object.

Examples

use rutie::{Module, VM};

let module = Module::new("Record");

assert_eq!(module, Module::from_existing("Record"));

Ruby:

module Record
end

# get module

Record

# or

Object.const_get('Record')

pub fn ancestors(&self) -> Vec<Module>

Returns a Vector of ancestors of current module

Examples

Getting all the ancestors

use rutie::{Module, VM};

let process_module_ancestors = Module::from_existing("Process").ancestors();

let expected_ancestors = vec![
    Module::from_existing("Process")
];

assert_eq!(process_module_ancestors, expected_ancestors);

Searching for an ancestor

use rutie::{Module, VM};

let record_module = Module::new("Record");

let ancestors = record_module.ancestors();

assert!(ancestors.iter().any(|module| *module == record_module));

pub fn get_nested_module(&self, name: &str) -> Self

Retrieves a Module nested to current Module.

Examples

use rutie::{Module, Object, VM};

Module::new("Outer").define(|itself| {
    itself.define_nested_module("Inner");
});

Module::from_existing("Outer").get_nested_module("Inner");

Ruby:

module Outer
  module Inner
  end
end

Outer::Inner

# or

Outer.const_get('Inner')

pub fn get_nested_class(&self, name: &str) -> Class

Retrieves a Class nested to current Module.

Examples

use rutie::{Class, Module, Object, VM};

Module::new("Outer").define(|itself| {
    itself.define_nested_class("Inner", None);
});

Module::from_existing("Outer").get_nested_class("Inner");

Ruby:

module Outer
  class Inner
  end
end

Outer::Inner

# or

Outer.const_get('Inner')

pub fn define_nested_module(&mut self, name: &str) -> Self

Creates a new Module nested into current Module.

Examples

use rutie::{Module, Object, VM};

Module::new("Outer").define(|itself| {
    itself.define_nested_module("Inner");
});

Module::from_existing("Outer").get_nested_module("Inner");

Ruby:

module Outer
  module Inner
  end
end

Outer::Inner

# or

Outer.const_get('Inner')

pub fn define_nested_class(
    &mut self,
    name: &str,
    superclass: Option<&Class>
) -> Class

Creates a new Class nested into current module.

Examples

use rutie::{Class, Module, Object, VM};

Module::new("Outer").define(|itself| {
    itself.define_nested_class("Inner", None);
});

Module::from_existing("Outer").get_nested_class("Inner");

Ruby:

module Outer
  class Inner
  end
end

Outer::Inner

# or

Outer.const_get('Inner')

pub fn define_module_function<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

Defines an instance method for the given module.

Use methods! macro to define a callback.

You can also use def() alias for this function combined with Module::define() for a nicer DSL.

Panics

Ruby can raise an exception if you try to define instance method directly on an instance of some class (like Fixnum, String, Array etc).

Use this method only on classes (or singleton classes of objects).

Examples

The famous String#blank? method

#[macro_use] extern crate rutie;

use rutie::{Boolean, Module, Class, Object, RString, VM};

methods!(
   RString,
   itself,

   fn is_blank() -> Boolean {
       Boolean::new(itself.to_str().chars().all(|c| c.is_whitespace()))
   }
);

fn main() {
    Module::new("Blank").define(|itself| {
        itself.mod_func("blank?", is_blank);
    });

    Class::from_existing("String").include("Blank");
}

Ruby:

module Blank
  def blank?
    # simplified
    self.chars.all? { |c| c == ' ' }
  end
  module_function :blank?
end

String.include Blank

Receiving arguments

Raise Fixnum to the power of exp.

#[macro_use] extern crate rutie;

use std::error::Error;

use rutie::{Module, Fixnum, Object, Exception, VM};

methods!(
    Fixnum,
    itself,

    fn pow(exp: Fixnum) -> Fixnum {
        // `exp` is not a valid `Fixnum`, raise an exception
        if let Err(ref error) = exp {
            VM::raise(error.class(), &error.message());
        }

        // We can safely unwrap here, because an exception was raised if `exp` is `Err`
        let exp = exp.unwrap().to_i64() as u32;

        Fixnum::new(itself.to_i64().pow(exp))
    }

    fn pow_with_default_argument(exp: Fixnum) -> Fixnum {
        let default_exp = 0;
        let exp = exp.map(|exp| exp.to_i64()).unwrap_or(default_exp);

        let result = itself.to_i64().pow(exp as u32);

        Fixnum::new(result)
    }
);

fn main() {
    Module::from_existing("Fixnum").define(|itself| {
        itself.mod_func("pow", pow);
        itself.mod_func("pow_with_default_argument", pow_with_default_argument);
    });
}

Ruby:

module Fixnum
  def pow(exp)
    raise ArgumentError unless exp.is_a?(Fixnum)

    self ** exp
  end
  module_function :pow

  def pow_with_default_argument(exp)
    default_exp = 0
    exp = default_exp unless exp.is_a?(Fixnum)

    self ** exp
  end
  module_function :pow_with_default_argument
end

pub fn mod_func<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

An alias for define_module_function (similar to Ruby module_function :some_method).

pub fn const_get(&self, name: &str) -> AnyObject

Retrieves a constant from module.

Examples

use rutie::{Module, Object, RString, VM};

Module::new("Greeter").define(|itself| {
    itself.const_set("GREETING", &RString::new_utf8("Hello, World!"));
});

let greeting = Module::from_existing("Greeter")
    .const_get("GREETING")
    .try_convert_to::<RString>()
    .unwrap();

assert_eq!(greeting.to_str(), "Hello, World!");

Ruby:

module Greeter
  GREETING = 'Hello, World!'
end

# or

Greeter = Module.new
Greeter.const_set('GREETING', 'Hello, World!')

# ...

Greeter::GREETING == 'Hello, World!'

# or

Greeter.const_get('GREETING') == 'Hello, World'

pub fn const_set<T: Object>(&mut self, name: &str, value: &T)

Defines a constant for module.

Examples

use rutie::{Module, Object, RString, VM};

Module::new("Greeter").define(|itself| {
    itself.const_set("GREETING", &RString::new_utf8("Hello, World!"));
});

let greeting = Module::from_existing("Greeter")
    .const_get("GREETING")
    .try_convert_to::<RString>()
    .unwrap();

assert_eq!(greeting.to_str(), "Hello, World!");

Ruby:

module Greeter
  GREETING = 'Hello, World!'
end

# or

Greeter = Module.new
Greeter.const_set('GREETING', 'Hello, World!')

# ...

Greeter::GREETING == 'Hello, World!'

# or

Greeter.const_get('GREETING') == 'Hello, World'

pub fn include(&self, md: &str)

Includes module into current module

Examples

use rutie::{Module, VM};

Module::new("A");
Module::new("B").include("A");

let b_module_ancestors = Module::from_existing("B").ancestors();

let expected_ancestors = vec![
    Module::from_existing("B"),
    Module::from_existing("A")
];

assert_eq!(b_module_ancestors, expected_ancestors);

pub fn prepend(&self, md: &str)

Prepends module into current module

Examples

use rutie::{Module, VM};

Module::new("A");
Module::new("B").prepend("A");

let b_module_ancestors = Module::from_existing("B").ancestors();

let expected_ancestors = vec![
    Module::from_existing("A"),
    Module::from_existing("B")
];

assert_eq!(b_module_ancestors, expected_ancestors);

pub fn attr_reader(&mut self, name: &str)

Defines an attr_reader for module

Examples

use rutie::{Module, Object, VM};

Module::new("Test").define(|itself| {
    itself.attr_reader("reader");
});

Ruby:

module Test
  attr_reader :reader
end

pub fn attr_writer(&mut self, name: &str)

Defines an attr_writer for module

Examples

use rutie::{Module, Object, VM};

Module::new("Test").define(|itself| {
    itself.attr_writer("writer");
});

Ruby:

module Test
  attr_writer :writer
end

pub fn attr_accessor(&mut self, name: &str)

Defines an attr_accessor for module

Examples

use rutie::{Module, Object, VM};

Module::new("Test").define(|itself| {
    itself.attr_accessor("accessor");
});

Ruby:

module Test
  attr_accessor :accessor
end

pub fn wrap_data<T, O: Object>(
    &self,
    data: T,
    wrapper: &dyn DataTypeWrapper<T>
) -> O

Wraps Rust structure into a new Ruby object of the current module.

See the documentation for wrappable_struct! macro for more information.

Examples

Wrap Server structs to RubyServer objects. Note: Example shows use with class but the method still applies to module.

#[macro_use] extern crate rutie;
#[macro_use] extern crate lazy_static;

use rutie::{AnyObject, Class, Fixnum, Object, RString, VM};

// The structure which we want to wrap
pub struct Server {
    host: String,
    port: u16,
}

impl Server {
    fn new(host: String, port: u16) -> Self {
        Server {
            host: host,
            port: port,
        }
    }

    fn host(&self) -> &str {
        &self.host
    }

    fn port(&self) -> u16 {
        self.port
    }
}

wrappable_struct!(Server, ServerWrapper, SERVER_WRAPPER);

class!(RubyServer);

methods!(
    RubyServer,
    itself,

    fn ruby_server_new(host: RString, port: Fixnum) -> AnyObject {
        let server = Server::new(host.unwrap().to_string(),
                                 port.unwrap().to_i64() as u16);

        Class::from_existing("RubyServer").wrap_data(server, &*SERVER_WRAPPER)
    }

    fn ruby_server_host() -> RString {
        let host = itself.get_data(&*SERVER_WRAPPER).host();

        RString::new_utf8(host)
    }

    fn ruby_server_port() -> Fixnum {
        let port = itself.get_data(&*SERVER_WRAPPER).port();

        Fixnum::new(port as i64)
    }
);

fn main() {
    let data_class = Class::from_existing("Object");

    Class::new("RubyServer", None).define(|itself| {
        itself.def_self("new", ruby_server_new);

        itself.def("host", ruby_server_host);
        itself.def("port", ruby_server_port);
    });
}

To use the RubyServer class in Ruby:

server = RubyServer.new("127.0.0.1", 3000)

server.host == "127.0.0.1"
server.port == 3000

Trait Implementations

impl Object for Module

fn value(&self) -> Value

Returns internal value of current object.

fn class(&self) -> Class

Returns a class of current object.

fn singleton_class(&self) -> Class

Returns a singleton class of current object.

fn get_data<'a, T>(&'a self, wrapper: &'a dyn DataTypeWrapper<T>) -> &T

Gets an immutable reference to the Rust structure which is wrapped into a Ruby object.

fn get_data_mut<'a, T>(
    &'a mut self,
    wrapper: &'a dyn DataTypeWrapper<T>
) -> &mut T

Gets a mutable reference to the Rust structure which is wrapped into a Ruby object.

fn define<F: Fn(&mut Self)>(&mut self, f: F) -> &Self

Wraps calls to the object.

fn define_method<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

Defines an instance method for the given class or object.

fn define_private_method<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

Defines a private instance method for the given class or object.

fn define_singleton_method<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

Defines a class method for given class or singleton method for object.

fn def<I: Object, O: Object>(&mut self, name: &str, callback: Callback<I, O>)

An alias for define_method (similar to Ruby syntax def some_method).

fn def_private<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

An alias for define_private_method (similar to Ruby syntax private def some_method).

fn def_self<I: Object, O: Object>(
    &mut self,
    name: &str,
    callback: Callback<I, O>
)

An alias for define_singleton_method (similar to Ruby def self.some_method).

unsafe fn send(&self, method: &str, arguments: &[AnyObject]) -> AnyObject

Calls a given method on an object similarly to Ruby Object#send method

fn equals<T: Object>(&self, other: &T) -> bool

Alias for Ruby's ==

fn case_equals<T: Object>(&self, other: &T) -> bool

Alias for Ruby's ===

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

Alias for Ruby's eql?

fn is_equal<T: Object>(&self, other: &T) -> bool

Alias for Ruby's equal?

fn respond_to(&self, method: &str) -> bool

Checks whether the object responds to given method

fn protect_send(
    &self,
    method: &str,
    arguments: &[AnyObject]
) -> Result<AnyObject, AnyException>

protect_send returns Result<AnyObject, AnyObject>

fn protect_public_send(
    &self,
    method: &str,
    arguments: &[AnyObject]
) -> Result<AnyObject, AnyException>

protect_public_send returns Result<AnyObject, AnyObject>

fn is_nil(&self) -> bool

Checks whether the object is nil

fn to_any_object(&self) -> AnyObject

Converts struct to AnyObject

fn instance_variable_get(&self, variable: &str) -> AnyObject

Gets an instance variable of object

fn instance_variable_set<T: Object>(
    &mut self,
    variable: &str,
    value: T
) -> AnyObject

Sets an instance variable for object

fn is_frozen(&self) -> bool

Returns the freeze status of the object.

fn freeze(&mut self) -> Self

Prevents further modifications to the object.

unsafe fn to<T: Object>(&self) -> T

Unsafely casts current object to the specified Ruby type

fn try_convert_to<T: VerifiedObject>(&self) -> Result<T, AnyException>

Safely casts current object to the specified Ruby type

fn ty(&self) -> ValueType

Determines the value type of the object

impl VerifiedObject for Module

fn is_correct_type<T: Object>(object: &T) -> bool

fn error_message() -> &'static str

impl From<Value> for Module

fn from(value: Value) -> Self

Performs the conversion.

impl Into<Value> for Module

fn into(self) -> Value

Performs the conversion.

impl Into<AnyObject> for Module

fn into(self) -> AnyObject

Performs the conversion.

impl PartialEq<Module> for Module

fn eq(&self, other: &Self) -> 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 Debug for Module

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

Formats the value using the given formatter.