clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
# CLIPS 6.4.2 embedding API coverage

This maps the Advanced Programming Guide's embedding API to the safe Rust
surface. "Excluded" entries are deliberate, with the reason given; the crate is
Rust-only for everything that runs, so anything reachable solely through private
struct fields or C macros is either derived from a public API or left unbound
rather than reached with a C shim.

The single exception is `shim/abi_layout.c`, which exists only so the C compiler
can report `sizeof` and `offsetof` for the structures `src/ffi.rs` redeclares. It
executes nothing and CLIPS never calls it; see `src/abi.rs`.

## 3 — Environment and execution

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `CreateEnvironment`, `DestroyEnvironment` | `Environment::new`, `Drop` | RAII; callbacks unregistered before their contexts drop |
| `Clear`, `Reset`, `Run` | `Environment::clear`, `reset`, `run` | `&mut self`, so handles cannot be alive |
| `Build` | `Environment::build` | typed `BuildError` |
| `Load`, `LoadFromString` | `Environment::load`, `load_str` | `LoadFromString` returns bool in C; `load_str` maps failure to `LoadError::Parsing` |
| `Eval` | `Environment::eval` | retained typed result |
| `Save`, `Bsave`, `Bload`, `Bloaded` | `save_constructs`, `binary_save_constructs`, `binary_load_constructs`, `constructs_are_binary_loaded` | |
| `MemUsed`, `MemRequests`, `ReleaseMem`, conserve-memory | `memory_used`, `memory_requests`, `release_memory`, `conserve_memory` | |
| `GetHaltExecution`, `SetHaltExecution` | `halt_execution`, `set_halt_execution` | the getter reports a failed `eval` until the next one; setting cannot interrupt a run, which clears the flag on entry — tested |
| `GetHaltRules`, `SetHaltRules` | `halt_rules`, `set_halt_rules` | bound for completeness; `Run` clears the flag on entry and return, so it never stops a run and always reads `false` outside one — tested |
| `GetBetaMemoryResizing`, `SetBetaMemoryResizing` | `beta_memory_resizing`, `set_beta_memory_resizing` | |
| `Halt` | **Excluded** | identical in effect to `set_halt_rules(true)`, which a test shows to be inert from safe Rust; binding a second, more promising name for an operation that cannot stop a run would mislead |

## 4 — Values, multifields, and external addresses

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `CreateInteger`, `CreateFloat`, `CreateSymbol`, `CreateString`, `CreateInstanceName`, `CreateBoolean` | `Environment::create_*` | retained `Value` |
| `RetainCV`, `ReleaseCV` | automatic | every returned value is retained once and released on drop |
| Multifield builder | `MultifieldBuilder` | typed appends plus a generic `Value` append |
| `StringToMultifield`, `ImplodeMultifield` | `Environment::string_to_multifield`, `Multifield::implode` | |
| External address registration | **Excluded for now** | needs a Rust payload-destruction and type-id design; UDFs can already pass through addresses CLIPS supplied |

## 5 — Facts

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `AssertString`, `Retract` | `Environment::assert_string`, `Fact::retract` | typed errors |
| Fact builder and modifier | `FactBuilder`, `FactModifier` | typed slots plus generic `Value` slots |
| `GetFactSlot`, `FactSlotNames` | `Fact::slot`, `Fact::slot_names` | |
| `FactIndex`, `FindIndexedFact`, `FactIsDeleted` | `Fact::index`, `Environment::find_fact`, `Fact::is_retracted` | |
| `FactRelation`, `FactDeftemplate` | `Fact::relation`, `Fact::template` | |
| `GetNextFact`, `GetNextFactInTemplate` | `Environment::facts`, `facts_in_template` | |
| `GetFactListChanged`, `SetFactListChanged` | `Environment::fact_list_changed`, `set_fact_list_changed` | |
| `RetractAllFacts` | `Environment::retract_all_facts` | one operation, unlike retracting each fact in turn |
| Assert/retract/modify hooks | `Environment::add_fact_hook` | reports `FactChange`; modification arrives as two calls |
| Fact save/load, binary and text | `save_facts`, `load_facts`, `load_facts_str`, `binary_save_facts`, `binary_load_facts` | negative counts become typed errors |

