Subsections


3. Classes and Objects

As previously stated in the introduction, PyCLIPS provides classes and objects to access CLIPS ``entities''. It could be preferable to refer to counterparts ``living'' in the CLIPS subsystem as entities than as objects, because it is common practice in OOP to give the name of ``objects'' to class instances: since CLIPS has its own object oriented structure (in fact there are classes in CLIPS, and therefore also instances of these), calling these structures simply objects may generate confusion.

Entities in CLIPS are generated by constructs, one for each type of entity. In Python, the common way to create something is to instance an object for a certain class. So it seemed straightforward to make a class for each of these entities, and to substitute the constructs used in CLIPS to create entities with factory functions. These functions are defined at module level, and have names of the type BuildEntity() where Entity is the type of entity that has to be created. The only exception for this are Fact objects, which are created in several ways from Templates or Assertions.

There is another way to create entities in the CLIPS subsystem, that is directly using the Build() function with a full CLIPS construct as string argument. However, this function does not return anything to the caller, so the created entity has to be sought after creation to obtain a reference.

The BuildEntity() functions and the Assert() function return objects of proper types (whose detailed list is given below) which shadow the corresponding entities in the CLIPS space.

Note: Many objects in PyCLIPS have common features3.1, such as a factory function as stated above, or methods returning their name or their so-called pretty-print form: in the following detailed documentation only the first occurrence of a feature will be described thoroughly.


3.1 Wrapper Classes

There are some simple classes that deserve a special mention in the PyCLIPS module, used to represent in Python namespace the basic types in CLIPS. These wrappers are used to differentiate values that CLIPS returns from other values that live in the Python space. However these classes are equivalent to their Python counterparts, and there is no need to pass objects converted to these classes to the module functions. Here is a list containing the class names and their equivalents in Python:

Class Type Python Equivalent
Integer ClipsIntegerType int
Float ClipsFloatType float
String ClipsStringType str
Symbol ClipsSymbolType str
InstanceName ClipsInstanceNameType str
Multifield ClipsMultifieldType list

A special object named Nil is defined, and is equivalent to Symbol('nil') in comparisons and slot assignments. It is provided to make code more readable in such situations. It has to be noticed that also Nil evaluates to False in boolean tests: this also yields for the explicit Symbol('nil') and Symbol('FALSE') definitions3.2.


3.2 Template

Templates are used to build Fact objects, that is, they provide a systematic way to construct Facts sharing a common pattern, and the only way to define Facts that have named Slots (the equivalent of record fields or structure members in other programming languages).

class Template

This represents a copy of a deftemplate construct in the CLIPS subsystem, and not a true deftemplate entity. More than one Template object in Python can refer to the same deftemplate entity in the CLIPS subsystem.

BuildFact( )
Build a Fact object using this Template without asserting it. The created Fact Slots can be modified and the Fact asserted using its Assert method.

Deletable
Read-only property to verify if this Template can be deleted from the CLIPS subsystem.

InitialFact( )
Return initial Fact in list created using this Template.

Module
Read-only property to retrieve the CLIPS name of the Module where the Template is defined.

Name
Read-only property returning the name in CLIPS of this Template. The name identifies this entity in the CLIPS subsystem, and has nothing to do with the name given to the corresponding object in Python.

Next( )
Return next3.3 Template in the list of all Templates. None is returned at the end of the list.

NextFact( fact)
Return next Fact in list created using this Template, using the supplied fact as offset.

PPForm( )
Return the pretty-print form of this Template. Pretty-print forms are often the code necessary to build a construct in CLIPS, formatted in a way that makes it quite readable. The result of the PPForm() method can be used as the argument for the Build() top level function to rebuild the construct once the Environment has been cleared3.4.

Remove( )
Remove the entity corresponding to this Template from the CLIPS subsystem. This does not remove the corresponding Python object that has instead to be deleted via the del statement or garbage collected.

Slots
Deftemplate slots information. This is itself an object, having many methods, and deserves a special explaination.
AllowedValues( name)
Return a list of allowed values for slot specified by name.
Cardinality( name)
Return cardinality for slot specified by name.
DefaultValue( name)
Return cardinality for slot specified by name.
Exists( name)
Return True if slot specified by name exists, False otherwise.
HasDefault( name)
Return one of the following values: NO_DEFAULT if the default value is set to ?NONE, STATIC_DEFAULT when the default value is static and DYNAMIC_DEFAULT when it is dynamically generated (eg. gensym).
IsMultifileld( name)
Return True if slot specified by name is a Multifield value, False otherwise.
IsSinglefield( name)
Return True if slot specified by name is a single field value, False otherwise.
Names( )
Return the list of slot names.
Range( name)
Return numerical range information for slot specified by name.
Types( name)
Return names of primitive types for slot specified by name.

Watch
Read-only property to verify if this Template is being watched.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Templates is BuildTemplate(), which has been discussed above.


3.3 Fact

Facts are one of the main entities in CLIPS, since it is whether a Fact exists or not of that drives the subsystem in the decision to fire or not certain Rules. Facts, as seen above, can be created in several ways, that is either by directly asserting sentences in string form, or by building them first from Templates and then asserting them.

class Fact

This represents a copy of a fact definition in the CLIPS subsystem, and not a true fact entity. More than one Fact objects in Python can refer to the same fact entity in the CLIPS subsystem. Many CLIPS functions return a Fact object, but most Fact objects obtained from CLIPS are read-only3.5. Read-only Facts cannot be reasserted or modified in Slots, and are provided for ``informational'' purposes only.

The argument can be a string with the same format of the Assert() function seen in the previous chapter: in this case the fact is created and asserted. Otherwise the argument can be a Template object, and in this case the resulting Fact can be modified and then asserted via the Assert() member function.

