B. The clips._clips Submodule

It has been said throughout the whole document that there are two different ``natures'' of PyCLIPS, called the high level module and the low level module. The former has been described in detail here, and is supposed to be the main interface to CLIPS. However, since all communication between Python and the CLIPS subsystem is implemented in the low level part, some users might find it useful to access this interface instead of the higher level one. It is not the intention of this manual to provide documentation for the low level clips._clips interface, but only to give some indications to users who already have experience of the CLIPS C interface.

Submodule clips._clips provides low-level classes that have the same names as their counterparts in CLIPS, such as fact, deftemplate and so on. Also, clips._clips defines an environment class to refer to environment addresses.

Almost all functions described in Clips Reference Guide Vol. II: Advanced Programming Guide are ported to Python, except for missing features described below: the name is the same as in the reference guide, except for the first letter that is not capitalizedB.1. CLIPS ``top level'' functions have been ported to clips._clips as well as companion functions that accept an environment instance as the first argumentB.2, whose name begins with env_ followed by the same name as the corresponding top level function.

Low level functions are documented by themselves through documentation strings, that describe purpose, arguments and return values. For instance, let's show the documentation of a function:

>>> import clips
>>> cl = clips._clips
>>> print cl.listDeftemplates.__doc__
listDeftemplates(logicalname [, module])
list deftemplates to output identified by logicalname
arguments:
  logicalname (str) - the logical name of output
  module (module) - the module to inspect, all modules if omitted

Most low level function documentation strings, i.e. the ones given for functions that are not trivially identifiable with the CLIPS API counterpartsB.3, have this form and describe in detail arguments and return values. Users who want to benefit of these functions, can display documentation strings as a reference.

The underlying engine is the same, there is no separation of environment between the two interfaces. Operations performed at lower level are obviously reflected in the higher level layer, as in the following example:

>>> clips.Clear()
>>> cl.facts("stdout")
>>> s = clips.StdoutStream.Read()
>>> print s
None
>>> print cl.assertString.__doc__
assertString(expr) -> fact
assert a fact into the system fact list
returns: a pointer to the asserted fact
arguments:
  expr (str) - string containing a list of primitive datatypes
>>> f = cl.assertString("(duck)")
>>> clips.PrintFacts()
f-0     (duck)
For a total of 1 fact.

so the two interfaces can be used interchangeably.



Footnotes

... capitalizedB.1
There can be some exceptions: the most important one is the assertion function, since Python already has an assert keyword. This function is called assertFact instead.
... argumentB.2
When trying to show the documentation string of these functions, the first argument is not described because their code has been generated automatically.
... counterpartsB.3
Some functions have a documentation string that actually refers to the CLIPS API itself, explicitly containing the words ``equivalent of C API'' and the C function name: Clips Reference Guide Vol. II: Advanced Programming Guide is especially useful in this case.