clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
//! Multifield values and the builder that produces them.

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

use crate::{Environment, Fact, Instance, Result, Value, ffi};

/// A retained CLIPS multifield: an ordered sequence of values.
///
/// Multifields do not nest. A field holding a multifield only arises from a
/// slot; appending one to a builder splices its fields in.
pub struct Multifield<'env> {
    value: Value<'env>,
}
impl<'env> Multifield<'env> {
    pub(crate) fn from_value(value: Value<'env>) -> Self {
        Self { value }
    }
    /// The multifield as a plain CLIPS value, for APIs that accept any value.
    pub fn value(&self) -> &Value<'env> {
        &self.value
    }
    /// The number of fields.
    pub fn len(&self) -> usize {
        unsafe { (*self.raw()).length }
    }

    /// Whether the multifield has no fields.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// The field at a zero-based index, retained independently of this
    /// multifield. `None` if the index is out of range.
    pub fn get(&self, index: usize) -> Option<Value<'env>> {
        if index >= self.len() {
            return None;
        }
        unsafe {
            let first = std::ptr::addr_of!((*self.raw()).contents) as *const ffi::CLIPSValue;
            let mut raw = *first.add(index);
            ffi::RetainCV(self.value.environment().raw.as_ptr(), &mut raw);
            Some(Value::from_retained_raw(self.value.environment(), raw))
        }
    }
    /// Iterates the fields in order, each retained.
    pub fn iter(&self) -> impl Iterator<Item = Value<'env>> + '_ {
        (0..self.len()).map(|index| self.get(index).expect("validated multifield index"))
    }
    /// Joins the fields into a single string exactly as CLIPS `implode$` does:
    /// fields separated by single spaces, with strings quoted and escaped.
    pub fn implode(&self) -> String {
        let environment = self.value.environment();
        let mut argument = ffi::UDFValue {
            supplemental_info: std::ptr::null_mut(),
            value: self.value.raw(),
            begin: 0,
            range: self.len(),
            next: std::ptr::null_mut(),
        };
        // The returned lexeme is ephemeral, so its contents are copied out
        // before returning to CLIPS.
        let lexeme = unsafe { ffi::ImplodeMultifield(environment.raw.as_ptr(), &mut argument) };
        if lexeme.is_null() {
            return String::new();
        }
        unsafe { std::ffi::CStr::from_ptr((*lexeme).contents) }
            .to_string_lossy()
            .into_owned()
    }
    pub(crate) fn raw(&self) -> *mut ffi::Multifield {
        unsafe { self.value.raw().multifield }
    }
}

/// Builds a multifield by appending fields in order.
///
/// The builder is reusable: [`MultifieldBuilder::build`] leaves it empty and
/// ready for the next multifield.
pub struct MultifieldBuilder<'env> {
    raw: NonNull<ffi::MultifieldBuilder>,
    environment: &'env Environment,
    marker: PhantomData<&'env Environment>,
}
impl<'env> MultifieldBuilder<'env> {
    pub(crate) fn new(environment: &'env Environment, capacity: usize) -> Result<Self> {
        NonNull::new(unsafe { ffi::CreateMultifieldBuilder(environment.raw.as_ptr(), capacity) })
            .map(|raw| Self {
                raw,
                environment,
                marker: PhantomData,
            })
            .ok_or(crate::Error::EnvironmentCreation)
    }
    /// Appends an integer field.
    pub fn integer(&mut self, value: i64) -> &mut Self {
        unsafe { ffi::MBAppendInteger(self.raw.as_ptr(), value) };
        self
    }
    /// Appends a float field.
    pub fn float(&mut self, value: f64) -> &mut Self {
        unsafe { ffi::MBAppendFloat(self.raw.as_ptr(), value) };
        self
    }
    /// Appends a symbol field.
    pub fn symbol(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::MBAppendSymbol(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends a string field.
    pub fn string(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::MBAppendString(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends an instance-name field.
    pub fn instance_name(&mut self, value: &str) -> Result<&mut Self> {
        let value = CString::new(value)?;
        unsafe { ffi::MBAppendInstanceName(self.raw.as_ptr(), value.as_ptr()) };
        Ok(self)
    }
    /// Appends a fact address as a field.
    pub fn fact(&mut self, value: &Fact<'env>) -> &mut Self {
        unsafe { ffi::MBAppendFact(self.raw.as_ptr(), value.raw.as_ptr()) };
        self
    }
    /// Appends an instance address as a field.
    pub fn instance(&mut self, value: &Instance<'env>) -> &mut Self {
        unsafe { ffi::MBAppendInstance(self.raw.as_ptr(), value.raw.as_ptr()) };
        self
    }
    /// Appends another multifield.
    ///
    /// CLIPS multifields do not nest: its fields are spliced into this one.
    pub fn multifield(&mut self, value: &Multifield<'env>) -> &mut Self {
        unsafe { ffi::MBAppendMultifield(self.raw.as_ptr(), value.raw()) };
        self
    }
    /// Appends an already existing CLIPS value.
    ///
    /// Fails with [`crate::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::MBAppend(self.raw.as_ptr(), &mut cv) };
        Ok(self)
    }
    /// Discards the appended fields without building anything.
    pub fn reset(&mut self) {
        unsafe { ffi::MBReset(self.raw.as_ptr()) }
    }

    /// Builds the multifield from the appended fields and empties the builder.
    pub fn build(&mut self) -> Multifield<'env> {
        let mut raw = ffi::CLIPSValue {
            multifield: unsafe { ffi::MBCreate(self.raw.as_ptr()) },
        };
        unsafe { ffi::RetainCV(self.environment.raw.as_ptr(), &mut raw) };
        Multifield::from_value(Value::from_retained_raw(self.environment, raw))
    }
}
impl Drop for MultifieldBuilder<'_> {
    fn drop(&mut self) {
        unsafe { ffi::MBDispose(self.raw.as_ptr()) }
    }
}