Assert( )
Assert this Fact. Only Facts that have been constructed from Templates can be Asserted using this method: read-only Facts can only be inspected with the other methods/properties.

AssignSlotDefaults( )
Assign default values to Slots of this Fact.

CleanPPForm( )
Return only the second part of this Facts pretty-print form - which can be used to build the Fact itself as described above.

Exists
Is True if this Fact has been asserted (and never retracted), False otherwise.

ImpliedSlots
The list of all implied Slots for this Fact.

Index
Read-only property returning the index in CLIPS of this Fact. As for other entities the Name is a unique identifier, as is the Index for Facts.

Next( )
Return next Fact in the list of all Facts. This list is not based on Modules, but global to the CLIPS subsystem.

PPForm( )
Return the pretty-print form of this Fact. In this case, only the second part of the returned string (the one between parentheses) can be used to build the Fact via the Assert() function3.6.

PPrint( [ignoredefaults])
Print the Fact to the standard output. When ignoredefaults is set to True (the default), slots containing the default values are omitted.

Relation
Return only the name of the relation that identifies this Fact3.7 as a Symbol.

Retract( )
Retract this Fact: in other words, remove the corresponding entity from the CLIPS subsystem. As in Remove() seen above, this does not delete the corresponding Python object. None is returned at the end of the list.

Slots
Dictionary of Fact Slots. This member behaves like a dict, but is not related to such objects. In fact, the values of slots are accessible using a dict-like syntax (square brackets), but not all the members of dict are implemented.

Please note that Facts have slightly different methods than classes representing other entities in CLIPS: an instance of Fact is created using the module-level Assert() function, and removed using the Retract() member function: this syntax, closer to the original CLIPS form, was seen as the preferred method instead of using a name such as BuildFact() for creation and a Remove() member because of the particular nature of Fact related to other types of entity.

Here is an example of usage of Fact and Template objects:

>>> import clips
>>> clips.Reset()
>>> t0 = clips.BuildTemplate("person", """
    (slot name (type STRING))
    (slot age (type INTEGER))
""", "template for a person")
>>> print t0.PPForm()
(deftemplate MAIN::person "template for a person"
   (slot name (type STRING))
   (slot age (type INTEGER)))

>>> f1 = clips.Fact(t0)
>>> f1_slotkeys = f1.Slots.keys()
>>> print f1_slotkeys
<Multifield [<Symbol 'name'>, <Symbol 'age'>]>
>>> f1.Slots['name'] = "Grace"
>>> f1.Slots['age'] = 24
>>> print f1.PPForm()
f-0     (person (name "Grace") (age 24))
>>> clips.PrintFacts()
f-0     (initial-fact)
>>> f1.Assert()
<Fact 'f-1': fact object at 0x00E0CB10>
>>> print f1.Exists()
True
>>> clips.PrintFacts()
f-0     (initial-fact)
f-1     (person (name "Grace") (age 24))
For a total of 2 facts.
>>> f1.Retract()
>>> print f1.Exists()
False
>>> clips.PrintFacts()
f-0     (initial-fact)
For a total of 1 fact.

Please note that slot names are implemented as Symbols, and the list of Slots is returned as a Multifield. Also note that the Fact f1, that has been constructed from a Template (and not yet Asserted) object and then modified using the Slots property, can be Asserted while other Facts built from construct strings cannot.


3.4 Deffacts

A Deffacts is used to modify the ``initial structure'' of a CLIPS environment, by allowing some Facts to be Asserted by default each time the Reset() function is called.

class Deffacts

This represents a copy of a deffacts construct in the CLIPS subsystem, and not a true deffacts entity. More than one Deffacts object in Python can refer to the same deffacts entity in the CLIPS subsystem.

Deletable
Read-only property to verify if this Deffacts can be deleted.

Module
Read-only property to retrieve the CLIPS name of the Module where the Deffacts is defined.

Name
Read-only property returning the name in CLIPS of this Deffacts.

Next( )
Return next Deffacts in the list of all Deffacts. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of this Deffacts.

Remove( )
Remove the entity corresponding to this Deffacts from the CLIPS subsystem.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Deffacts is BuildDeffacts(), which has been discussed above.


3.5 Rule

The construct defines rules to be activated and then fired whenever particular conditions are met. This construct is in fact the counterpart of the defrule construct in CLIPS. Normally conditions that fire Rules are Facts Asserted during a session.

class Rule

This represents a copy of a defrule construct in the CLIPS subsystem, and not a true defrule entity. More than one Rule object in Python can refer to the same defrule entity in the CLIPS subsystem.

Breakpoint
Set or remove a breakpoint from this Rule.

Deletable
Read-only property to verify if this Rule can be deleted.

Module
Read-only property to retrieve the CLIPS name of the Module where the Rule is defined.

Name
Read-only property returning the name in CLIPS of this Rule.

Next( )
Return next Rule in the list of all Rules. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of this Rule.

PrintMatches( )
Print partial matches of this Rule to standard output.

Refresh( )
Refresh this Rule.

Remove( )
Remove the entity corresponding to this Rule from the CLIPS subsystem.

WatchActivations
Set or reset debugging of activations for this Rule.

WatchFirings
Set or reset debugging of firings for this Rule.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Rules is BuildRule(), which has been discussed above.

An example - derived from the ones present in the standard CLIPS documentation - may be useful here:

>>> clips.Reset()
>>> r1 = clips.BuildRule("duck-rule", "(duck)",
                         "(assert (quack))", "The Duck rule")
>>> print r1.PPForm()
(defrule MAIN::duck-rule "The Duck rule"
   (duck)
   =>
   (assert (quack)))

