Skip to main content

clips_bindings/
function.rs

1//! Calling CLIPS functions directly, without parsing an expression.
2
3use std::ffi::CString;
4use std::marker::PhantomData;
5use std::ptr::NonNull;
6
7use crate::error::{Error, FunctionCallError, Result};
8use crate::{Environment, Fact, Instance, Multifield, Value, ffi};
9
10/// Calls a CLIPS function with typed arguments.
11///
12/// Arguments are passed as real CLIPS values rather than as expression text,
13/// so nothing has to be formatted, escaped, or re-parsed. This is also how
14/// message sends are built, since CLIPS's own `Send` only accepts argument
15/// text.
16pub struct FunctionCall<'env> {
17    raw: NonNull<ffi::FunctionCallBuilder>,
18    environment: &'env Environment,
19    marker: PhantomData<&'env Environment>,
20}
21impl<'env> FunctionCall<'env> {
22    pub(crate) fn new(environment: &'env Environment, capacity: usize) -> Result<Self> {
23        NonNull::new(unsafe { ffi::CreateFunctionCallBuilder(environment.raw.as_ptr(), capacity) })
24            .map(|raw| Self {
25                raw,
26                environment,
27                marker: PhantomData,
28            })
29            .ok_or(Error::EnvironmentCreation)
30    }
31    /// Appends an integer argument.
32    pub fn integer(&mut self, value: i64) -> &mut Self {
33        unsafe { ffi::FCBAppendInteger(self.raw.as_ptr(), value) };
34        self
35    }
36    /// Appends a float argument.
37    pub fn float(&mut self, value: f64) -> &mut Self {
38        unsafe { ffi::FCBAppendFloat(self.raw.as_ptr(), value) };
39        self
40    }
41    /// Appends a symbol argument.
42    pub fn symbol(&mut self, value: &str) -> Result<&mut Self> {
43        let value = CString::new(value)?;
44        unsafe { ffi::FCBAppendSymbol(self.raw.as_ptr(), value.as_ptr()) };
45        Ok(self)
46    }
47    /// Appends a string argument.
48    pub fn string(&mut self, value: &str) -> Result<&mut Self> {
49        let value = CString::new(value)?;
50        unsafe { ffi::FCBAppendString(self.raw.as_ptr(), value.as_ptr()) };
51        Ok(self)
52    }
53    /// Appends an instance-name argument.
54    pub fn instance_name(&mut self, value: &str) -> Result<&mut Self> {
55        let value = CString::new(value)?;
56        unsafe { ffi::FCBAppendInstanceName(self.raw.as_ptr(), value.as_ptr()) };
57        Ok(self)
58    }
59    /// Appends a fact address as an argument.
60    pub fn fact(&mut self, value: &Fact<'env>) -> &mut Self {
61        unsafe { ffi::FCBAppendFact(self.raw.as_ptr(), value.raw.as_ptr()) };
62        self
63    }
64    /// Appends an instance address as an argument.
65    pub fn instance(&mut self, value: &Instance<'env>) -> &mut Self {
66        unsafe { ffi::FCBAppendInstance(self.raw.as_ptr(), value.raw.as_ptr()) };
67        self
68    }
69    /// Appends a multifield argument.
70    pub fn multifield(&mut self, value: &Multifield<'env>) -> &mut Self {
71        unsafe { ffi::FCBAppendMultifield(self.raw.as_ptr(), value.raw()) };
72        self
73    }
74    /// Appends an already existing CLIPS value.
75    ///
76    /// Fails with [`Error::ForeignEnvironment`] if `value` belongs to another
77    /// environment, since CLIPS atoms are interned per environment.
78    pub fn value(&mut self, value: &Value<'env>) -> Result<&mut Self> {
79        let mut cv = self.environment.check_value(value)?;
80        unsafe { ffi::FCBAppend(self.raw.as_ptr(), &mut cv) };
81        Ok(self)
82    }
83    /// Removes the most recently appended argument.
84    pub fn pop(&mut self) {
85        unsafe { ffi::FCBPopArgument(self.raw.as_ptr()) }
86    }
87
88    /// Discards every appended argument.
89    pub fn reset(&mut self) {
90        unsafe { ffi::FCBReset(self.raw.as_ptr()) }
91    }
92
93    /// Calls `name` with the appended arguments and returns its retained
94    /// result.
95    ///
96    /// The name may be a built-in function, a deffunction, or a generic
97    /// function. Arguments are cleared afterwards, so the builder can be
98    /// reused.
99    pub fn call(&mut self, name: &str) -> Result<Value<'env>> {
100        let name = CString::new(name)?;
101        let mut result = ffi::CLIPSValue {
102            value: std::ptr::null_mut(),
103        };
104        match unsafe { ffi::FCBCall(self.raw.as_ptr(), name.as_ptr(), &mut result) } {
105            0 => {
106                unsafe { ffi::RetainCV(self.environment.raw.as_ptr(), &mut result) };
107                Ok(Value::from_retained_raw(self.environment, result))
108            }
109            code => Err(Error::FunctionCall(FunctionCallError::from(code))),
110        }
111    }
112}
113impl Drop for FunctionCall<'_> {
114    fn drop(&mut self) {
115        unsafe { ffi::FCBDispose(self.raw.as_ptr()) }
116    }
117}