Skip to main content

Instance

Struct Instance 

Source
pub struct Instance<'env> { /* private fields */ }
Expand description

A COOL instance, retained for as long as the handle lives.

Borrowing the environment is what keeps the handle sound: operations that could invalidate it, such as clear or reset, take &mut Environment and so cannot run while one exists.

Implementations§

Source§

impl<'env> Instance<'env>

Source

pub fn name(&self) -> &str

The instance’s name, or "" once the instance has been unmade.

Retaining an instance keeps its record alive but not its name symbol, which CLIPS releases on unmake-instance; reading the name afterwards would dereference freed memory, so it is checked first.

Source

pub fn is_deleted(&self) -> bool

Whether the instance has been deleted.

The handle stays valid: CLIPS keeps the record alive while it is retained, so a deleted instance can still be queried rather than dangling.

Source

pub fn unmake(&mut self) -> Result<()>

Deletes the instance, running its delete handler.

Source

pub fn pretty_print(&self) -> String

The instance rendered as make-instance syntax.

Empty if CLIPS could not allocate the string builder it prints through.

Source

pub fn class(&self) -> Option<Defclass<'env>>

The class this instance belongs to.

Examples found in repository?
examples/objects_and_messages.rs (line 28)
7fn main() -> Result<(), Error> {
8    let mut environment = Environment::new()?;
9
10    environment.load_str(
11        r#"
12        (defclass ACCOUNT (is-a USER)
13            (slot holder)
14            (slot balance (type INTEGER) (default 0)))
15
16        (defmessage-handler ACCOUNT deposit (?amount)
17            (bind ?self:balance (+ ?self:balance ?amount))
18            ?self:balance)
19
20        (defmessage-handler ACCOUNT describe ()
21            (str-cat (send ?self get-holder) ": " (send ?self get-balance)))
22        "#,
23    )?;
24
25    let account = environment.make_instance("(ada of ACCOUNT (holder Ada) (balance 100))")?;
26    println!(
27        "class: {}",
28        account.class().expect("instance has a class").name()
29    );
30
31    let balance = account.send("deposit")?.integer(250).send()?;
32    println!("after deposit: {:?}", balance.as_i64());
33    drop(balance);
34
35    // A direct slot write bypasses message passing entirely.
36    account.put_integer("balance", 1_000)?;
37
38    let description = account.send("describe")?.send()?;
39    println!("{}", description.as_str().unwrap_or(""));
40    drop(description);
41    drop(account);
42
43    let class = environment.find_defclass("ACCOUNT")?.expect("class exists");
44    for slot in class.slots(false) {
45        let descriptor = class.slot(&slot).expect("slot name has no NUL");
46        if let Some(descriptor) = descriptor {
47            println!(
48                "slot {slot}: types {:?} default {:?}",
49                descriptor.allowed_types(),
50                descriptor.default_value()
51            );
52        }
53    }
54
55    Ok(())
56}
Source

pub fn send(&self, message: &str) -> Result<MessageCall<'env>>

Starts a message send to this instance.

Arguments are appended with the typed methods of MessageCall, so no CLIPS argument text is assembled or parsed by the caller.

Examples found in repository?
examples/objects_and_messages.rs (line 31)
7fn main() -> Result<(), Error> {
8    let mut environment = Environment::new()?;
9
10    environment.load_str(
11        r#"
12        (defclass ACCOUNT (is-a USER)
13            (slot holder)
14            (slot balance (type INTEGER) (default 0)))
15
16        (defmessage-handler ACCOUNT deposit (?amount)
17            (bind ?self:balance (+ ?self:balance ?amount))
18            ?self:balance)
19
20        (defmessage-handler ACCOUNT describe ()
21            (str-cat (send ?self get-holder) ": " (send ?self get-balance)))
22        "#,
23    )?;
24
25    let account = environment.make_instance("(ada of ACCOUNT (holder Ada) (balance 100))")?;
26    println!(
27        "class: {}",
28        account.class().expect("instance has a class").name()
29    );
30
31    let balance = account.send("deposit")?.integer(250).send()?;
32    println!("after deposit: {:?}", balance.as_i64());
33    drop(balance);
34
35    // A direct slot write bypasses message passing entirely.
36    account.put_integer("balance", 1_000)?;
37
38    let description = account.send("describe")?.send()?;
39    println!("{}", description.as_str().unwrap_or(""));
40    drop(description);
41    drop(account);
42
43    let class = environment.find_defclass("ACCOUNT")?.expect("class exists");
44    for slot in class.slots(false) {
45        let descriptor = class.slot(&slot).expect("slot name has no NUL");
46        if let Some(descriptor) = descriptor {
47            println!(
48                "slot {slot}: types {:?} default {:?}",
49                descriptor.allowed_types(),
50                descriptor.default_value()
51            );
52        }
53    }
54
55    Ok(())
56}
Source