>>> clips.PrintFacts()
f-0     (initial-fact)
For a total of 1 fact.
>>> clips.PrintRules()
MAIN:
duck-rule
>>> f1 = clips.Assert("(duck)")
>>> clips.PrintAgenda()
MAIN:
   0      duck-rule: f-1
For a total of 1 activation.
>>> clips.PrintFacts()
f-0     (initial-fact)
f-1     (duck)
For a total of 2 facts.
>>> clips.Run()
>>> clips.PrintFacts()
f-0     (initial-fact)
f-1     (duck)
f-2     (quack)
For a total of 3 facts.


3.6 Activation

Rule Activations are only returned by the CLIPS subsystem, and cannot be created - thus there is no factory function for these objects. CLIPS provides Activation objects to keep the program flow under control.

class Activation

This represents a copy of an activation object in the CLIPS subsystem, and not a true activation entity. More than one Activation object in Python can refer to the same activation entity in the CLIPS subsystem.

Name
Retrieve Activation name.

Next( )
Return next Activation in the list of all Activations. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of Activation.

Salience
Retrieve Activation salience3.8.

Remove( )
Remove this Activation from CLIPS.

The name of this entity in CLIPS is also returned by the string coercion function.


3.7 Global

Global objects represent global variables in CLIPS, which are normally built using the defglobal construct. To define a new Global variable the BuildGlobal() function must be used, which returns a new object.

class Global

A Global object represents a copy of a defglobal construct in the CLIPS subsystem, and not a true defglobal entity. More than one Global object in Python can refer to the same defglobal entity in the CLIPS subsystem.

Deletable
Verify if this Global can be deleted.

Module
Read-only property to retrieve the CLIPS name of the Module where the Global is defined.

Name
Retrieve Global name. The returned value is a Symbol containing the name of the global variable in the CLIPS subsystem.

Next( )
Return next Global in the list of all global variables. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of Global.

Remove( )
Remove this Global from CLIPS subsystem.

Value
Set or retrieve Global value. The returned value can be of many types, depending on the type of value contained in the corresponding CLIPS global variable.

ValueForm( )
Return a ``printed'' form of Global value. The printed form is the one that would be used in CLIPS to represent the variable itself.

Watch
Set or retrieve Global debug status.

Some examples follow to show the use of Global objects:

>>> g_x = clips.BuildGlobal("x", 15)

This is equivalent to the CLIPS declaration:

CLIPS> (defglobal ?*x* = 15)

Some of the Global methods are illustrated here:

>>> g_x
<Global 'x': defglobal object at 0x00E09960>
>>> print g_x
x
>>> g_x.Value
<Integer 15>
>>> print g_x.Value
15
>>> print g_x.ValueForm()
?*x* = 15

The name of this entity in CLIPS is also returned by the string coercion function.


3.8 Function

Objects of this type represent newly defined functions (usually via the CLIPS deffunction construct) in the CLIPS subsystem. In fact the BuildFunction() function described above, which returns a Function object, corresponds to the deffunction construct.

class Function

This represents a copy of a deffunction construct in the CLIPS subsystem, and not a true deffunction entity. More than one Function object in Python can refer to the same deffunction entity in the CLIPS subsystem.

Call( [*args])
Call this Function with the given arguments, if any. If one only argument is passed and it is a str, then it is considered a ``list of whitespace separated arguments3.9'' and follows the CLIPS syntax: in order to pass a single string it has to be explicitly cast to the String wrapper class. Conversion to wrapper classes is however recommended for all passed arguments.

Deletable
Verify if this Function can be deleted.

Module
Read-only property to retrieve the CLIPS name of the Module where the Function is defined.

Name
Retrieve Function name.

Next( )
Return next Function in the list of all CLIPS functions. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of Function.

Remove( )
Remove this Function.

Watch
Set or retrieve Function debug status.

The name of this entity in CLIPS is also returned by the string coercion function.

