For most people, interaction with Soar begins with using the standard interface and a simple environment such as those which come along with the tutorial. Soar can be instructed to load productions, run, add-wme and such all via easy interaction with the user at some prompt. For some people, this is their only requirement for Soar: to execute some productions within a (relatively) simple environment which can easily be integrated with Soar's current interface.
Obviously, this is a limitation that we would like to avoid. In an ideal world, people who were framiliar with interacting with Soar through its stardard interface would also be use Soar with a multitude of different environments, regardless of their implementation language. Unfortunately, in the past this meant looking deep inside of the Soar source code, and picking out (with relatively little guidence) the key set of functions which would allow an appropriate interaction to take place.
The primary goal of the Soar API is to provide a C based interface which has a high degree of correspondence with the standard Soar interface (Tcl) that users begin their interaction to Soar with. The anticipated result of this is that it will be easier to interface other applications with Soar becuase the requred C function calls will be more intuitive. Moreover, it is likely that this will also help everyone because documentation at all levels of interaction (from the C based API to the high level interface in Tcl) will be relatively similar.
The secondary goal of the Soar API is to remove all interface dependencies from the Soar kernel. In the past, when a new interface was used the kernel was modified (often only slightly) to provide some degree of support for the particularities of the interface. The new paradigm is to enforce a strict distinction between interface and kernel. As a result the kernel is implemented in ansi C. Interface specific functionality should be handled via callbacks from the Soar kernel. Examples of this can be seen in both the new-unix-interface and the tcl-interface. By maintaining a strict distinction between kernel and interface, it should be easier for users to embed soar in ther application or build a new interface for it, without understaning all the details of the kernel itself.
Now that you are convinced that the API represents forward progress for the Soar community :), I will give a brief overview of the components that make up the API, and how they are organized.
The Soar API exists at two distinct levels of abstraction. The job of the highest layer is to provide abstract functions which can easily be called from the end user interface (e.g. something the user types into). Each of its functions provide a method for parsing command arguments so that this tedium need not be done by the developers of end user interfaces. Moreover, all of the functions in this layer have the similar arguments and return values, so that a function pointer can be used to invoke any of them.
The currently implemented version of the Soar API (soarapi.h) requires only that the end user interface parse commands into argc, argv style arguments (in a manner similar to what is done in the Tcl shell). The Soar API then does context dependent parsing and calls lower level functions in the Soar core (or extended core) API.
Low Level: Soar Core API and Extended Soar Core API
Together, the Core API and the Extended Core API comprise the functionality of the low level Soar API. These functions (described in soar_core_api.h and soar_ecore_api.h) provide common ancestors for the more abstract functions in the high level api (soarapi.h). The difference between this level and the higher level is that these functions use typed arguments, so that minimal string parsing is required, and more static type checking can be done. Interaction with Soar at this level of abstraction is most appropriate when Soar is embedded within another application, and is not controlled by a user typing specific commands.
The distinction between Core and Extended Core functions is less important than the distinction between the high and low level API. However, the Core API (soar_core_api.h), provides all the minimum functionality that would be required for an embeddable system. Using it alone, allows a (much?) smaller footprint than would be possible otherwise because functionality such as printing and parsing are minimized (in the future it is likely that they will be removed altogether). The Extended Core API (soar_ecore_api.h), completes the functionality provided in the higher level Soar API, but requires more code to be included in the end applciation. Moreover, many of its functions make the assumption that there is some mechanism to display output to the user in a pseudo-interactive manner.
The following questions may be useful in helping you determine which api functions you should be examining:
1.2.6 written by Dimitri van Heesch,
© 1997-2001