clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
//! Typed handles for every CLIPS construct family, plus lookup and
//! iteration.
//!
//! A handle borrows its environment, which is what stops `clear`, a binary
//! load, or an undefinition from running while it is alive.

use std::ffi::{CStr, CString};
use std::ptr::NonNull;

use crate::{Environment, Result, ffi};

macro_rules! construct_type {
    ($handle:ident, $iter:ident, $raw:ident, $method:ident, $find:ident, $next:ident, $name:ident) => {
        #[doc = concat!("A handle to one ", stringify!($handle), " construct.")]
        ///
        /// Borrowing the environment is what keeps it sound: undefining a
        /// construct, clearing, or loading a binary image all need
        /// `&mut Environment` and so cannot run while a handle is alive.
        pub struct $handle<'env> {
            pub(crate) raw: NonNull<ffi::$raw>,
            pub(crate) _environment: &'env Environment,
        }
        impl $handle<'_> {
            /// The construct's name, without any module prefix.
            pub fn name(&self) -> &str {
                unsafe { CStr::from_ptr(ffi::$name(self.raw.as_ptr())) }
                    .to_str()
                    .unwrap_or("")
            }
        }
        #[doc = concat!("Iterates every ", stringify!($handle), " in definition order.")]
        pub struct $iter<'env> {
            environment: &'env Environment,
            current: *mut ffi::$raw,
        }
        impl<'env> Iterator for $iter<'env> {
            type Item = $handle<'env>;
            fn next(&mut self) -> Option<Self::Item> {
                self.current = unsafe { ffi::$next(self.environment.raw.as_ptr(), self.current) };
                NonNull::new(self.current).map(|raw| $handle {
                    raw,
                    _environment: self.environment,
                })
            }
        }
        impl Environment {
            #[doc = concat!("Looks up a ", stringify!($handle), " by name.")]
            ///
            /// `None` if no construct of that name is visible from the current
            /// module.
            pub fn $method(&self, name: &str) -> Result<Option<$handle<'_>>> {
                let name = CString::new(name)?;
                Ok(
                    NonNull::new(unsafe { ffi::$find(self.raw.as_ptr(), name.as_ptr()) }).map(
                        |raw| $handle {
                            raw,
                            _environment: self,
                        },
                    ),
                )
            }
        }
    };
}

construct_type!(
    Deftemplate,
    Deftemplates,
    Deftemplate,
    find_deftemplate,
    FindDeftemplate,
    GetNextDeftemplate,
    DeftemplateName
);
construct_type!(
    Defrule,
    Defrules,
    Defrule,
    find_defrule,
    FindDefrule,
    GetNextDefrule,
    DefruleName
);
construct_type!(
    Deffacts,
    DeffactsIter,
    Deffacts,
    find_deffacts,
    FindDeffacts,
    GetNextDeffacts,
    DeffactsName
);
construct_type!(
    Defglobal,
    Defglobals,
    Defglobal,
    find_defglobal,
    FindDefglobal,
    GetNextDefglobal,
    DefglobalName
);
construct_type!(
    Deffunction,
    Deffunctions,
    Deffunction,
    find_deffunction,
    FindDeffunction,
    GetNextDeffunction,
    DeffunctionName
);
construct_type!(
    Defgeneric,
    Defgenerics,
    Defgeneric,
    find_defgeneric,
    FindDefgeneric,
    GetNextDefgeneric,
    DefgenericName
);
construct_type!(
    Defclass,
    Defclasses,
    Defclass,
    find_defclass,
    FindDefclass,
    GetNextDefclass,
    DefclassName
);
construct_type!(
    Definstances,
    DefinstancesIter,
    Definstances,
    find_definstances,
    FindDefinstances,
    GetNextDefinstances,
    DefinstancesName
);
construct_type!(
    Defmodule,
    Defmodules,
    Defmodule,
    find_defmodule,
    FindDefmodule,
    GetNextDefmodule,
    DefmoduleName
);

impl<'env> Defmodule<'env> {
    pub(crate) fn from_raw(environment: &'env Environment, raw: NonNull<ffi::Defmodule>) -> Self {
        Self {
            raw,
            _environment: environment,
        }
    }
}

impl Defclass<'_> {
    pub(crate) fn raw(&self) -> *mut ffi::Defclass {
        self.raw.as_ptr()
    }
}

impl Environment {
    /// Iterates every deftemplate, including the implied templates CLIPS creates for ordered facts.
    pub fn deftemplates(&self) -> Deftemplates<'_> {
        Deftemplates {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every defrule.
    pub fn defrules(&self) -> Defrules<'_> {
        Defrules {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every deffacts.
    pub fn deffacts(&self) -> DeffactsIter<'_> {
        DeffactsIter {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every defglobal.
    pub fn defglobals(&self) -> Defglobals<'_> {
        Defglobals {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every deffunction.
    pub fn deffunctions(&self) -> Deffunctions<'_> {
        Deffunctions {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every defgeneric.
    pub fn defgenerics(&self) -> Defgenerics<'_> {
        Defgenerics {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every defclass, including the built-in classes such as USER and OBJECT.
    pub fn defclasses(&self) -> Defclasses<'_> {
        Defclasses {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every definstances construct.
    pub fn definstances(&self) -> DefinstancesIter<'_> {
        DefinstancesIter {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
    /// Iterates every defmodule, starting with MAIN.
    pub fn defmodules(&self) -> Defmodules<'_> {
        Defmodules {
            environment: self,
            current: std::ptr::null_mut(),
        }
    }
}