Skip to main content

Crate clips_bindings

Crate clips_bindings 

Source
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.
ClassSlot
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.
DeffunctionArity
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.
FactBuilder
Builds a fact slot by slot, then asserts it.
FactEvent
A fact identified for a lifecycle callback.
FactModifier
Collects slot changes and applies them as a single modification.
Facts
Iterates every fact in the environment, in index order.
FactsInTemplate
Iterator over the facts asserted against one deftemplate.
FocusEntry
A snapshot of an entry in the focus stack.
FocusStack
Immutable traversal of the environment’s focus stack, from top to bottom.
FunctionCall
Calls a CLIPS function with typed arguments.
Instance
A COOL instance, retained for as long as the handle lives.
InstanceBuilder
Builds an instance slot by slot, then creates it.
InstanceModifier
Collects slot changes and applies them as a single modification.
Instances
Iterates every instance in the environment, in every module.
InstancesInClass
Iterator over the direct instances of one class.
MatchSummary
Counts summarising how far a rule’s patterns have matched.
MessageCall
A message send with typed arguments.
MessageHandler
A message-handler index tied to an immutable borrow of its class.
MessageHandlers
Iterates a class’s own message handlers, excluding inherited ones.
MethodRestrictions
A method’s arity and parameter restrictions.
Multifield
A retained CLIPS multifield: an ordered sequence of values.
MultifieldBuilder
Builds a multifield by appending fields in order.
ParameterRestriction
The restrictions on one method parameter.
ParserDiagnostic
A parser diagnostic, with every string copied out of CLIPS’s buffers.
TemplateSlot
A named slot borrowed from a deftemplate.
UdfExternalAddress
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.
UdfSignatureBuilder
Builder for UdfSignature.
Value
A retained CLIPS value.

Enums§

AssertionError
Why asserting a fact from text failed.
BuildError
Why defining a construct failed.
ClassDefaultsMode
Whether CLIPS creates slot accessor handlers a defclass does not declare.
ClassError
Why a class or message-handler operation failed.
Error
Anything that can go wrong in a CLIPS operation.
EvaluationError
Why evaluating an expression failed.
FactBuilderError
Why a fact builder could not produce a fact.
FactChange
What happened to a fact, as reported to a fact hook.
FactEventKind
Which fact-lifecycle event a callback observes.
FactModifierError
Why modifying a fact failed.
FunctionCallError
Why calling a CLIPS function failed.
GetSlotError
Why reading a slot failed.
HandlerType
Which stage of a message send a handler runs in.
HookError
Why registering or removing a hook failed.
HookKind
A CLIPS lifecycle event a Rust callback can be attached to.
InstanceBuilderError
Why an instance builder could not produce an instance.
InstanceModifierError
Why modifying an instance failed.
LoadError
Why loading constructs failed.
MakeInstanceError
Why creating an instance from make-instance syntax failed.
ModuleError
Why a module operation failed.
PersistenceError
Identifies a persistence operation which CLIPS could not complete.
PutSlotError
Why writing a slot failed.
ReadyHookKind
Which veto hook a callback answers.
RetractionError
Why retracting a fact failed.
RouterError
Why registering or removing a router failed.
RuleFirePhase
Whether a rule-fire callback runs before or after the rule’s actions.
SalienceEvaluation
When CLIPS evaluates a rule’s salience expression.
SaveScope
Selects which constructs are included when facts or instances are saved.
SlotDefaultType
What kind of default value a slot has.
Strategy
How CLIPS orders activations of equal salience on the agenda.
TemplateError
Why a deftemplate slot query failed.
UdfCallbackError
Error produced by a Rust UDF invocation.
UdfRegistrationError
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.
UnmakeInstanceError
Why deleting an instance failed.
Verbosity
How much detail CLIPS prints to the routers while summarising matches.
WatchError
Why a watch or dribble operation failed.
WatchItem
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.