clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
//! Calling CLIPS functions directly, without parsing an expression.

use std::ffi::CString;
use std::marker::PhantomData;
use std::ptr::NonNull;

use crate::error::{Error, FunctionCallError, Result};
use crate::{Environment, Fact, Instance, Multifield, Value, ffi};

/// Calls a CLIPS function with typed arguments.
///
/// Arguments are passed as real CLIPS values rather than as expression text,
/// so nothing has to be formatted, escaped, or re-parsed. This is also how
/// message sends are built, since CLIPS's own `Send` only accepts argument
/// text.
pub struct FunctionCall<'env> {
    raw: NonNull<ffi::FunctionCallBuilder>,
    environment: &'env Environment,
    marker: PhantomData<&'env Environment>,
}
impl<'env> FunctionCall<'env> {
    pub(crate) fn new(environment: &'env Environment, capacity: usize) -> Result<Self> {
        NonNull::new(unsafe { ffi::CreateFunctionCallBuilder(environment.raw.as_ptr(), capacity) })
            .map(|raw| Self {
                raw,
                environment,
                marker: PhantomData,
            })
            .ok_or(Error::EnvironmentCreation)
    }
    /// Appends an integer argument.
    pub fn integer(&mut self, value: i64) -> &mut Self {
        unsafe { ffi::FCBAppendInteger(self.raw.as_ptr(), value) };
        self
    }
    /// Appends a float argument.
    pub fn float(&mut self, value: f64) -> &mut Self {
        unsafe { ffi::FCBAppendFloat(self.raw.as_ptr(), value) };
        self
    }
    /// Appends a symbol argument.
    pub fn symbol(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::FCBAppendSymbol(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends a string argument.
    pub fn string(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::FCBAppendString(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends an instance-name argument.
    pub fn instance_name(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::FCBAppendInstanceName(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends a fact address as an argument.
    pub fn fact(&mut self, value: &Fact<'env>) -> &mut Self {
        unsafe { ffi::FCBAppendFact(self.raw.as_ptr(), value.raw.as_ptr()) };
        self
    }
    /// Appends an instance address as an argument.
    pub fn instance(&mut self, value: &Instance<'env>) -> &mut Self {
        unsafe { ffi::FCBAppendInstance(self.raw.as_ptr(), value.raw.as_ptr()) };
        self
    }
    /// Appends a multifield argument.
    pub fn multifield(&mut self, value: &Multifield<'env>) -> &mut Self {
        unsafe { ffi::FCBAppendMultifield(self.raw.as_ptr(), value.raw()) };
        self
    }
    /// Appends an already existing CLIPS value.
    ///
    /// Fails with [`Error::ForeignEnvironment`] if `value` belongs to another
    /// environment, since CLIPS atoms are interned per environment.
    pub fn value(&mut self, value: &Value<'env>) -> Result<&mut Self> {
        let mut cv = self.environment.check_value(value)?;
        unsafe { ffi::FCBAppend(self.raw.as_ptr(), &mut cv) };
        Ok(self)
    }
    /// Removes the most recently appended argument.
    pub fn pop(&mut self) {
        unsafe { ffi::FCBPopArgument(self.raw.as_ptr()) }
    }

    /// Discards every appended argument.
    pub fn reset(&mut self) {
        unsafe { ffi::FCBReset(self.raw.as_ptr()) }
    }

    /// Calls `name` with the appended arguments and returns its retained
    /// result.
    ///
    /// The name may be a built-in function, a deffunction, or a generic
    /// function. Arguments are cleared afterwards, so the builder can be
    /// reused.
    pub fn call(&mut self, name: &str) -> Result<Value<'env>> {
        let name = CString::new(name)?;
        let mut result = ffi::CLIPSValue {
            value: std::ptr::null_mut(),
        };
        match unsafe { ffi::FCBCall(self.raw.as_ptr(), name.as_ptr(), &mut result) } {
            0 => {
                unsafe { ffi::RetainCV(self.environment.raw.as_ptr(), &mut result) };
                Ok(Value::from_retained_raw(self.environment, result))
            }
            code => Err(Error::FunctionCall(FunctionCallError::from(code))),
        }
    }
}
impl Drop for FunctionCall<'_> {
    fn drop(&mut self) {
        unsafe { ffi::FCBDispose(self.raw.as_ptr()) }
    }
}