Expand description
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
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);§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, an unmade Instance answers
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.
Structs§
- Activation
- A rule activation on the agenda.
- Activations
- Iterates the agenda of the module in focus, highest priority first.
- Class
Slot - A named slot borrowed from a class, used to inspect its facets and constraints.
- Defclass
- A handle to one Defclass construct.
- Deffacts
- A handle to one Deffacts construct.
- Deffunction
- A handle to one Deffunction construct.
- Deffunction
Arity - A deffunction’s declared arity.
- Defgeneric
- A handle to one Defgeneric construct.
- Defglobal
- A handle to one Defglobal construct.
- Definstances
- A handle to one Definstances construct.
- Defmethod
- A method belonging to a
Defgeneric. - Defmethods
- Iterates a generic function’s methods in index order.
- Defmodule
- A handle to one Defmodule construct.
- Defrule
- A handle to one Defrule construct.
- Deftemplate
- A handle to one Deftemplate construct.
- Dribble
- Stops dribbling when dropped.
- Environment
- An owning, single-thread-affine CLIPS environment.
- Fact
- A fact, retained for as long as the handle lives.
- Fact
Builder - Builds a fact slot by slot, then asserts it.
- Fact
Event - A fact identified for a lifecycle callback.
- Fact
Modifier - Collects slot changes and applies them as a single modification.
- Facts
- Iterates every fact in the environment, in index order.
- Facts
InTemplate - Iterator over the facts asserted against one deftemplate.
- Focus
Entry - A snapshot of an entry in the focus stack.
- Focus
Stack - Immutable traversal of the environment’s focus stack, from top to bottom.
- Function
Call - Calls a CLIPS function with typed arguments.
- Instance
- A COOL instance, retained for as long as the handle lives.
- Instance
Builder - Builds an instance slot by slot, then creates it.
- Instance
Modifier - Collects slot changes and applies them as a single modification.
- Instances
- Iterates every instance in the environment, in every module.
- Instances
InClass - Iterator over the direct instances of one class.
- Match
Summary - Counts summarising how far a rule’s patterns have matched.
- Message
Call - A message send with typed arguments.
- Message
Handler - A message-handler index tied to an immutable borrow of its class.
- Message
Handlers - Iterates a class’s own message handlers, excluding inherited ones.
- Method
Restrictions - A method’s arity and parameter restrictions.
- Multifield
- A retained CLIPS multifield: an ordered sequence of values.
- Multifield
Builder - Builds a multifield by appending fields in order.
- Parameter
Restriction - The restrictions on one method parameter.
- Parser
Diagnostic - A parser diagnostic, with every string copied out of CLIPS’s buffers.
- Template
Slot - A named slot borrowed from a deftemplate.
- UdfExternal
Address - An address CLIPS passed into the current UDF invocation.
- UdfFact
- An address CLIPS passed into the current UDF invocation.
- UdfInstance
- An address CLIPS passed into the current UDF invocation.
- UdfSignature
- Arity and type restrictions passed to CLIPS when registering a UDF.
- UdfSignature
Builder - Builder for
UdfSignature. - Value
- A retained CLIPS value.
Enums§
- Assertion
Error - Why asserting a fact from text failed.
- Build
Error - Why defining a construct failed.
- Class
Defaults Mode - Whether CLIPS creates slot accessor handlers a defclass does not declare.
- Class
Error - Why a class or message-handler operation failed.
- Error
- Anything that can go wrong in a CLIPS operation.
- Evaluation
Error - Why evaluating an expression failed.
- Fact
Builder Error - Why a fact builder could not produce a fact.
- Fact
Change - What happened to a fact, as reported to a fact hook.
- Fact
Event Kind - Which fact-lifecycle event a callback observes.
- Fact
Modifier Error - Why modifying a fact failed.
- Function
Call Error - Why calling a CLIPS function failed.
- GetSlot
Error - Why reading a slot failed.
- Handler
Type - Which stage of a message send a handler runs in.
- Hook
Error - Why registering or removing a hook failed.
- Hook
Kind - A CLIPS lifecycle event a Rust callback can be attached to.
- Instance
Builder Error - Why an instance builder could not produce an instance.
- Instance
Modifier Error - Why modifying an instance failed.
- Load
Error - Why loading constructs failed.
- Make
Instance Error - Why creating an instance from
make-instancesyntax failed. - Module
Error - Why a module operation failed.
- Persistence
Error - Identifies a persistence operation which CLIPS could not complete.
- PutSlot
Error - Why writing a slot failed.
- Ready
Hook Kind - Which veto hook a callback answers.
- Retraction
Error - Why retracting a fact failed.
- Router
Error - Why registering or removing a router failed.
- Rule
Fire Phase - Whether a rule-fire callback runs before or after the rule’s actions.
- Salience
Evaluation - When CLIPS evaluates a rule’s salience expression.
- Save
Scope - Selects which constructs are included when facts or instances are saved.
- Slot
Default Type - What kind of default value a slot has.
- Strategy
- How CLIPS orders activations of equal salience on the agenda.
- Template
Error - Why a deftemplate slot query failed.
- UdfCallback
Error - Error produced by a Rust UDF invocation.
- UdfRegistration
Error - Why registering or removing a user-defined function failed.
- UdfReturn
- A value returned from a Rust UDF to CLIPS.
- UdfType
- CLIPS types used to describe UDF arguments and results.
- UdfValue
- A value supplied to a Rust UDF by CLIPS.
- Unmake
Instance Error - Why deleting an instance failed.
- Verbosity
- How much detail CLIPS prints to the routers while summarising matches.
- Watch
Error - Why a watch or dribble operation failed.
- Watch
Item - A built-in CLIPS watch category.
Traits§
- Router
- A destination and/or source for CLIPS logical I/O names.
Type Aliases§
- Result
- The result type used throughout the crate.