clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
//! Safe, idiomatic Rust bindings to CLIPS 6.4.2.
//!
//! The unsafe C interface is private. Public handles are lifetime-bound to the
//! environment that owns them, and allocated CLIPS resources use RAII. CLIPS
//! environments and their handles are single-thread-affine and therefore
//! implement neither [`Send`] nor [`Sync`].
//!
//! Everything here is custom-written: there is no bindgen output, and the only
//! C compiled into the crate is the unmodified CLIPS 6.4.2 source tree.
//!
//! # Getting started
//!
//! ```no_run
//! use clips_bindings::Environment;
//!
//! let mut environment = Environment::new()?;
//! environment.build("(deftemplate person (slot name) (slot age))")?;
//! environment.build("(defrule adult (person (age ?a&:(>= ?a 18))) => )")?;
//!
//! let fact = environment.assert_string("(person (name Ada) (age 36))")?;
//! assert_eq!(fact.slot("name")?.as_str(), Some("Ada"));
//! drop(fact);
//!
//! environment.run(None);
//! # Ok::<(), clips_bindings::Error>(())
//! ```
//!
//! # Borrowing and invalidation
//!
//! Handles such as [`Fact`], [`Instance`], [`Value`], and the construct types
//! borrow their [`Environment`] immutably. Every operation that can invalidate
//! what a handle refers to takes `&mut Environment`, so the borrow checker
//! rejects it while any handle is alive. That covers [`Environment::clear`],
//! [`Environment::reset`], [`Environment::run`], [`Environment::build`],
//! binary loads, and every undefinition method.
//!
//! Builders borrow immutably too, so several may exist at once and values
//! created with [`Environment::create_integer`] and friends stay usable while a
//! builder is being filled in.
//!
//! Some invalidation cannot be expressed in the type system, and those APIs
//! report it instead: a retracted [`Fact`] answers
//! [`is_retracted`](Fact::is_retracted), an unmade [`Instance`] answers
//! [`is_deleted`](Instance::is_deleted), and a stale fact index resolves to
//! `None` through [`Environment::find_fact`].
//!
//! # Retention and garbage collection
//!
//! CLIPS reference-counts the values it hands out and reclaims unreferenced
//! ones at garbage-collection points. Every value this crate returns past the
//! originating call is retained on creation and released exactly once on drop,
//! so a [`Value`] stays valid for as long as it is held, regardless of what
//! CLIPS does in between. Values are therefore cheap to hold but not free: drop
//! them when done rather than accumulating them across a long run.
//!
//! # Callbacks
//!
//! Routers, user-defined functions, and lifecycle hooks are owned by the
//! environment, stored at stable addresses, and unregistered before their
//! contexts are dropped. Every trampoline catches unwinding, so a Rust panic
//! never crosses the C boundary, and a reentrant invocation is refused rather
//! than aliasing the callback. A few CLIPS callback families have no removal
//! entry point; [`HookKind::is_removable`] reports which, and their allocations
//! are held until the environment is destroyed.

// Every public item is documented, and the build fails rather than letting a
// new one slip out undocumented. `ffi` is private, so its declarations are
// exempt.
#![deny(missing_docs)]

mod abi;
mod agenda;
mod class;
mod construct;
mod construct_manage;
mod data;
mod environment;
mod error;
mod fact;
mod ffi;
mod function;
mod generic;
mod hook;
mod instance;
mod module;
mod multifield;
mod persistence;
mod router;
mod template;
mod thread_safety;
mod udf;
mod value;
mod watch;

pub use agenda::{Activation, Activations, SalienceEvaluation, Strategy};
pub use class::{
    ClassDefaultsMode, ClassError, ClassSlot, HandlerType, MessageHandler, MessageHandlers,
};
pub use construct::{
    Defclass, Deffacts, Deffunction, Defgeneric, Defglobal, Definstances, Defmodule, Defrule,
    Deftemplate,
};
pub use construct_manage::{DeffunctionArity, MatchSummary, Verbosity};
pub use environment::Environment;
pub use error::{
    AssertionError, BuildError, Error, EvaluationError, FactBuilderError, FactModifierError,
    FunctionCallError, GetSlotError, InstanceBuilderError, InstanceModifierError, LoadError,
    MakeInstanceError, PutSlotError, Result, RetractionError, UnmakeInstanceError,
};
pub use fact::{Fact, FactBuilder, FactModifier, Facts, FactsInTemplate};
pub use function::FunctionCall;
pub use generic::{Defmethod, Defmethods, MethodRestrictions, ParameterRestriction};
pub use hook::{
    FactChange, FactEvent, FactEventKind, HookError, HookKind, ParserDiagnostic, ReadyHookKind,
    RuleFirePhase,
};
pub use instance::{
    Instance, InstanceBuilder, InstanceModifier, Instances, InstancesInClass, MessageCall,
};
pub use module::{FocusEntry, FocusStack, ModuleError};
pub use multifield::{Multifield, MultifieldBuilder};
pub use persistence::{PersistenceError, SaveScope};
pub use router::{Router, RouterError};
pub use template::{SlotDefaultType, TemplateError, TemplateSlot};
pub use udf::{
    UdfCallbackError, UdfExternalAddress, UdfFact, UdfInstance, UdfRegistrationError, UdfReturn,
    UdfSignature, UdfSignatureBuilder, UdfType, UdfValue,
};
pub use value::Value;
pub use watch::{Dribble, WatchError, WatchItem};