Struct Host 

pub struct Host<'a> { /* private fields */ }

Safe access to the host VM for the duration of one plugin call.

Methods that run generic bytecode (and may therefore trigger garbage collection) take &mut self: the borrow checker then guarantees the rooting contract’s string rule - any &str obtained from the host borrows self and cannot be held across a re-entering call. Values held across a re-entering call must be rooted, e.g. via Host::rooted.

Implementations

impl<'a> Host<'a>

pub fn kind(&self, value: GenericValue) -> ValueKind

The ValueKind of a value.

pub fn decode(&self, value: GenericValue) -> ArgValue<'_>

Decode a value into a borrowed view.

pub fn as_bool(&self, value: GenericValue) -> Option<bool>

None if the value is not a bool.

pub fn as_int(&self, value: GenericValue) -> Option<i64>

The value as an i64; None if it is not an integer or does not fit in an i64 (big integers - fall back to display).

pub fn as_float(&self, value: GenericValue) -> Option<f64>

None if the value is not a float.

pub fn as_str(&self, value: GenericValue) -> Option<&str>

The contents of a string value; None if the value is not a string (or the host answered with malformed string data - a null pointer or invalid UTF-8, both protocol violations).

The returned string borrows the host and therefore cannot be held across a re-entering call (&mut self methods); the compiler rejects it:

use generic_lang_api::{GenericValue, Host, PluginError};

fn plugin_fn(host: &mut Host, args: &[GenericValue]) -> Result<GenericValue, PluginError> {
    let name = host.as_str(args[0]).unwrap();     // borrows `host`
    host.call(args[1], &[])?;                     // re-enters: needs `&mut host`
    Ok(host.make_str(name))                       // ERROR: `name` still borrowed
}

Copy the string out (.to_owned()) before re-entering if it is needed afterwards.

pub fn list_len(&self, value: GenericValue) -> Option<usize>

None if the value is not a list.

pub fn list_get( &self, value: GenericValue, index: usize, ) -> Result<GenericValue, PluginError>

The list element at index.

Errors

TypeError if the value is not a list; IndexError if the index is out of bounds.

pub fn tuple_len(&self, value: GenericValue) -> Option<usize>

None if the value is not a tuple.

pub fn tuple_get( &self, value: GenericValue, index: usize, ) -> Result<GenericValue, PluginError>

The tuple element at index.

Errors

TypeError if the value is not a tuple; IndexError if the index is out of bounds.

pub fn dict_len(&self, value: GenericValue) -> Option<usize>

None if the value is not a dict.

pub fn set_len(&self, value: GenericValue) -> Option<usize>

None if the value is not a set.

pub fn builtin(&self, name: &str) -> Result<GenericValue, PluginError>

Look up a builtin global by name - exception classes like "TypeError", native classes, builtin functions.

Errors

NameError if absent.

pub fn is_instance( &self, value: GenericValue, class: GenericValue, ) -> Result<bool, PluginError>

Whether value is an instance of class or of a subclass of it - the exact semantics of the isinstance builtin, value-type proxy classes included.

Errors

TypeError if class is not a class.

pub fn class_of(&self, value: GenericValue) -> Result<GenericValue, PluginError>

The class of an instance, as a class value (the analogue of type(self)). Call it to construct another instance of the same class, or pass it to Host::is_instance to type-check another argument before reading its opaque state.

Errors

TypeError if value is not an instance.

pub fn attr_get( &self, receiver: GenericValue, name: &str, ) -> Result<GenericValue, PluginError>

A field of an instance.

Errors

AttributeError if the field is absent, TypeError if the receiver is not an instance.

pub fn attr_set( &self, receiver: GenericValue, name: &str, value: GenericValue, ) -> Result<(), PluginError>

Set a field on an instance.

Errors

TypeError if the receiver is not an instance.

pub fn attr_has( &self, receiver: GenericValue, name: &str, ) -> Result<bool, PluginError>

Whether an instance has a field.

Errors

TypeError if the receiver is not an instance.

pub fn make_nil(&self) -> GenericValue

A new nil value.

pub fn make_bool(&self, value: bool) -> GenericValue

A new boolean value.

pub fn make_int(&self, value: i64) -> GenericValue

A new integer value.

pub fn make_float(&self, value: f64) -> GenericValue

A new float value.

pub fn make_str(&self, value: &str) -> GenericValue

Intern a string value.

Panics

Panics if the host rejects the string, which cannot happen for Rust strings (they are always valid UTF-8).

pub fn make_list(&self) -> GenericValue

A new, empty list.

pub fn list_push( &self, list: GenericValue, item: GenericValue, ) -> Result<(), PluginError>

Append to a list value.

Errors

TypeError if the target is not a list.

pub fn list_set( &self, list: GenericValue, index: usize, value: GenericValue, ) -> Result<(), PluginError>

Replace the element at an index.

Errors

TypeError if the target is not a list; IndexError if the index is out of bounds.

pub fn make_exception( &self, class: GenericValue, message: &str, ) -> Result<GenericValue, PluginError>

A new exception instance of class (any class deriving from Exception - builtin or user-defined), ready to be thrown (returned inside PluginError::Exception) or passed to generic code. Sets the message directly, bypassing __init__. Prefer the typed constructors below for the common builtin-class case.