## 6 — Instances and COOL

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `MakeInstance`, `UnmakeInstance` | `Environment::make_instance`, `Instance::unmake` | typed errors, including CLIPS returning neither instance nor error code |
| Instance builder and modifier | `InstanceBuilder`, `InstanceModifier` | typed slots plus generic `Value` slots |
| `DirectGetSlot`, `DirectPutSlot*` | `Instance::slot`, `Instance::put_*` | immediate writes, unlike the modifier |
| `FindInstance` | `Environment::find_instance` | module and import search are explicit parameters |
| `InstanceClass` | `Instance::class` | |
| `GetNextInstance`, `GetNextInstanceInClass` | `Environment::instances`, `instances_in_class` | |
| `GetNextInstanceInClassAndSubclasses` | **Excluded for now** | needs a retained-cursor design: CLIPS makes the caller own the traversal's `UDFValue` and class cursor |
| `Send` | `Instance::send` returning `MessageCall` | typed arguments through the function-call builder, since C `Send` only takes argument text |
| `UnmakeAllInstances` | `Environment::unmake_all_instances` | |
| `GetGlobalNumberOfInstances` | `Environment::instance_count` | |
| `GetInstancesChanged`, `SetInstancesChanged` | `instances_changed`, `set_instances_changed` | |
| Instance lifecycle callbacks | **Excluded** | CLIPS 6.4.2 has no public instance-callback registry; use message handlers or pattern matching |
| Instance save/load/restore | `save_instances`, `load_instances`, `restore_instances`, binary variants | |

## 7 — Deftemplates and constructs

| CLIPS | Rust | Notes |
| --- | --- | --- |
| Find/iterate every construct family | `Environment::find_*`, iterators | typed handles borrowing the environment |
| Names, modules, pretty-print, deletability | `name`, `module_name`, `pretty_print`, `is_deletable` | |
| Undefinition | `Environment::undefine_*` | name-based, resolved under `&mut Environment` |
| Deftemplate slot metadata and constraints | `Deftemplate::slot_names`, `TemplateSlot` | defaults, types, allowed values, range, cardinality |
| Implied deftemplate flag | `Deftemplate::is_implied` | derived from the absent pretty-print form; caveat documented |
| Deftemplate allowed classes | **Excluded** | CLIPS has no deftemplate allowed-classes accessor; the COOL query is on `ClassSlot` |
| Deffunction arity | `Deffunction::arity` | read from the pretty-print parameter list; caveat documented |

## 8 — Defclasses and message handlers

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `ClassAbstractP`, `ClassReactiveP` | `Defclass::is_abstract`, `is_reactive` | |
| `ClassSlots`, `ClassSuperclasses`, `ClassSubclasses` | `Defclass::slots`, `superclasses`, `subclasses` | |
| `SuperclassP`, `SubclassP` | `Defclass::is_superclass_of`, `is_subclass_of` | handles prove shared environment ownership |
| Class precedence list | `Defclass::precedence_list` | |
| `SlotExistP`, `SlotSources`, `SlotFacets`, `SlotTypes`, `SlotAllowedValues`, `SlotAllowedClasses`, `SlotRange`, `SlotCardinality`, `SlotDefaultValue`, `SlotDefaultP`, `SlotWritableP`, `SlotInitableP`, `SlotPublicP`, `SlotDirectAccessP` | `Defclass::slot` returning `ClassSlot` | `is_public` and `default_type` do not follow inheritance in CLIPS; documented and tested |
| Handler traversal, lookup, type, pretty-print, deletability, watch | `MessageHandler` | |
| `UndefmessageHandler` | `Environment::undefine_message_handler` | resolved immediately before deletion |
| `PreviewSend` | `Defclass::preview_send` | CLIPS only prints the handler chain, so capture it with a `Router` |
| `GetClassDefaultsMode`, `SetClassDefaultsMode` | `class_defaults_mode`, `set_class_defaults_mode` | despite the CLIPS name this controls accessor-handler creation, not slot defaults; tested |

## 9 — Defgenerics, defmethods, defglobals

| CLIPS | Rust | Notes |
| --- | --- | --- |
| Method traversal and lookup | `Defgeneric::methods`, `method` | |
| `DefmethodPPForm`, description, deletability, watch | `Defmethod` | |
| `GetMethodRestrictions` | `Defmethod::restrictions` | structured `MethodRestrictions`; the raw value is still available |
| `Undefmethod` | `Environment::undefine_defmethod` | |
| `DefglobalGetValue`, `DefglobalSet*` | `Environment::defglobal_value`, `set_defglobal_*` | generic value setter stores facts, instances, and multifields |
| Reset-globals behaviour | `Environment::reset_globals`, `set_reset_globals` | |
| `GetGlobalsChanged`, `SetGlobalsChanged` | `globals_changed`, `set_globals_changed` | |

## 10 — Agenda, rules, modules, focus

| CLIPS | Rust | Notes |
| --- | --- | --- |
| Activation traversal, salience, move-to-top, delete | `Activations`, `Activation` | |
| Strategy and salience evaluation | `Environment::strategy`, `salience_evaluation` | typed enums |
| Refresh/reorder, all and per module | `refresh_agendas`, `refresh_module_agenda`, and reorder counterparts | module APIs are name-based |
| `RemoveAllActivations`, agenda-changed | `remove_all_activations`, `agenda_changed` | |
| Breakpoints | `set_rule_breakpoint`, `remove_rule_breakpoint`, `remove_all_breakpoints`, `breakpoint_rule_names` | listing walks the rules rather than using router-printing `ShowBreaks` |
| `Matches` | `Defrule::matches` returning `MatchSummary` | no rete internals exposed |
| Disjuncts | `Defrule::disjuncts` | |
| Focus stack | `focus`, `pop_focus`, `focus_stack`, `current_focus`, `clear_focus_stack` | |
| `GetFocusChanged`, `SetFocusChanged` | `focus_changed`, `set_focus_changed` | |
| Module list and current module | `module_names`, `current_module`, `set_current_module` | |
| Module import/export inspection | **Excluded** | port items live in private struct fields; the pretty-print form carries the text |
| Before/after rule-fire hooks | `Environment::add_rule_fire_hook` | receives the rule name |