pub fn modifier(&self) -> Result<InstanceModifier<'env>>

Starts a batched modification.

Unlike the put_* methods, slot writes are collected and applied as one change when InstanceModifier::modify is called, so daemons and pattern matching run once rather than per slot.

Source

pub fn put_integer(&self, slot: &str, value: i64) -> Result<&Self>

Writes a slot directly, bypassing message passing.

Unlike InstanceModifier, each call takes effect immediately, so slot-level daemons and pattern matching run per assignment.

Examples found in repository?
examples/objects_and_messages.rs (line 36)
7fn main() -> Result<(), Error> {
8    let mut environment = Environment::new()?;
9
10    environment.load_str(
11        r#"
12        (defclass ACCOUNT (is-a USER)
13            (slot holder)
14            (slot balance (type INTEGER) (default 0)))
15
16        (defmessage-handler ACCOUNT deposit (?amount)
17            (bind ?self:balance (+ ?self:balance ?amount))
18            ?self:balance)
19
20        (defmessage-handler ACCOUNT describe ()
21            (str-cat (send ?self get-holder) ": " (send ?self get-balance)))
22        "#,
23    )?;
24
25    let account = environment.make_instance("(ada of ACCOUNT (holder Ada) (balance 100))")?;
26    println!(
27        "class: {}",
28        account.class().expect("instance has a class").name()
29    );
30
31    let balance = account.send("deposit")?.integer(250).send()?;
32    println!("after deposit: {:?}", balance.as_i64());
33    drop(balance);
34
35    // A direct slot write bypasses message passing entirely.
36    account.put_integer("balance", 1_000)?;
37
38    let description = account.send("describe")?.send()?;
39    println!("{}", description.as_str().unwrap_or(""));
40    drop(description);
41    drop(account);
42
43    let class = environment.find_defclass("ACCOUNT")?.expect("class exists");
44    for slot in class.slots(false) {
45        let descriptor = class.slot(&slot).expect("slot name has no NUL");
46        if let Some(descriptor) = descriptor {
47            println!(
48                "slot {slot}: types {:?} default {:?}",
49                descriptor.allowed_types(),
50                descriptor.default_value()
51            );
52        }
53    }
54
55    Ok(())
56}
Source

pub fn put_float(&self, slot: &str, value: f64) -> Result<&Self>

Writes a float slot directly. See Instance::put_integer.

Source

pub fn put_symbol(&self, slot: &str, value: &str) -> Result<&Self>

Writes a symbol slot directly. See Instance::put_integer.

Source

pub fn put_string(&self, slot: &str, value: &str) -> Result<&Self>

Writes a string slot directly. See Instance::put_integer.

Source

pub fn put_instance_name(&self, slot: &str, value: &str) -> Result<&Self>

Writes an instance-name slot directly. See Instance::put_integer.

Source

pub fn put_fact(&self, slot: &str, value: &Fact<'env>) -> Result<&Self>

Writes a fact address to a slot directly. See Instance::put_integer.

Source

pub fn put_instance(&self, slot: &str, value: &Instance<'env>) -> Result<&Self>

Writes an instance address to a slot directly. See Instance::put_integer.

Source

pub fn put_multifield( &self, slot: &str, value: &Multifield<'env>, ) -> Result<&Self>

Writes a multifield slot directly. See Instance::put_integer.

Source

pub fn put_value(&self, slot: &str, value: &Value<'env>) -> Result<&Self>

Writes an already existing CLIPS value to a slot.

Fails with Error::ForeignEnvironment if value belongs to another environment, since CLIPS atoms are interned per environment.

Source

pub fn slot(&self, name: &str) -> Result<Value<'env>>

Reads a slot, bypassing any get- accessor handler.

The returned value is retained, so it stays valid independently of the instance.

Trait Implementations§

Source§

impl Drop for Instance<'_>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl<'env> !RefUnwindSafe for Instance<'env>

§

impl<'env> !Send for Instance<'env>

§

impl<'env> !Sync for Instance<'env>

§

impl<'env> !UnwindSafe for Instance<'env>

§

impl<'env> Freeze for Instance<'env>

§

impl<'env> Unpin for Instance<'env>

§

impl<'env> UnsafeUnpin for Instance<'env>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.