1use std::ffi::CString;
5use std::marker::PhantomData;
6use std::ptr::NonNull;
7use std::rc::Rc;
8
9use crate::error::{BuildError, Error, EvaluationError, LoadError, Result};
10use crate::{
11 data::EnvironmentData,
12 fact::{Fact, FactBuilder, Facts},
13 ffi,
14 function::FunctionCall,
15 hook::{
16 FactChange, FactEventKind, HookEntry, HookError, HookKind, ParserDiagnostic,
17 ParserErrorContext, ReadyHookKind, RuleFirePhase,
18 },
19 instance::{InstanceBuilder, Instances},
20 multifield::{Multifield, MultifieldBuilder},
21 router::{Router, RouterEntry, RouterError},
22 udf::{
23 UdfCallbackError, UdfRegistration, UdfRegistrationError, UdfReturn, UdfSignature, UdfValue,
24 },
25 value::Value,
26};
27
28pub struct Environment {
34 pub(crate) raw: NonNull<ffi::Environment>,
35 pub(crate) routers: Vec<RouterEntry>,
36 #[allow(clippy::vec_box)]
38 pub(crate) udfs: Vec<Box<UdfRegistration>>,
39 pub(crate) hooks: Vec<HookEntry>,
40 parser_error: Option<Box<ParserErrorContext>>,
42 pub(crate) data: EnvironmentData,
45 thread_affinity: PhantomData<Rc<()>>,
46}
47
48impl Environment {
49 pub fn new() -> Result<Self> {
55 NonNull::new(unsafe { ffi::CreateEnvironment() })
56 .map(|raw| Self {
57 raw,
58 routers: Vec::new(),
59 udfs: Vec::new(),
60 hooks: Vec::new(),
61 parser_error: None,
62 data: EnvironmentData::default(),
63 thread_affinity: PhantomData,
64 })
65 .ok_or(Error::EnvironmentCreation)
66 }
67 pub fn clear(&mut self) -> Result<()> {
73 unsafe { ffi::Clear(self.raw.as_ptr()) }
74 .then_some(())
75 .ok_or(Error::ClearRejected)
76 }
77
78 pub fn reset(&mut self) {
81 unsafe { ffi::Reset(self.raw.as_ptr()) }
82 }
83
84 pub fn run(&mut self, limit: Option<u64>) -> u64 {
88 unsafe {
89 ffi::Run(
90 self.raw.as_ptr(),
91 limit.map_or(-1, |n| n.min(i64::MAX as u64) as i64),
92 ) as u64
93 }
94 }
95 pub fn halt_execution(&self) -> bool {
107 unsafe { ffi::GetHaltExecution(self.raw.as_ptr()) }
108 }
109
110 pub fn set_halt_execution(&mut self, halt: bool) {
116 unsafe { ffi::SetHaltExecution(self.raw.as_ptr(), halt) }
117 }
118
119 pub fn halt_rules(&self) -> bool {
124 unsafe { ffi::GetHaltRules(self.raw.as_ptr()) }
125 }
126
127 pub fn set_halt_rules(&mut self, halt: bool) {
135 unsafe { ffi::SetHaltRules(self.raw.as_ptr(), halt) }
136 }
137
138 pub fn beta_memory_resizing(&self) -> bool {
140 unsafe { ffi::GetBetaMemoryResizing(self.raw.as_ptr()) }
141 }
142
143 pub fn set_beta_memory_resizing(&mut self, resize: bool) -> bool {
145 unsafe { ffi::SetBetaMemoryResizing(self.raw.as_ptr(), resize) }
146 }
147
148 pub fn write(&self, text: &str) -> Result<()> {
153 let text = CString::new(text)?;
154 unsafe { ffi::Write(self.raw.as_ptr(), text.as_ptr()) };
155 Ok(())
156 }
157
158 pub fn writeln(&self, text: &str) -> Result<()> {
160 let text = CString::new(text)?;
161 unsafe { ffi::Writeln(self.raw.as_ptr(), text.as_ptr()) };
162 Ok(())
163 }
164
165 pub fn write_to(&self, logical_name: &str, text: &str) -> Result<()> {
168 let logical_name = CString::new(logical_name)?;
169 let text = CString::new(text)?;
170 unsafe { ffi::WriteString(self.raw.as_ptr(), logical_name.as_ptr(), text.as_ptr()) };
171 Ok(())
172 }
173
174 pub fn build(&mut self, construct: &str) -> Result<()> {
180 let construct = CString::new(construct)?;
181 match unsafe { ffi::Build(self.raw.as_ptr(), construct.as_ptr()) } {
182 0 => Ok(()),
183 code => Err(Error::Build(BuildError::from(code))),
184 }
185 }
186
187 pub fn load(&mut self, path: &str) -> Result<()> {
189 let path = CString::new(path)?;
190 match unsafe { ffi::Load(self.raw.as_ptr(), path.as_ptr()) } {
191 0 => Ok(()),
192 code => Err(Error::Load(LoadError::from(code))),
193 }
194 }
195 pub fn load_str(&mut self, source: &str) -> Result<()> {
201 let source = CString::new(source)?;
202 if unsafe {
203 ffi::LoadFromString(self.raw.as_ptr(), source.as_ptr(), source.as_bytes().len())
204 } {
205 Ok(())
206 } else {
207 Err(Error::Load(LoadError::Parsing))
208 }
209 }
210 pub fn eval(&mut self, expression: &str) -> Result<Value<'_>> {
215 let expression = CString::new(expression)?;
216 let mut raw = ffi::CLIPSValue {
217 value: std::ptr::null_mut(),
218 };
219 match unsafe { ffi::Eval(self.raw.as_ptr(), expression.as_ptr(), &mut raw) } {
220 0 => {
221 unsafe { ffi::RetainCV(self.raw.as_ptr(), &mut raw) };
222 Ok(Value::new(self, raw))
223 }
224 code => Err(Error::Evaluation(EvaluationError::from(code))),
225 }
226 }
227 pub(crate) fn is_same(&self, other: &Environment) -> bool {
232 self.raw == other.raw
233 }
234 pub(crate) fn check_value(&self, value: &Value<'_>) -> Result<ffi::CLIPSValue> {
237 if self.is_same(value.environment()) {
238 Ok(value.raw())
239 } else {
240 Err(Error::ForeignEnvironment)
241 }
242 }
243 pub fn create_integer(&self, value: i64) -> Value<'_> {
245 Value::retaining(
246 self,
247 ffi::CLIPSValue {
248 integer: unsafe { ffi::CreateInteger(self.raw.as_ptr(), value) },
249 },
250 )
251 }
252 pub fn create_float(&self, value: f64) -> Value<'_> {
254 Value::retaining(
255 self,
256 ffi::CLIPSValue {
257 float: unsafe { ffi::CreateFloat(self.raw.as_ptr(), value) },
258 },
259 )
260 }
261 pub fn create_boolean(&self, value: bool) -> Value<'_> {
263 Value::retaining(
264 self,
265 ffi::CLIPSValue {
266 lexeme: unsafe { ffi::CreateBoolean(self.raw.as_ptr(), value) },
267 },
268 )
269 }
270 pub fn create_symbol(&self, value: &str) -> Result<Value<'_>> {
272 self.create_lexeme(value, ffi::CreateSymbol)
273 }
274 pub fn create_string(&self, value: &str) -> Result<Value<'_>> {
276 self.create_lexeme(value, ffi::CreateString)
277 }
278 pub fn create_instance_name(&self, value: &str) -> Result<Value<'_>> {
280 self.create_lexeme(value, ffi::CreateInstanceName)
281 }
282 fn create_lexeme(
283 &self,
284 value: &str,
285 create: unsafe extern "C" fn(
286 *mut ffi::Environment,
287 *const std::ffi::c_char,
288 ) -> *mut ffi::CLIPSLexeme,
289 ) -> Result<Value<'_>> {
290 let value = CString::new(value)?;
291 Ok(Value::retaining(
292 self,
293 ffi::CLIPSValue {
294 lexeme: unsafe { create(self.raw.as_ptr(), value.as_ptr()) },
295 },
296 ))
297 }
298 pub fn string_to_multifield(&self, source: &str) -> Result<Multifield<'_>> {
301 let source = CString::new(source)?;
302 let raw = unsafe { ffi::StringToMultifield(self.raw.as_ptr(), source.as_ptr()) };
303 if raw.is_null() {
304 return Err(Error::Evaluation(EvaluationError::Parsing));
305 }
306 Ok(Multifield::from_value(Value::retaining(
307 self,
308 ffi::CLIPSValue { multifield: raw },
309 )))
310 }
311 pub fn assert_string(&self, source: &str) -> Result<Fact<'_>> {
316 let source = CString::new(source)?;
317 let raw = unsafe { ffi::AssertString(self.raw.as_ptr(), source.as_ptr()) };
318 Fact::from_result(self, raw, unsafe {
319 ffi::GetAssertStringError(self.raw.as_ptr())
320 })
321 }
322 pub fn fact_builder(&self, template: &str) -> Result<FactBuilder<'_>> {
328 FactBuilder::new(self, template)
329 }
330
331 pub fn facts(&self) -> Facts<'_> {
333 Facts::new(self)
334 }
335
336 pub fn fact_count(&self) -> usize {
338 unsafe { ffi::GetNumberOfFacts(self.raw.as_ptr()) as usize }
339 }
340
341 pub fn instance_builder(&self, class: &str) -> Result<InstanceBuilder<'_>> {
343 InstanceBuilder::new(self, class)
344 }
345
346 pub fn instances(&self) -> Instances<'_> {
348 Instances::new(self)
349 }
350
351 pub fn multifield_builder(&self, capacity: usize) -> Result<MultifieldBuilder<'_>> {
354 MultifieldBuilder::new(self, capacity)
355 }
356
357 pub fn function_call(&self, capacity: usize) -> Result<FunctionCall<'_>> {
360 FunctionCall::new(self, capacity)
361 }
362 pub fn register_router<R: Router>(
370 &mut self,
371 name: &str,
372 priority: i32,
373 router: R,
374 ) -> std::result::Result<(), RouterError> {
375 let entry = RouterEntry::register(self.raw, name, priority, router)?;
376 self.routers.push(entry);
377 Ok(())
378 }
379 pub fn remove_router(&mut self, name: &str) -> std::result::Result<(), RouterError> {
384 let position = self
385 .routers
386 .iter()
387 .position(|entry| entry.name().to_bytes() == name.as_bytes())
388 .ok_or(RouterError::NotFound)?;
389 let entry = self.routers.remove(position);
390 match entry.unregister(self.raw) {
391 Ok(()) => Ok(()),
392 Err((entry, error)) => {
393 self.routers.insert(position, entry);
394 Err(error)
395 }
396 }
397 }
398 pub fn activate_router(&mut self, name: &str) -> std::result::Result<(), RouterError> {
400 self.router_entry(name)?.activate(self.raw)
401 }
402
403 pub fn deactivate_router(&mut self, name: &str) -> std::result::Result<(), RouterError> {
405 self.router_entry(name)?.deactivate(self.raw)
406 }
407 fn router_entry(&self, name: &str) -> std::result::Result<&RouterEntry, RouterError> {
408 self.routers
409 .iter()
410 .find(|entry| entry.name().to_bytes() == name.as_bytes())
411 .ok_or(RouterError::NotFound)
412 }
413 pub fn add_udf<F>(
425 &mut self,
426 name: &str,
427 signature: UdfSignature,
428 callback: F,
429 ) -> std::result::Result<(), UdfRegistrationError>
430 where
431 F: for<'call> FnMut(
432 &[UdfValue<'call>],
433 ) -> std::result::Result<UdfReturn<'call>, UdfCallbackError>
434 + 'static,
435 {
436 let name = CString::new(name).map_err(UdfRegistrationError::from)?;
437 let mut registration = UdfRegistration::new(name, signature, callback);
438 let context = registration.context();
439 let argument_types = registration
440 .signature
441 .arguments
442 .as_ref()
443 .map_or(std::ptr::null(), |value| value.as_ptr());
444 let code = unsafe {
445 ffi::AddUDF(
446 self.raw.as_ptr(),
447 registration.name.as_ptr(),
448 registration.signature.returns.as_ptr(),
449 registration.signature.min_args,
450 registration.signature.max_args,
451 argument_types,
452 Some(crate::udf::trampoline),
453 registration.name.as_ptr(),
454 context,
455 )
456 };
457 if code != 0 {
458 return Err(UdfRegistrationError::from_code(code));
459 }
460 self.udfs.push(registration);
461 Ok(())
462 }
463 pub fn remove_udf(&mut self, name: &str) -> std::result::Result<(), UdfRegistrationError> {
465 let position = self
466 .udfs
467 .iter()
468 .position(|entry| entry.name.to_bytes() == name.as_bytes())
469 .ok_or(UdfRegistrationError::NotFound)?;
470 if unsafe { ffi::RemoveUDF(self.raw.as_ptr(), self.udfs[position].name.as_ptr()) } {
471 self.udfs.remove(position);
472 Ok(())
473 } else {
474 Err(UdfRegistrationError::NotFound)
475 }
476 }
477 pub fn take_udf_error(&self, name: &str) -> Option<UdfCallbackError> {
482 self.udfs
483 .iter()
484 .find(|entry| entry.name.to_bytes() == name.as_bytes())
485 .and_then(|entry| entry.take_error())
486 }
487 pub fn add_hook<F>(
494 &mut self,
495 name: &str,
496 kind: HookKind,
497 priority: i32,
498 callback: F,
499 ) -> std::result::Result<(), HookError>
500 where
501 F: FnMut() + 'static,
502 {
503 self.reject_duplicate_hook(name)?;
504 let entry = HookEntry::void(self.raw.as_ptr(), name, kind, priority, callback)?;
505 self.hooks.push(entry);
506 Ok(())
507 }
508 pub fn add_veto_hook<F>(
511 &mut self,
512 name: &str,
513 kind: ReadyHookKind,
514 priority: i32,
515 callback: F,
516 ) -> std::result::Result<(), HookError>
517 where
518 F: FnMut() -> bool + 'static,
519 {
520 self.reject_duplicate_hook(name)?;
521 let entry = HookEntry::ready(self.raw.as_ptr(), name, kind, priority, callback)?;
522 self.hooks.push(entry);
523 Ok(())
524 }
525 pub fn add_clear_ready_hook<F>(
531 &mut self,
532 name: &str,
533 priority: i32,
534 callback: F,
535 ) -> std::result::Result<(), HookError>
536 where
537 F: FnMut() -> bool + 'static,
538 {
539 self.add_veto_hook(name, ReadyHookKind::Clear, priority, callback)
540 }
541 pub fn add_rule_fire_hook<F>(
543 &mut self,
544 name: &str,
545 phase: RuleFirePhase,
546 priority: i32,
547 callback: F,
548 ) -> std::result::Result<(), HookError>
549 where
550 F: FnMut(&str) + 'static,
551 {
552 self.reject_duplicate_hook(name)?;
553 let entry = HookEntry::rule_fired(self.raw.as_ptr(), name, phase, priority, callback)?;
554 self.hooks.push(entry);
555 Ok(())
556 }
557 pub fn add_fact_hook<F>(
563 &mut self,
564 name: &str,
565 kind: FactEventKind,
566 priority: i32,
567 callback: F,
568 ) -> std::result::Result<(), HookError>
569 where
570 F: FnMut(&FactChange) + 'static,
571 {
572 self.reject_duplicate_hook(name)?;
573 let entry = HookEntry::fact(self.raw.as_ptr(), name, kind, priority, callback)?;
574 self.hooks.push(entry);
575 Ok(())
576 }
577 pub fn add_save_hook<F>(
582 &mut self,
583 name: &str,
584 priority: i32,
585 callback: F,
586 ) -> std::result::Result<(), HookError>
587 where
588 F: FnMut(&str, &str) + 'static,
589 {
590 self.reject_duplicate_hook(name)?;
591 let entry = HookEntry::save(self.raw.as_ptr(), name, priority, callback)?;
592 self.hooks.push(entry);
593 Ok(())
594 }
595 pub fn set_parser_error_hook<F>(&mut self, callback: F)
605 where
606 F: FnMut(&ParserDiagnostic) + 'static,
607 {
608 let context = ParserErrorContext::install(self.raw.as_ptr(), callback);
611 self.parser_error = Some(context);
612 }
613 pub fn clear_parser_error_hook(&mut self) {
615 ParserErrorContext::clear(self.raw.as_ptr());
616 self.parser_error = None;
617 }
618 fn reject_duplicate_hook(&self, name: &str) -> std::result::Result<(), HookError> {
623 if self
624 .hooks
625 .iter()
626 .any(|entry| entry.name() == name.as_bytes())
627 {
628 return Err(HookError::NameInUse);
629 }
630 Ok(())
631 }
632 pub fn remove_hook(&mut self, name: &str) -> std::result::Result<(), HookError> {
638 let position = self
639 .hooks
640 .iter()
641 .position(|entry| entry.name() == name.as_bytes())
642 .ok_or(HookError::NotFound)?;
643 if self.hooks[position].unregister(self.raw.as_ptr()) {
644 self.hooks.remove(position);
645 Ok(())
646 } else {
647 Err(HookError::NotFound)
648 }
649 }
650}
651
652impl Default for Environment {
653 fn default() -> Self {
654 Self::new().expect("CLIPS environment creation failed")
655 }
656}
657impl Drop for Environment {
658 fn drop(&mut self) {
659 if self.parser_error.is_some() {
662 ParserErrorContext::clear(self.raw.as_ptr());
663 }
664 let parser_error = self.parser_error.take();
665
666 let mut hooks = std::mem::take(&mut self.hooks);
667 hooks.retain(|entry| !entry.unregister(self.raw.as_ptr()));
668
669 let mut udfs = std::mem::take(&mut self.udfs);
670 udfs.retain(|registration| unsafe {
671 !ffi::RemoveUDF(self.raw.as_ptr(), registration.name.as_ptr())
672 });
673
674 let mut routers = Vec::new();
675 for entry in std::mem::take(&mut self.routers) {
676 if let Err((entry, _)) = entry.unregister(self.raw) {
677 routers.push(entry);
678 }
679 }
680
681 if !unsafe { ffi::DestroyEnvironment(self.raw.as_ptr()) } {
682 std::mem::forget(hooks);
685 std::mem::forget(udfs);
686 std::mem::forget(routers);
687 std::mem::forget(parser_error);
688 }
689 }
690}