Skip to main content

clips_bindings/
construct.rs

1//! Typed handles for every CLIPS construct family, plus lookup and
2//! iteration.
3//!
4//! A handle borrows its environment, which is what stops `clear`, a binary
5//! load, or an undefinition from running while it is alive.
6
7use std::ffi::{CStr, CString};
8use std::ptr::NonNull;
9
10use crate::{Environment, Result, ffi};
11
12macro_rules! construct_type {
13    ($handle:ident, $iter:ident, $raw:ident, $method:ident, $find:ident, $next:ident, $name:ident) => {
14        #[doc = concat!("A handle to one ", stringify!($handle), " construct.")]
15        ///
16        /// Borrowing the environment is what keeps it sound: undefining a
17        /// construct, clearing, or loading a binary image all need
18        /// `&mut Environment` and so cannot run while a handle is alive.
19        pub struct $handle<'env> {
20            pub(crate) raw: NonNull<ffi::$raw>,
21            pub(crate) _environment: &'env Environment,
22        }
23        impl $handle<'_> {
24            /// The construct's name, without any module prefix.
25            pub fn name(&self) -> &str {
26                unsafe { CStr::from_ptr(ffi::$name(self.raw.as_ptr())) }
27                    .to_str()
28                    .unwrap_or("")
29            }
30        }
31        #[doc = concat!("Iterates every ", stringify!($handle), " in definition order.")]
32        pub struct $iter<'env> {
33            environment: &'env Environment,
34            current: *mut ffi::$raw,
35        }
36        impl<'env> Iterator for $iter<'env> {
37            type Item = $handle<'env>;
38            fn next(&mut self) -> Option<Self::Item> {
39                self.current = unsafe { ffi::$next(self.environment.raw.as_ptr(), self.current) };
40                NonNull::new(self.current).map(|raw| $handle {
41                    raw,
42                    _environment: self.environment,
43                })
44            }
45        }
46        impl Environment {
47            #[doc = concat!("Looks up a ", stringify!($handle), " by name.")]
48            ///
49            /// `None` if no construct of that name is visible from the current
50            /// module.
51            pub fn $method(&self, name: &str) -> Result<Option<$handle<'_>>> {
52                let name = CString::new(name)?;
53                Ok(
54                    NonNull::new(unsafe { ffi::$find(self.raw.as_ptr(), name.as_ptr()) }).map(
55                        |raw| $handle {
56                            raw,
57                            _environment: self,
58                        },
59                    ),
60                )
61            }
62        }
63    };
64}
65
66construct_type!(
67    Deftemplate,
68    Deftemplates,
69    Deftemplate,
70    find_deftemplate,
71    FindDeftemplate,
72    GetNextDeftemplate,
73    DeftemplateName
74);
75construct_type!(
76    Defrule,
77    Defrules,
78    Defrule,
79    find_defrule,
80    FindDefrule,
81    GetNextDefrule,
82    DefruleName
83);
84construct_type!(
85    Deffacts,
86    DeffactsIter,
87    Deffacts,
88    find_deffacts,
89    FindDeffacts,
90    GetNextDeffacts,
91    DeffactsName
92);
93construct_type!(
94    Defglobal,
95    Defglobals,
96    Defglobal,
97    find_defglobal,
98    FindDefglobal,
99    GetNextDefglobal,
100    DefglobalName
101);
102construct_type!(
103    Deffunction,
104    Deffunctions,
105    Deffunction,
106    find_deffunction,
107    FindDeffunction,
108    GetNextDeffunction,
109    DeffunctionName
110);
111construct_type!(
112    Defgeneric,
113    Defgenerics,
114    Defgeneric,
115    find_defgeneric,
116    FindDefgeneric,
117    GetNextDefgeneric,
118    DefgenericName
119);
120construct_type!(
121    Defclass,
122    Defclasses,
123    Defclass,
124    find_defclass,
125    FindDefclass,
126    GetNextDefclass,
127    DefclassName
128);
129construct_type!(
130    Definstances,
131    DefinstancesIter,
132    Definstances,
133    find_definstances,
134    FindDefinstances,
135    GetNextDefinstances,
136    DefinstancesName
137);
138construct_type!(
139    Defmodule,
140    Defmodules,
141    Defmodule,
142    find_defmodule,
143    FindDefmodule,
144    GetNextDefmodule,
145    DefmoduleName
146);
147
148impl<'env> Defmodule<'env> {
149    pub(crate) fn from_raw(environment: &'env Environment, raw: NonNull<ffi::Defmodule>) -> Self {
150        Self {
151            raw,
152            _environment: environment,
153        }
154    }
155}
156
157impl Defclass<'_> {
158    pub(crate) fn raw(&self) -> *mut ffi::Defclass {
159        self.raw.as_ptr()
160    }
161}
162
163impl Environment {
164    /// Iterates every deftemplate, including the implied templates CLIPS creates for ordered facts.
165    pub fn deftemplates(&self) -> Deftemplates<'_> {
166        Deftemplates {
167            environment: self,
168            current: std::ptr::null_mut(),
169        }
170    }
171    /// Iterates every defrule.
172    pub fn defrules(&self) -> Defrules<'_> {
173        Defrules {
174            environment: self,
175            current: std::ptr::null_mut(),
176        }
177    }
178    /// Iterates every deffacts.
179    pub fn deffacts(&self) -> DeffactsIter<'_> {
180        DeffactsIter {
181            environment: self,
182            current: std::ptr::null_mut(),
183        }
184    }
185    /// Iterates every defglobal.
186    pub fn defglobals(&self) -> Defglobals<'_> {
187        Defglobals {
188            environment: self,
189            current: std::ptr::null_mut(),
190        }
191    }
192    /// Iterates every deffunction.
193    pub fn deffunctions(&self) -> Deffunctions<'_> {
194        Deffunctions {
195            environment: self,
196            current: std::ptr::null_mut(),
197        }
198    }
199    /// Iterates every defgeneric.
200    pub fn defgenerics(&self) -> Defgenerics<'_> {
201        Defgenerics {
202            environment: self,
203            current: std::ptr::null_mut(),
204        }
205    }
206    /// Iterates every defclass, including the built-in classes such as USER and OBJECT.
207    pub fn defclasses(&self) -> Defclasses<'_> {
208        Defclasses {
209            environment: self,
210            current: std::ptr::null_mut(),
211        }
212    }
213    /// Iterates every definstances construct.
214    pub fn definstances(&self) -> DefinstancesIter<'_> {
215        DefinstancesIter {
216            environment: self,
217            current: std::ptr::null_mut(),
218        }
219    }
220    /// Iterates every defmodule, starting with MAIN.
221    pub fn defmodules(&self) -> Defmodules<'_> {
222        Defmodules {
223            environment: self,
224            current: std::ptr::null_mut(),
225        }
226    }
227}