Trait koto_runtime::prelude::KotoObject

pub trait KotoObject: KotoType + KotoCopy + KotoEntries + KotoSend + KotoSync + Downcast {
    // Provided methods
    fn display(&self, ctx: &mut DisplayContext<'_>) -> Result<()> { ... }
    fn index(&self, _index: &KValue) -> Result<KValue> { ... }
    fn size(&self) -> Option<usize> { ... }
    fn call(&mut self, _ctx: &mut CallContext<'_>) -> Result<KValue> { ... }
    fn negate(&self, _vm: &mut KotoVm) -> Result<KValue> { ... }
    fn add(&self, _rhs: &KValue) -> Result<KValue> { ... }
    fn subtract(&self, _rhs: &KValue) -> Result<KValue> { ... }
    fn multiply(&self, _rhs: &KValue) -> Result<KValue> { ... }
    fn divide(&self, _rhs: &KValue) -> Result<KValue> { ... }
    fn remainder(&self, _rhs: &KValue) -> Result<KValue> { ... }
    fn add_assign(&mut self, _rhs: &KValue) -> Result<()> { ... }
    fn subtract_assign(&mut self, _rhs: &KValue) -> Result<()> { ... }
    fn multiply_assign(&mut self, _rhs: &KValue) -> Result<()> { ... }
    fn divide_assign(&mut self, _rhs: &KValue) -> Result<()> { ... }
    fn remainder_assign(&mut self, _rhs: &KValue) -> Result<()> { ... }
    fn less(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn less_or_equal(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn greater(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn greater_or_equal(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn equal(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn not_equal(&self, _rhs: &KValue) -> Result<bool> { ... }
    fn is_iterable(&self) -> IsIterable { ... }
    fn make_iterator(&self, _vm: &mut KotoVm) -> Result<KIterator> { ... }
    fn iterator_next(&mut self, _vm: &mut KotoVm) -> Option<KIteratorOutput> { ... }
    fn iterator_next_back(
        &mut self,
        _vm: &mut KotoVm
    ) -> Option<KIteratorOutput> { ... }
}

A trait for implementing objects that can be added to the Koto runtime

KotoObjects are added to the Koto runtime by the KObject type, and stored as KValue::Objects.

Example

use koto_runtime::{derive::*, prelude::*, Result};

#[derive(Clone, Default, KotoType, KotoCopy)]
pub struct Foo {
    data: i32,
}

// The `#[koto_impl]` macro derives an implementation of [KotoEntries] containing wrapper
// functions for each impl function tagged with `#[koto_method]`.
#[koto_impl(runtime = koto_runtime)]
impl Foo {
    // Simple methods tagged with `#[koto_method]` can use a `&self` argument.
    #[koto_method(alias = "data")]
    fn get_data(&self) -> KValue {
        self.data.into()
    }

    // An example of a more complex method that makes use of [MethodContext] to return the
    // instance as the result, which allows for chaining of setter operations.  e.g.:
    // ```koto
    // make_foo(42)
    //  .set_data(99)
    //  .set_data(-1)
    //  .get_data()
    // # -1
    // ```
    #[koto_method]
    fn set_data(ctx: MethodContext<Self>) -> Result<KValue> {
        match ctx.args {
            [KValue::Number(n)] => ctx.instance_mut()?.data = n.into(),
            unexpected => return type_error_with_slice("a Number", unexpected),
        }

        // Return the object instance as the result of the setter operation
        ctx.instance_result()
    }
}

impl KotoObject for Foo {
    fn display(&self, ctx: &mut DisplayContext) -> Result<()> {
        ctx.append(format!("Foo({})", self.data));
        Ok(())
    }
}

See also: KObject.

Provided Methods

fn display(&self, ctx: &mut DisplayContext<'_>) -> Result<()>

Called when the object should be displayed as a string, e.g. by io.print

By default, the object’s type is used as the display string.

The DisplayContext is used to append strings to the result, and also provides context about any parent containers.

fn index(&self, _index: &KValue) -> Result<KValue>

Called for indexing operations, e.g. x[0]

See also: KotoObject::size

fn size(&self) -> Option<usize>

Called when checking for the number of elements contained in the object

The runtime defers to this function when the ‘size’ of an object is needed e.g. when koto.size is called, or when unpacking function arguments.

The size should represent the maximum valid index that can be passed to KotoObject::index.

See also: KotoObject::index

fn call(&mut self, _ctx: &mut CallContext<'_>) -> Result<KValue>

Allows the object to behave as a function

fn negate(&self, _vm: &mut KotoVm) -> Result<KValue>

Defines the behavior of negation (e.g. -x)

fn add(&self, _rhs: &KValue) -> Result<KValue>

The + addition operator ()

fn subtract(&self, _rhs: &KValue) -> Result<KValue>

The - subtraction operator

fn multiply(&self, _rhs: &KValue) -> Result<KValue>

The * multiplication operator

fn divide(&self, _rhs: &KValue) -> Result<KValue>

The / division operator

fn remainder(&self, _rhs: &KValue) -> Result<KValue>

The % remainder operator

fn add_assign(&mut self, _rhs: &KValue) -> Result<()>

The += in-place addition operator

fn subtract_assign(&mut self, _rhs: &KValue) -> Result<()>

The -= in-place subtraction operator

fn multiply_assign(&mut self, _rhs: &KValue) -> Result<()>

The *= in-place multiplication operator

fn divide_assign(&mut self, _rhs: &KValue) -> Result<()>

The /= in-place division operator

fn remainder_assign(&mut self, _rhs: &KValue) -> Result<()>

The %= in-place remainder operator

fn less(&self, _rhs: &KValue) -> Result<bool>

The < less-than operator

fn less_or_equal(&self, _rhs: &KValue) -> Result<bool>

The <= less-than-or-equal operator

fn greater(&self, _rhs: &KValue) -> Result<bool>

The > greater-than operator

fn greater_or_equal(&self, _rhs: &KValue) -> Result<bool>

The >= greater-than-or-equal operator

fn equal(&self, _rhs: &KValue) -> Result<bool>

The == equality operator

fn not_equal(&self, _rhs: &KValue) -> Result<bool>

The != inequality operator

fn is_iterable(&self) -> IsIterable

Declares to the runtime whether or not the object is iterable

fn make_iterator(&self, _vm: &mut KotoVm) -> Result<KIterator>

Returns an iterator that iterates over the objects contents

If IsIterable::Iterable is returned from is_iterable, then the runtime will call this function when the object is used in iterable contexts, expecting a KIterator to be returned.

fn iterator_next(&mut self, _vm: &mut KotoVm) -> Option<KIteratorOutput>

Gets the object’s next value in an iteration

If either ForwardIterator or BidirectionalIterator is returned from is_iterable, then the object will be wrapped in a KIterator whenever it’s used in an iterable context. This function will then be called each time KIterator::next is invoked.

fn iterator_next_back(&mut self, _vm: &mut KotoVm) -> Option<KIteratorOutput>

Gets the object’s next value from the end of an iteration

If BidirectionalIterator is returned from is_iterable, then the object will be wrapped in a KIterator whenever it’s used in an iterable context. This function will then be called each time KIterator::next_back is invoked.

Implementations

impl dyn KotoObject

pub fn is<__T: KotoObject>(&self) -> bool

Returns true if the trait object wraps an object of type __T.

pub fn downcast<__T: KotoObject>(self: Box<Self>) -> Result<Box<__T>, Box<Self>>

Returns a boxed object from a boxed trait object if the underlying object is of type __T. Returns the original boxed trait if it isn’t.

pub fn downcast_rc<__T: KotoObject>(self: Rc<Self>) -> Result<Rc<__T>, Rc<Self>>

Returns an Rc-ed object from an Rc-ed trait object if the underlying object is of type __T. Returns the original Rc-ed trait if it isn’t.

pub fn downcast_ref<__T: KotoObject>(&self) -> Option<&__T>

Returns a reference to the object within the trait object if it is of type __T, or None if it isn’t.

pub fn downcast_mut<__T: KotoObject>(&mut self) -> Option<&mut __T>

Returns a mutable reference to the object within the trait object if it is of type __T, or None if it isn’t.

Implementors

impl KotoObject for File

impl KotoObject for Peekable

impl KotoObject for IteratorOutput

impl KotoObject for Chunk

impl KotoObject for DateTime

impl KotoObject for Timer