Skip to main content

clips_bindings/
lib.rs

1//! Safe, idiomatic Rust bindings to CLIPS 6.4.2.
2//!
3//! The unsafe C interface is private. Public handles are lifetime-bound to the
4//! environment that owns them, and allocated CLIPS resources use RAII. CLIPS
5//! environments and their handles are single-thread-affine and therefore
6//! implement neither [`Send`] nor [`Sync`].
7//!
8//! Everything here is custom-written: there is no bindgen output, and the only
9//! C compiled into the crate is the unmodified CLIPS 6.4.2 source tree.
10//!
11//! # Getting started
12//!
13//! ```no_run
14//! use clips_bindings::Environment;
15//!
16//! let mut environment = Environment::new()?;
17//! environment.build("(deftemplate person (slot name) (slot age))")?;
18//! environment.build("(defrule adult (person (age ?a&:(>= ?a 18))) => )")?;
19//!
20//! let fact = environment.assert_string("(person (name Ada) (age 36))")?;
21//! assert_eq!(fact.slot("name")?.as_str(), Some("Ada"));
22//! drop(fact);
23//!
24//! environment.run(None);
25//! # Ok::<(), clips_bindings::Error>(())
26//! ```
27//!
28//! # Borrowing and invalidation
29//!
30//! Handles such as [`Fact`], [`Instance`], [`Value`], and the construct types
31//! borrow their [`Environment`] immutably. Every operation that can invalidate
32//! what a handle refers to takes `&mut Environment`, so the borrow checker
33//! rejects it while any handle is alive. That covers [`Environment::clear`],
34//! [`Environment::reset`], [`Environment::run`], [`Environment::build`],
35//! binary loads, and every undefinition method.
36//!
37//! Builders borrow immutably too, so several may exist at once and values
38//! created with [`Environment::create_integer`] and friends stay usable while a
39//! builder is being filled in.
40//!
41//! Some invalidation cannot be expressed in the type system, and those APIs
42//! report it instead: a retracted [`Fact`] answers
43//! [`is_retracted`](Fact::is_retracted), an unmade [`Instance`] answers
44//! [`is_deleted`](Instance::is_deleted), and a stale fact index resolves to
45//! `None` through [`Environment::find_fact`].
46//!
47//! # Retention and garbage collection
48//!
49//! CLIPS reference-counts the values it hands out and reclaims unreferenced
50//! ones at garbage-collection points. Every value this crate returns past the
51//! originating call is retained on creation and released exactly once on drop,
52//! so a [`Value`] stays valid for as long as it is held, regardless of what
53//! CLIPS does in between. Values are therefore cheap to hold but not free: drop
54//! them when done rather than accumulating them across a long run.
55//!
56//! # Callbacks
57//!
58//! Routers, user-defined functions, and lifecycle hooks are owned by the
59//! environment, stored at stable addresses, and unregistered before their
60//! contexts are dropped. Every trampoline catches unwinding, so a Rust panic
61//! never crosses the C boundary, and a reentrant invocation is refused rather
62//! than aliasing the callback. A few CLIPS callback families have no removal
63//! entry point; [`HookKind::is_removable`] reports which, and their allocations
64//! are held until the environment is destroyed.
65
66// Every public item is documented, and the build fails rather than letting a
67// new one slip out undocumented. `ffi` is private, so its declarations are
68// exempt.
69#![deny(missing_docs)]
70
71mod abi;
72mod agenda;
73mod class;
74mod construct;
75mod construct_manage;
76mod data;
77mod environment;
78mod error;
79mod fact;
80mod ffi;
81mod function;
82mod generic;
83mod hook;
84mod instance;
85mod module;
86mod multifield;
87mod persistence;
88mod router;
89mod template;
90mod thread_safety;
91mod udf;
92mod value;
93mod watch;
94
95pub use agenda::{Activation, Activations, SalienceEvaluation, Strategy};
96pub use class::{
97    ClassDefaultsMode, ClassError, ClassSlot, HandlerType, MessageHandler, MessageHandlers,
98};
99pub use construct::{
100    Defclass, Deffacts, Deffunction, Defgeneric, Defglobal, Definstances, Defmodule, Defrule,
101    Deftemplate,
102};
103pub use construct_manage::{DeffunctionArity, MatchSummary, Verbosity};
104pub use environment::Environment;
105pub use error::{
106    AssertionError, BuildError, Error, EvaluationError, FactBuilderError, FactModifierError,
107    FunctionCallError, GetSlotError, InstanceBuilderError, InstanceModifierError, LoadError,
108    MakeInstanceError, PutSlotError, Result, RetractionError, UnmakeInstanceError,
109};
110pub use fact::{Fact, FactBuilder, FactModifier, Facts, FactsInTemplate};
111pub use function::FunctionCall;
112pub use generic::{Defmethod, Defmethods, MethodRestrictions, ParameterRestriction};
113pub use hook::{
114    FactChange, FactEvent, FactEventKind, HookError, HookKind, ParserDiagnostic, ReadyHookKind,
115    RuleFirePhase,
116};
117pub use instance::{
118    Instance, InstanceBuilder, InstanceModifier, Instances, InstancesInClass, MessageCall,
119};
120pub use module::{FocusEntry, FocusStack, ModuleError};
121pub use multifield::{Multifield, MultifieldBuilder};
122pub use persistence::{PersistenceError, SaveScope};
123pub use router::{Router, RouterError};
124pub use template::{SlotDefaultType, TemplateError, TemplateSlot};
125pub use udf::{
126    UdfCallbackError, UdfExternalAddress, UdfFact, UdfInstance, UdfRegistrationError, UdfReturn,
127    UdfSignature, UdfSignatureBuilder, UdfType, UdfValue,
128};
129pub use value::Value;
130pub use watch::{Dribble, WatchError, WatchItem};