Errors

TypeError if class is not a class deriving from Exception.

pub fn exception(&self, message: &str) -> PluginError

A PluginError carrying a fresh base Exception instance.

pub fn type_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh TypeError instance.

pub fn value_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh ValueError instance.

pub fn name_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh NameError instance.

pub fn const_reassignment_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh ConstReassignmentError instance.

pub fn attribute_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh AttributeError instance.

pub fn import_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh ImportError instance.

pub fn assertion_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh AssertionError instance.

pub fn io_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh IoError instance.

pub fn key_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh KeyError instance.

pub fn index_error(&self, message: &str) -> PluginError

A PluginError carrying a fresh IndexError instance.

pub fn display(&self, value: GenericValue) -> GenericValue

The raw string representation of any value, as a string value. Does NOT honor a user class’s __str__ - see Host::to_str.

pub fn display_string(&self, value: GenericValue) -> String

Host::display, copied out as an owned Rust String.

pub fn call( &mut self, callee: GenericValue, args: &[GenericValue], ) -> Result<GenericValue, PluginError>

Call a callable value with the given arguments.

Errors

Returns the generic exception raised by the callee, if any.

pub fn invoke( &mut self, receiver: GenericValue, name: &str, args: &[GenericValue], ) -> Result<GenericValue, PluginError>

Invoke a named method on a receiver.

Errors

Returns the generic exception raised by the method, if any.

pub fn to_str( &mut self, value: GenericValue, ) -> Result<GenericValue, PluginError>

String conversion honoring a user class’s __str__.

Errors

Returns the generic exception raised by __str__, if any.

pub fn dict_get( &mut self, dict: GenericValue, key: GenericValue, ) -> Result<GenericValue, PluginError>

Look up a key in a dict.

Errors

KeyError if absent, TypeError for unusable targets/keys, or any exception raised by __hash__/__eq__.

pub fn dict_set( &mut self, dict: GenericValue, key: GenericValue, value: GenericValue, ) -> Result<(), PluginError>

Insert or replace a key in a dict.

Errors

TypeError for unusable targets/keys, or any exception raised by __hash__/__eq__.

pub fn dict_contains( &mut self, dict: GenericValue, key: GenericValue, ) -> Result<bool, PluginError>

Whether a dict contains a key.

Errors

TypeError for unusable targets/keys, or any exception raised by __hash__/__eq__.

pub fn set_add( &mut self, set: GenericValue, item: GenericValue, ) -> Result<(), PluginError>

Add an item to a set.

Errors

TypeError for unusable targets/items, or any exception raised by __hash__/__eq__.

pub fn set_contains( &mut self, set: GenericValue, item: GenericValue, ) -> Result<bool, PluginError>

Whether a set contains an item.

Errors

TypeError for unusable targets/items, or any exception raised by __hash__/__eq__.

pub fn truthy(&mut self, value: GenericValue) -> Result<bool, PluginError>

Truthiness honoring __bool__.

Errors

Returns the generic exception raised by __bool__, if any.

pub fn equals( &mut self, a: GenericValue, b: GenericValue, ) -> Result<bool, PluginError>

Equality honoring __eq__.

Errors

Returns the generic exception raised by __eq__, if any.

pub fn hash(&mut self, value: GenericValue) -> Result<i64, PluginError>

Hash honoring __hash__.

Errors

Returns the generic exception raised by __hash__, if any.

pub fn root(&self, value: GenericValue)

Keep a value alive across re-entering calls for the rest of this plugin call (the host releases all roots automatically on return). Prefer the RAII form, Host::rooted.

pub fn unroot(&self, n: usize)

Release the n most recent roots early. Releasing more roots than were pushed corrupts interpreter state; prefer the RAII form, Host::rooted.

pub fn rooted(&self, value: GenericValue) -> Rooted<'a>

Root a value for the lifetime of the returned guard.

Guards release in LIFO order - drop them in reverse order of creation (scopes do this naturally).

pub fn set_opaque( &self, receiver: GenericValue, ptr: *mut c_void, ) -> Result<(), PluginError>

Install the plugin’s opaque pointer on a plugin-backed instance.

Typically called from __init__ with args[0] (the receiver) and a Box::into_raw(state) pointer. The class’s drop callback is called with this pointer when the instance is garbage-collected.

Overwriting an already-installed pointer leaks the previous one: the host does not run drop on it, since it cannot know whether the plugin still holds a copy elsewhere. If a plugin means to replace state, it must Host::get_opaque and free the old pointer itself first.

Errors

TypeError if receiver is not a plugin-backed instance.

pub fn get_opaque(&self, receiver: GenericValue) -> *mut c_void

Recover the pointer installed by Host::set_opaque, or null if none was installed (e.g. before __init__ ran) or receiver is not a plugin-backed instance. Never raises.

pub unsafe fn opaque_ref<T>(&self, receiver: GenericValue) -> Option<&mut T>

Typed mutable view of the opaque pointer, or None if it is null or receiver is not a plugin-backed instance.

Safety

The caller must ensure T is the correct type for this instance’s opaque state. The reference is valid while the instance is alive (the GC will not collect it while the plugin holds the instance value).