## 11 — I/O routers and diagnostics

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `AddRouter` and friends | `Router` trait, `register_router`, activate/deactivate/remove | panic-contained, reentrancy-refusing |
| Watch categories and named items | `WatchItem`, `watch`, `watch_named`, `watch_states` | `all` handled specially, matching CLIPS |
| Dribble | `dribble_on`, `dribble_active`, `dribble_off`, `dribble_to` | `dribble_to` returns an owned `Dribble` guard that stops dribbling on drop |
| `Write`, `Writeln`, `WriteString` | `Environment::write`, `writeln`, `write_to` | output goes to the router claiming the logical name |
| Profiling | `profile_percent_threshold`, `set_profile_percent_threshold` | collection and reporting are CLIPS commands; run them with `eval` and capture with a router |
| Parser error callback | `set_parser_error_hook` | owned `ParserDiagnostic`; only the load path installs CLIPS's capture router |

## 12 — User-defined functions and extension

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `AddUDF`, `RemoveUDF` | `Environment::add_udf`, `remove_udf` | typed signatures, arity, and per-position restrictions |
| UDF arguments | `UdfValue` | addresses are opaque tokens bound to the invocation |
| UDF results | `UdfReturn` | scalars, multifields, and pass-through addresses |
| `UDFThrowError` | automatic | callback errors are deferred and retrieved by name |
| Reset/clear/clear-ready hooks | `add_hook`, `add_veto_hook` | |
| Periodic, cleanup, save, binary-load hooks | `add_hook`, `add_save_hook` | `HookKind::is_removable` reports which CLIPS can unregister |
| After-module-defined hook | **Excluded** | CLIPS calls that list through a cast that drops the context argument, so no Rust closure can be reached; binding it crashes |
| Environment data (`AllocateEnvironmentData`) | `Environment::insert_data`, `data`, `data_mut`, `remove_data` | type-keyed Rust storage, deliberately outside CLIPS's shared slot registry, so no slot number can collide |
| Rete, parser-expression, constraint, and construct-compiler structures | **Excluded by design** | not part of the safe surface |

## Families excluded wholesale

These appear throughout the headers rather than in one section. Each is
excluded for the same reason across every construct family.

| CLIPS | Rust | Notes |
| --- | --- | --- |
| `GetDefruleList`, `GetDeftemplateList`, `GetDefclassList`, and the other `Get*List` functions | **Excluded** | they return a multifield of names; the typed iterators give the same information with handles instead of strings |
| `ListDefrules`, `ListDefclasses`, `ListDefmethods`, `ListFocusStack`, `Agenda`, `Instances`, and the other `List*` printers | **Excluded** | router-printing only; the iterators expose the same data structurally |
| `PPDefrule`, `PPDeftemplate`, `PPDefglobal`, `PPFact` | `pretty_print` on each handle | CLIPS prints to a router; the Rust methods return the text |
| `DescribeClass`, `BrowseClasses` | **Excluded** | router-printing summaries; `Defclass` exposes the same facts as typed accessors |
| `Find*InModule` variants | `find_*` plus explicit module arguments where CLIPS offers them | the module-scoped variants take an already-resolved module pointer, which the safe API does not hand out |
| `SetFastLoad`, `SetFastSave`, `GetFastLoad`, `GetFastSave` | **Excluded** | they exchange raw `FILE *` handles, which cannot cross the safe boundary |
| `FindRouter`, `QueryRouters`, `ExitRouter`, `ReadRouter`, `UnreadRouter` | **Excluded** | CLIPS's internal router dispatch; the `Router` trait is the supported extension point |
| `UTF8Length`, `UTF8CharNum`, `UTF8Offset`, `UTF8Increment` | **Excluded** | Rust's own `str` handles UTF-8 |
| `FindSymbolMatches`, `GetNextSymbolMatch` | **Excluded** | command-completion helpers for a CLIPS shell, not embedding API |
| `StartProfile`, `EndProfile`, `Profile`, `ResetProfileInfo` | **Excluded** | profiling is driven by the `profile` commands; only the reporting threshold is bound |
| `AtomInstall`, `Retain*`, `Release*`, `CreateMultifield`, garbage-frame helpers | automatic | the crate retains and releases every value it hands out |