Note: Objects of this class are callable themselves using the syntax object([arg1 [, ... [argN]]), where the arguments follow the same rules as in the Call method.


3.9 Generic

Generics (in CLIPS called generic functions) are similar to Functions, but they add generic programming capabilities to the CLIPS system. Python programmers will find them similar to Python functions, since overloading is possible within the corresponding construct.

Each different implementation (for different argument sets) of a generic function is called a Method, and the Generic class provides several ways to inspect the various Methods. Methods are identified by an index.

class Generic

This represents a copy of a defgeneric construct in the CLIPS subsystem, and not a true defgeneric entity. More than one Generic objects in Python can refer to the same defgeneric entity in the CLIPS subsystem.

AddMethod( restrictions, actions[, midx[, comment]])
Add a Method to this Generic. The structure of this function resembles the one of the Build<entity>() functions: in fact this method of Generic actually implements the defmethod construct which is present in CLIPS. For proper documentation of this construct, see the CLIPS reference: the restrictions parameter (which represents the Method parameter restrictions) must be expressed without parentheses; the actions parameter must be expressed as in the defmethod construct, that is with all the necessary parentheses pairs. midx is the Method index when it has to be forced (optionally). The example below should be explanatory. restrictions can also be expressed as a sequence of tuples, in each of which the first element is the argument name (with its proper prefix) as a string and the following ones are the actual restrictions, either in string form or as CLIPS primitive types - which can be specified using PyCLIPS wrapper classes types, see above.

Call( [*args])
Call this Generic with the given arguments, if any. If one only argument is passed and it is a str, then it is considered a ``list of whitespace separated arguments'' and follows the CLIPS syntax: in order to pass a single string it has to be explicitly cast to the String wrapper class. Conversion to wrapper classes is however recommended for all passed arguments.

Deletable
Verify if this Generic can be deleted.

InitialMethod( )
Return the index of first Method in this Generic.

MethodDeletable( midx)
Test whether or not specified Method can be deleted from this Generic.

MethodDescription( midx)
Return the synopsis of specified Method restrictions.

MethodList( )
Return the list of Method indices for this Generic.

MethodPPForm( midx)
Return the pretty-print form of specified Method.

MethodRestrictions( midx)
Return the restrictions of specified Method in this Generic object: the midx parameter must be an Integer or int indicating the Method index.

MethodWatched( midx)
Test whether or not specified Method is being watched.

Module
Read-only property to retrieve the CLIPS name of the Module where the Generic is defined.

Name
Retrieve Generic name.

NextMethod( midx)
Return the index of next Method in this Generic given the start index as an Integer or int.

PPForm( )
Return the pretty-print form of Generic.

PrintMethods( )
Print out Method list for this Generic.

Remove( )
Remove this Generic.

RemoveMethod( midx)
Remove specified Method from this Generic.

UnwatchMethod( midx)
Deactivate watch on specified Method.

Watch
Set or retrieve Generic debug status.

WatchMethod( midx)
Activate watch on specified Method.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Generics is BuildGeneric(), which has been discussed above.

Note: Objects of this class are callable themselves using the syntax object([arg1 [, ... [argN]]), where the arguments follow the same rules as in the Call method.

An example for this class follows.

>>> import clips
>>> addf = clips.BuildGeneric("my-addf", "my generic add function")
>>> addf.AddMethod("(?a STRING)(?b STRING)", "(str-cat ?a ?b)")
>>> addf.AddMethod("(?a INTEGER)(?b INTEGER)", "(+ ?a ?b)")
>>> addf.PrintMethods()
my-addf #1  (STRING) (STRING)
my-addf #2  (INTEGER) (INTEGER)
For a total of 2 methods.
>>> print addf.MethodPPForm(1)
(defmethod MAIN::my-addf
   ((?a STRING)
    (?b STRING))
   (str-cat ?a ?b))

>>> print addf.PPForm()
(defgeneric MAIN::my-addf "my generic add function")

>>> print clips.Eval('(my-addf 5 13)')
18
>>> print clips.Eval('(my-addf "hello,"(my-addf " " "world!"))')
hello, world!
>>> print clips.Eval('(my-addf "hello" 13)')
Traceback (most recent call last):
  File "<pyshell#14>", line 1, in ?
    print clips.Eval('(my-addf "hello" 13)')
  File ".../_clips_wrap.py", line 2472, in Eval
    return _cl2py(_c.eval(expr))
ClipsError: C10: unable to evaluate expression
>>> s = clips.ErrorStream.Read()
>>> print s
[GENRCEXE1] No applicable methods for my-addf.

Please note how the error stream (ErrorStream) can be used to retrieve a more explanatory text for the error. The error stream can be very useful during interactive debugging PyCLIPS sessions to fix errors.


3.10 Class

Class objects are class definition constructs, the most important feature of the COOL3.10 sublanguage of CLIPS. As in other OOP environments, classes represent in CLIPS new data types (often resulting from aggregation of simpler data types) which have particular ways of being handled. Normally, as in Python, these particular ways are called methods3.11, while in CLIPS they are called message handlers, since to apply a method to a CLIPS object (in fact, the Instance of a Class in PyCLIPS) a message has to be sent to that object.

class Class

This represents a copy of a defclass construct in the CLIPS subsystem, and not a true defclass entity. More than one Class object in Python can refer to the same defclass entity in the CLIPS subsystem.

Abstract
Verify if this Class is abstract or not.

AddMessageHandler( name, args, text [, type, comment])
Add a new message handler to this class, with specified name, body (the text argument) and argument list: this can be specified either as a sequence of variable names or as a single string of whitespace separated variable names. Variable names (expressed as strings) can also be wildcard parameters, as specified in the Clips Reference Guide Vol. I: Basic Programming Guide. The type parameter should be one of AROUND, AFTER, BEFORE, PRIMARY defined at the module level: if omitted it will be considered as PRIMARY. The body must be enclosed in brackets, as it is in CLIPS syntax. The function returns the index of the message handler within this Class.

AllMessageHandlerList( )
Return the list of MessageHandler constructs of this Class including the ones that have been inherited from the superclass.

BuildInstance( name, [overrides])
Build an Instance of this Class with the supplied name and overriding specified slots. If no slot is specified to be overridden, then the Instance will assume default values.

BuildSubclass( name, text [, comment])
Build a subclass of this Class with specified name and body. comment is the optional comment to give to the object.

Deletable
Verify if this Class can be deleted.

Description( )
Return a summary of Class description.

InitialInstance( )
Return initial Instance of this Class. It raises an error if the Class has no subclass Instances.

InitialSubclassInstance( )
Return initial instance of this Class including its subclasses. It raises an error if the Class has no subclass Instances.

IsSubclassOf( o)
Test whether this Class is a subclass of specified Class.

IsSuperclassOf( o)
Test whether this Class is a superclass of specified Class.

MessageHandlerDeletable( index)
Return true if specified MessageHandler can be deleted.

MessageHandlerIndex( name [, htype])
Find the specified MessageHandler, given its name and type (as the parameter htype). If type is omitted, it is considered to be PRIMARY.

MessageHandlerName( index)
Return the name of specified MessageHandler.

MessageHandlerList( )
Return the list of MessageHandler constructs for this Class.

MessageHandlerPPForm( index)
Return the pretty-print form of MessageHandler.

MessageHandlerType( index)
Return the type of the MessageHandler specified by the provided index.

MessageHandlerWatched( index)
Return watch status of specified MessageHandler.

Module
Read-only property to retrieve the CLIPS name of the Module where the Class is defined.

Name
Retrieve Class name.

Next( )
Return next Class in the list of all CLIPS classes. None is returned at the end of the list.

NextInstance( instance)
Return next Instance of this Class. Returns None if there are no Instances left.

NextMessageHandlerIndex( index)
Return index of next MessageHandler with respect to the specified one.

NextSubclassInstance( instance)
Return next instance of this Class, including subclasses. Returns None if there are no Instances left.

PPForm( )
Return the pretty-print form of Class.

PreviewSend( msgname)
Print list of MessageHandlers suitable for specified message.

PrintAllMessageHandlers( )
Print the list of all MessageHandlers for this Class including the ones that have been inherited from the superclass.

PrintMessageHandlers( )
Print the list of MessageHandlers for this Class.

RawInstance( name)
Create an empty Instance of this Class with specified name.

Reactive
Verify if this Class is reactive or not.

Remove( )
Remove this Class.

RemoveMessageHandler( index)
Remove MessageHandler specified by the provided index.

Slots
Class slots information. This is itself an object, having many methods, and deserves a special explaination.
AllowedClasses( name)
Return a list of allowed class names for slot specified by name.
AllowedValues( name)
Return a list of allowed values for slot specified by name.
Cardinality( name)
Return cardinality for slot specified by name.
DefaultValue( name)
Return the default value for slot specified by name.
Exists( name)
Return True if slot specified by name exists, False otherwise.
ExistsDefined( name)
Return True if slot specified by name is defined in this Class, False otherwise.
Facets( name)
Return facet names for slot specified by name.
HasDirectAccess( name)
Return True if slot specified by name is directly accessible, False otherwise.
IsInitable( name)
Return True if slot specified by name is initializable, False otherwise.
IsPublic( name)
Return True if slot specified by name is public, False otherwise.
IsWritable( name)
Return True if slot specified by name is writable, False otherwise.
Names( )
Return the list of slot names.
NamesDefined( )
Return the list of slot names explicitly defined in this Class.
Range( name)
Return numerical range information for slot specified by name.
Sources( name)
Return source class names for slot specified by name.
Types( name)
Return names of primitive types for slot specified by name.

Subclasses( )
Return the names of subclasses of this Class.

Superclasses( )
Return the names of superclasses of this Class.

UnwatchMessageHandler( index)
Turn off debug for specified MessageHandler.

WatchInstances
Set or retrieve debug status for this Class Instances.

WatchMessageHandler( index)
Turn on debug for specified MessageHandler.

WatchSlots
Set or retrieve Slot debug status.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Classes is BuildClass(), which has been discussed above.


3.11 Instance

Instance objects represent class instances (that is, objects in the OOP paradigm) that live in the CLIPS subsystem. Messages can be sent to those objects and values can be set and retrieved for the slots defined in the related class, where the meaning of slot has been described in the section above.

class Instance

This represents a copy of an instance object in the CLIPS subsystem, and not a true instance entity. More than one Instance object in Python can refer to the same instance entity in the CLIPS subsystem.

Class
Retrieve the Class of this Instance: this property actually refers to a Class object, so all of its methods are available.

DirectRemove( )
Directly remove this Instance, without sending a message.

GetSlot( slotname)
Retrieve the value of Slot specified as argument. The synonym SlotValue is retained for readability and compatibility. Please notice that these functions are provided in order to be more coherent with the behaviour of CLIPS API, as CLIPS C interface users know that a function like GetSlot usually bypasses message passing, thus accessing slots directly. The possibilities offered by GetSlot are also accessible using the Slots property described below.

IsValid( )
Determine if this Instance is still valid.

Name
Retrieve the Instance name.

Next( )
Return next Instance in the list of all CLIPS instances. It returns None if there are no Instances left.

PPForm( )
Return the pretty-print form of Instance.

PutSlot( slotname, value)
Set the value of specified slot. The value parameter should contain a value of the correct type, if necessary cast to one of the wrapper classes described above if the type could be ambiguous. The synonym SetSlotValue is provided for readability and compatibility. What has been said about GetSlot also yields for the hereby described function, as the possibilities offered by PutSlot are also accessible using the Slots property described below.

Remove( )
Remove this Instance (passing a message).

Send( msg [, args])
Send the provided message with the given arguments to Instance. The args parameter (that is, message arguments), should be a string containing a list of arguments separated by whitespace, a tuple containing the desired arguments or a value of a basic type. Also in the second case the tuple elements have to be of basic types. The function returns a value depending on the passed message.

Slots
Dictionary of Instance slots. This member behaves like a dict, but is not related to such objects. In fact, the values of slots are accessible using a dict-like syntax (square brackets), but not all the members of dict are implemented. The functionality of PutSlot and GetSlot is superseded by this property.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Instances is BuildInstance(), which has been discussed above.

Here is an example of usage of Instance and Class objects:

>>> import clips
>>> clips.Build("""(defclass TEST1
    (is-a USER)
    (slot ts1 (type INSTANCE-NAME))
    (multislot ts2))""")
>>> c = clips.FindClass("TEST1")
>>> print c.PPForm()
(defclass MAIN::TEST1
   (is-a USER)
   (slot ts1
      (type INSTANCE-NAME))
   (multislot ts2))

>>> clips.Reset()
>>> i = clips.BuildInstance("test1", c)
>>> i.Slots['ts2'] = clips.Multifield(['hi', 'there'])
>>> i.Slots['ts1'] = i.Name
>>> print i.PPForm()
[test1] of TEST1 (ts1 [test1]) (ts2 "hi" "there")


3.12 Definstances

As there are deffacts for fact objects, instances are supported in CLIPS by the definstances construct: it allows certain default Instances to be created each time a Reset() is issued. In PyCLIPS this construct is provided via the Definstances class.

class Definstances

This represents a copy of the definstances construct in the CLIPS subsystem, and not a true definstances entity. More than one Definstances object in Python can refer to the same definstances entity in the CLIPS subsystem.

Deletable
Verify if this Definstances can be deleted.

Module
Read-only property to retrieve the CLIPS name of the Module where the Definstances is defined.

Name
Retrieve Definstances name.

Next( )
Return next Definstances in the list of all CLIPS definstances. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of this Definstances object.

Remove( )
Delete this Definstances object from CLIPS subsystem.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Definstances is BuildDefinstances(), which has been discussed above.


3.13 Module

Modules are a way, in CLIPS, to organize constructs, facts and objects. There is a big difference between modules and environments3.12: one should think of a Module as a group of definitions and objects, which can interoperate with entities that are defined in other Modules. The Module class provides methods, similar to the ones defined at top level, to directly create entities as part of the Module itself, as well as methods to examine Module contents. Also, Module objects have methods that instruct the related CLIPS module to become current, so that certain operations can be performed without specifying the module to which they have to be applied.

class Module

This represents a copy of a defmodule construct in the CLIPS subsystem, and not a true defmodule entity. More than one Module object in Python can refer to the same defmodule entity in the CLIPS subsystem.

Name
Return the name of this Module.

Next( )
Return next Module in the list of all CLIPS modules. None is returned at the end of the list.

PPForm( )
Return the pretty-print form of this Module.

SetCurrent( )
Make the module that this object refers the current Module.

SetFocus( )
Set focus to this Module.

For the following methods:

TemplateList(), FactList(), DeffactsList(), ClassList(), DefinstancesList(),
GenericList(), FunctionList(), GlobalList(), BuildTemplate(),
BuildDeffacts(), BuildClass(), BuildDefinstances(), BuildGeneric(),
BuildFunction(), BuildGlobal(), BuildRule(), BuildInstance(),
PrintTemplates(), PrintDeffacts(), PrintRules(), PrintClasses(),
PrintInstances(), PrintSubclassInstances(), PrintDefinstances(),
PrintGenerics(), PrintFunctions(), PrintGlobals(), ShowGlobals(),
PrintAgenda(), PrintBreakpoints(), ReorderAgenda(), RefreshAgenda()

please refer to the corresponding function defined at module level, keeping in mind that these methods perform the same task but within the Module where they are executed.

The name of this entity in CLIPS is also returned by the string coercion function. The factory function for Modules is BuildModule(), which has been discussed above.


3.14 Environment

This class represents an environment, and implements almost all the module level functions and classes. The only objects appearing at PyCLIPS level and not at Environment level are the CLIPS I/O subsystem streams, which are shared with the rest of the CLIPS engine.

Environment objects are not a feature of CLIPS sessions (as stated above), thus there is no way to identify them in CLIPS using a symbol. So Environment objects do not have a Name property. Instead, CLIPS provides a way to identify an environment through an integer called index.

class Environment

Please refer to top level functions, variables and classes for information on contents of Environment objects. The extra methods and properties follow below.

Index
Retrieve the index identifying this Environment internally in CLIPS.

SetCurrent( )
Make the environment that this object refers the current Environment.

Further explanations about Environment objects can be found in the appendices.


3.15 Status and Configuration Objects

As seen in the introduction, there are a couple of objects that can be accessed to configure the underlying CLIPS engine and to retrieve its status. These are the EngineConfig and DebugConfig objects. The reason why configuration and status functions have been grouped in these objects is only cosmetic: in fact there is no counterpart of EngineConfig and DebugConfig in CLIPS. It was seen as convenient to group configuration and debug functions in two main objects and to make them accessible mainly as properties in Python, instead of populating the module namespace with too many get/set functions.

There is also an object, called Memory, which gives information about memory utilization and allow the user to attempt to free memory used by the CLIPS engine and no longer needed.

A description of what the above objects (which can not be instanced by the user of PyCLIPS3.13) actually expose follows.


3.15.1 Engine Configuration

The EngineConfig object allows the configuration of some features of the underlying CLIPS engine. Here are the properies provided by EngineConfig:

AutoFloatDividend
Reflects the behaviour of CLIPS get/set-auto-float-dividend. When True the dividend is always considered to be a floating point number within divisions.

ClassDefaultsMode
Reflects the behaviour of CLIPS get/set-class-defaults-mode. Possible values of this flag are CONVENIENCE_MODE and CONSERVATION_MODE. See Clips Reference Guide Vol. II: Advanced Programming Guide for details.

DynamicConstraintChecking
Reflects the behaviour of CLIPS get/set-dynamic-constraint-checking. When True, function calls and constructs are checked against constraint violations.

FactDuplication
Reflects the behaviour of CLIPS get/set-fact-duplication. When True, facts can be reasserted when they have already been asserted3.14.

IncrementalReset
Reflects the behaviour of CLIPS get/set-incremental-reset. When True newly defined rules are updated according to current facts, otherwise new rules will only be updated by facts defined after their construction.

ResetGlobals
Reflects the behaviour of CLIPS get/set-reset-globals. When True the Global variables are reset to their initial value after a call to Reset().

SalienceEvaluation
Reflects the behaviour of CLIPS get/set-salience-evaluation. Can be one of WHEN_DEFINED, WHEN_ACTIVATED, EVERY_CYCLE. See the previous chapter and Clips Reference Guide Vol. II: Advanced Programming Guide for more information.

SequenceOperatorRecognition
Reflects the behaviour of CLIPS get/set-sequence-operator-recognition. When False, Multifield values in function calls are treated as a single argument.

StaticConstraintChecking
Reflects the behaviour of CLIPS get/set-static-constraint-checking. When True, slot values are checked against constraint violations.

Strategy
Reflects get/set-strategy behaviour. Can be any of the following values: RANDOM_STRATEGY, LEX_STRATEGY, MEA_STRATEGY, COMPLEXITY_STRATEGY, SIMPLICITY_STRATEGY, BREADTH_STRATEGY or DEPTH_STRATEGY. See the previous chapter and Clips Reference Guide Vol. II: Advanced Programming Guide for more information.


3.15.2 Debug Settings

The DebugConfig object provides access to the debugging and trace features of CLIPS. During a CLIPS interactive session debug and trace messages are printed on the system console (which maps the wtrace I/O router). Users of the trace systems will have to poll the TraceStream to read the generated messages.

In CLIPS, the process of enabling trace features on some class of entities is called to watch such a class; this naming convention is reflected in PyCLIPS. Note that specific objects can be watched: many classes have their own Watch property to enable or disable debugging on a particular object.

Also, CLIPS provides a facility to log all debug information to physical files: this is called to dribble on a file. Dribbling is possible from DebugConfig via the appropriate methods.

The names of methods and properties provided by this object are quite similar to the corresponding commands in CLIPS, so more information about debugging features can be found in Clips Reference Guide Vol. I: Basic Programming Guide.

ActivationsWatched
Flag to enable or disable trace of Rule activations and deactivations.

CompilationsWatched
Flag to enable or disable trace of construct definition progress.

DribbleActive( )
Tell whether or not dribble is active.

DribbleOff( )
Turn off dribble and close the dribble file.

DribbleOn( fn)
Enable dribble on the file identified by provided filename fn.

ExternalTraceback
Flag to enable or disable printing traceback messages to Python sys.stderr if an error occurs when the CLIPS engine calls a Python function. Please note that the error is not propagated to the Python interpreter. See the appendices for a more detailed explaination.

FactsWatched
Flag to enable or disable trace of Fact assertions and retractions.

FunctionsWatched
Flag to enable or disable trace of start and finish of Functions.

GenericFunctionsWatched
Flag to enable or disable trace of start and finish of Generic functions.

GlobalsWatched
Flag to enable or disable trace of assignments to Global variables.

MethodsWatched
Flag to enable or disable trace of start and finish of Methods within Generic functions.

MessageHandlersWatched
Flag to enable or disable trace of start and finish of MessageHandlers.

MessagesWatched
Flag to enable or disable trace of start and finish of messages.

RulesWatched
Flag to enable or disable trace of Rule firings.

SlotsWatched
Flag to enable or disable trace of changes to Instance Slots.

StatisticsWatched
Flag to enable or disable reports about timings, number of facts and instances, and other information after Run() has been performed.

UnwatchAll( )
Turn off watch for all items above.

WatchAll( )
Watch all items above.

Note: Other CLIPS I/O streams besides TraceStream can be involved in the trace process: please refer to the CLIPS guides for details.


3.15.3 Memory Operations

This object provides access to the memory management utilities of the underlying CLIPS engine. As said above, it allows the reporting of memory usage and the attempt to free memory that is used not for computational purposes. Also, a property of this object affects the engine behaviour about whether or not to cache some information. Here is what the object exposes:

Conserve
When set to True, the engine does not cache pretty-print forms to memory, thus being more conservative.

EnvironmentErrorsEnabled
When set to True, the engine is enabled to directly write fatal environment errors to the console (stderr). This kind of messages is in most of the cases printed when the program exits, so it can be annoying. The behaviour is disabled by default.

Free( )
Attempt to free as much memory as possible of the one used by the underlying CLIPS engine for previous computations.

PPBufferSize
Report the size (in bytes) of the buffers used by PyCLIPS to return pretty-print forms or similar values. By default this is set to 8192, but the user can modify it using values greater than or equal to 256. Greater values than the default can be useful when such forms are used to reconstruct CLIPS entities and definitions are so complex that the default buffer size is insufficient.

Requests
Read-only property reporting the number of memory request made by the engine to the operating system since PyCLIPS has been initialized.

Used
Read-only property reporting the amount, in kilobytes, of memory used by the underlying CLIPS engine.

NumberOfEnvironments
Read-only property reporting the number of currently allocated Environments.


3.16 I/O Streams

In order to be more embeddable, CLIPS defines a clear way to redirect its messages to locations where they can be easily retrieved. CLIPS users can access these locations for reading or writing by specifying them as logical names (namely stdin, stdout, wtrace, werror, wwarning, wdialog, wdisplay, wprompt)3.15. PyCLIPS creates some special unique objects3.16, called I/O streams throughout this document, to allow the user to read messages provided by the underlying engine. Most of these objects have only one method, called Read(), that consumes CLIPS output and returns it as a string: this string contains all output since a previous call or module initialization. The only exception is StdinStream whose single method is Write() and it accepts a string3.17 as parameter. As CLIPS writes line-by-line, the string resulting from a call to Read() can contain newline characters, often indicating subsequent messages.

Here is a list of the I/O streams provided by PyCLIPS, along with a brief description of each.

Stream Description
StdoutStream where information is usually printed out (eg. via (printout t ...))
TraceStream where trace information (see watch) goes
ErrorStream where CLIPS error messages are written in readable form
WarningStream where CLIPS warning messages are written in readable form
DialogStream where CLIPS informational messages are written in readable form
DisplayStream where CLIPS displays information (eg. the output of the (facts) command)
PromptStream where the CLIPS prompt (normally CLIPS>) is sent
StdinStream where information is usually read by CLIPS (eg. via (readline))

Some of the provided I/O streams are actually not so relevant for PyCLIPS programmers: for instance, it is of little use to read the contents of PromptStream and DisplayStream. In the latter case, in fact, there are other inspection functions that provide the same information in a more structured way than text. However they are available to provide a closer representation of the programming interface and allow CLIPS programmers to verify if the output of CLIPS-oriented calls (see the paragraph about Build() and Eval() in the appendices) really do what they are expected to.


3.17 Predefined Classes

PyCLIPS defines3.18, some Class objects, that is the ones that are present in CLIPS itself by default. They are defined in order to provide a compact access to CLIPS ``stock'' classes: most of these objects are of little or no use generally (although they can be handy when testing for class specification or generalization), but at least one (USER_CLASS) can be used to make code more readable.

Namely, these Classes are:

Python Name CLIPS defclass
FLOAT_CLASS FLOAT
INTEGER_CLASS INTEGER
SYMBOL_CLASS SYMBOL
STRING_CLASS STRING
MULTIFIELD_CLASS MULTIFIELD
EXTERNAL_ADDRESS_CLASS EXTERNAL-ADDRESS
FACT_ADDRESS_CLASS FACT-ADDRESS
INSTANCE_ADDRESS_CLASS INSTANCE-ADDRESS
INSTANCE_NAME_CLASS INSTANCE-NAME
OBJECT_CLASS OBJECT
PRIMITIVE_CLASS PRIMITIVE
NUMBER_CLASS NUMBER
LEXEME_CLASS LEXEME
ADDRESS_CLASS ADDRESS
INSTANCE_CLASS INSTANCE
INITIAL_OBJECT_CLASS INITIAL-OBJECT
USER_CLASS USER

The following code, shows how to use the ``traditional'' BuildClass() factory function and how to directly subclass one of the predefined Class object. In the latter case, probably, the action of subclassing is expressed in a more clear way:

>>> import clips
>>> C = clips.BuildClass("C", "(is-a USER)(slot s)")
>>> print C.PPForm()
(defclass MAIN::C
   (is-a USER)
   (slot s))

>>> D = clips.USER_CLASS.BuildSubclass("D", "(slot s)")
>>> print D.PPForm()
(defclass MAIN::D
   (is-a USER)
   (slot s))

Although it actually does not save typing (the statement is slightly longer), the second form can be used to produce more readable Python code.

Note: These objects are actually useful only when the package is fully imported, that is using the import clips form: importing the symbols at global level (in the form from clips import *) does in fact create some namespace problems. Since in the latter case the names that represent stock classes are only references to the ones defined at module level, PyCLIPS cannot change them when the actual classes are relocated in the CLIPS memory space, for instance when Clear is called.



Footnotes

... features3.1
The current PyCLIPS implementation still does not make use of inheritance, although it's likely that a future release will do.
... definitions3.2
In this Symbol is different from str as only the empty string evaluates to false in Python. However, it seemed closer to the assumption that symbols in CLIPS are not to be considered as ``literals'' (they are more similar to implicitly defined variables) to implement such behaviour, that can be reverted with an explicit conversion to str.
... next3.3
CLIPS stores its objects (or entities) in ordered lists, so it makes sense to ``iterate'' over these lists. However this implementation of PyCLIPS does not implement iterators (as known in Python) on these classes: a way to do this is currently under examination.
... cleared3.4
Actually pretty-print forms use fixed size buffers to build the representing string: when such a form is too complex, the default buffer size of 8192 bytes can be insufficient. In this case the PPBufferSize property of the Memory object can be used to allow the creation of properly sized buffers.
...read-only3.5
Actually, the main rule is that if a Fact has been Asserted then it is read-only. Note that all shadow representations of CLIPS asserted fact entities are read-only.
... function3.6
This is also not always true: as said before, there is no way to Assert Facts that have named slots using a string if there is not a deftemplate for this kind of Fact. However, once a Template with the specified slots has been created, this becomes possible.
...Fact3.7
The authors of CLIPS call a relation the first field of the Fact itself, although it is not needed to actually represent a real relationship.
...salience3.8
Salience is a value that represents the priority of a rule in CLIPS.
... arguments3.9
See the syntax for the toplevel function with the same name.
...COOL3.10
Acronym for CLIPS Object-Oriented Language.
...methods3.11
Note that the term Method has been used for function overloading in the definition of Generic functions.
...environments3.12
Besides the discussion above, also notice that in a ``pure'' CLIPS session there is no concept of environment at all: the use of environment is reserved to those who embed CLIPS in another program, such as PyCLIPS users.
...3.13
Besides removal of class definitions, a singleton-styled implementation mechanism prevents the user from creating further instances of the objects.
... asserted3.14
This does not change the behaviour of the Fact class, which prohibits reassertion anyway. However, facts that would be asserted through firing of rules and would generate duplications will not raise an error when this behaviour is set.
...wprompt)3.15
CLIPS also defines t as a logical name: as stated in Clips Reference Guide Vol. II: Advanced Programming Guide this indicates stdin in functions that read text and stdout in function that print out. In PyCLIPS, for all functions that print out to t the user must read from StdoutStream.
... objects3.16
PyCLIPS in fact defines one more I/O stream, called temporary, which is used internally to retrieve output from CLIPS that shouldn't go anywhere else. PyCLIPS users however are not supposed to interact with this object.
... string3.17
The current implementation converts the argument to a string, so other types can be accepted.
... defines3.18
At the module level only: defining these objects at the environment level could cause aliasing current CLIPS enviroment. On the other hand, if these objects were implemented in a way that checked for aliasing, access to the actual entities would be surely slower only favouring compactness of user code.