Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals

soarapi.h File Reference

The High Level Interface to Soar. More...

Go to the source code of this file.

Interaction With Soar

This section deals with four main areas of interaction
  • (Re)Initializing Soar
  • Creating Agents
  • Destroying Agents
  • Starting and Stopping Agents


int soar_ReInitSoar (int argc, const char *argv[], soarResult *res)
 soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent.

int soar_CreateAgent (int argc, const char *argv[], soarResult *res)
 soar_CreateAgent -- This command creates a new agent.

int soar_Run (int argc, const char *argv[], soarResult *res)
 soar_Run -- This is the command procedure for the "run" command which runs the Soar agent.

int soar_DestroyAgent (int argc, const char *argv[], soarResult *res)
 soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent.

int soar_Quit (int argc, const char *argv[], soarResult *res)
 soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited.


Modifying Agent Memory

This section deals with two areas of the agent:
  • Production Memory
  • Working Memory


int soar_ReteNet (int argc, const char *argv[], soarResult *res)
 soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network.

int soar_AddWme (int argc, const char *argv[], soarResult *res)
 soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory.

int soar_RemoveWme (int argc, const char *argv[], soarResult *res)
 soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory.

int soar_Excise (int argc, const char *argv[], soarResult *res)
 soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory.


Modifying the Agents Parameters

int soar_CaptureInput (int argc, const char *argv[], soarResult *res)
 soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase.

int soar_ReplayInput (int argc, const char *argv[], soarResult *res)
 soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input.

int soar_ChunkNameFormat (int argc, const char *argv[], soarResult *res)
 soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks.

int soar_Learn (int argc, const char *argv[], soarResult *res)
 soar_Learn -- This is the command procedure for the "learn" command.

int soar_MaxElaborations (int argc, const char *argv[], soarResult *res)
 soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed.

int soar_MaxChunks (int argc, const char *argv[], soarResult *res)
 soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed.

int soar_Operand2 (int argc, const char *argv[], soarResult *res)
 soar_Operand2 -- This is the command procedure for the "soar8" command.

int soar_WaitSNC (int argc, const char *argv[], soarResult *res)
 soar_WaitSNC -- This is the command procedure for the "waitsnc" command.

int soar_InputPeriod (int argc, const char *argv[], soarResult *res)
 soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period.

int soar_MultiAttributes (int argc, const char *argv[], soarResult *res)
 soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values.

int soar_NumericIndifferentMode (int argc, const char *argv[], soarResult *res)
 soar_NumericIndifferentMode -- This is the command procedure for the "numeric-indifferent-mode" , command which controls the way o-support calculations are done (for the current agent).

int soar_OSupportMode (int argc, const char *argv[], soarResult *res)
 soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent).

int soar_ExplainBacktraces (int argc, const char *argv[], soarResult *res)
 soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command.

int soar_FiringCounts (int argc, const char *argv[], soarResult *res)
 soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired.

int soar_FormatWatch (int argc, const char *argv[], soarResult *res)
 soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack.

int soar_IndifferentSelection (int argc, const char *argv[], soarResult *res)
 soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration.

int soar_InternalSymbols (int argc, const char *argv[], soarResult *res)
 soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table.

int soar_Matches (int argc, const char *argv[], soarResult *res)
 soar_Matches -- This is the command procedure for the "matches" command.

int soar_Memories (int argc, const char *argv[], soarResult *res)
 soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use.

int soar_ProductionFind (int argc, const char *argv[], soarResult *res)
 soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic.

int soar_Preferences (int argc, const char *argv[], soarResult *res)
 soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot.

int soar_Print (int argc, const char *argv[], soarResult *res)
 soar_Print -- This is the command procedure for the "print" command, which prints various Soar items.

int soar_PWatch (int argc, const char *argv[], soarResult *res)
 soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing.

int soar_Pool (int argc, const char *argv[], soarResult *res)
 soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools

int soar_Sp (int argc, const char *argv[], soarResult *res)
 soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production.

int soar_Stats (int argc, const char *argv[], soarResult *res)
 soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information.

int soar_Stop (int argc, const char *argv[], soarResult *res)
 soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents.

int soar_Verbose (int argc, const char *argv[], soarResult *res)
 soar_Verbose -- This is the command procedure for the "verbose" command

int soar_Warnings (int argc, const char *argv[], soarResult *res)
 soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages.

int soar_Log (int argc, const char *argv[], soarResult *res)
 soar_Log -- This is the command procedure for the "log" command which records session information to a log file.

int soar_AttributePreferencesMode (int argc, const char *argv[], soarResult *res)
 soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled.

int soar_Watch (int argc, const char *argv[], soarResult *res)
 soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing.

int soar_DefaultWmeDepth (int argc, const char *argv[], soarResult *res)
 soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth.

int soar_BuildInfo (int argc, const char *argv[], soarResult *res)
 soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar.

int soar_ExcludedBuildInfo (int argc, const char *argv[], soarResult *res)
 soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar.

int soar_Interrupt (int argc, const char *argv[], soarResult *res)

Detailed Description

The High Level Interface to Soar.

Copyright 1995-2003 Carnegie Mellon University, University of Michigan, University of Southern California/Information Sciences Institute. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE SOAR CONSORTIUM ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE SOAR CONSORTIUM OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Carnegie Mellon University, the University of Michigan, the University of Southern California/Information Sciences Institute, or the Soar consortium. =======================================================================

Id
soarapi.h,v 1.8 2003/11/24 18:34:11 rmarinie Exp

Definition in file soarapi.h.

Function Documentation

int soar_AddWme (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_AddWme -- This is the command procedure for the "add-wme" command, which adds an element to working memory.

This command surgically modifies Soar's working memory. Add-wme adds a new wme with the given id, attribute, value, and optional acceptable preference. The given id must be an existing identifier. If '*' is given in place of the attribute or value, Soar creates a new identifier (gensym) for that field.

WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.

See also:
soar_RemoveWme
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           add-wme id [^] { attribute | '*'} { value | '*' } [+]
Returns:
Returns a standard SOAR completion code
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains information about the new wme in the following format: "<timetag>: <state> ^<attribute> <value>"
Side effects:
Adds the given wme to working memory.

Definition at line 301 of file soarapi.c.

References appendSoarResultResult(), appendSymbolsToSoarResultResult(), psoar_wme, setSoarResultResult(), soar_cAddWme(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and wme.

int soar_AttributePreferencesMode (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_AttributePreferencesMode -- This is the command procedure for the "attribute-preferences-mode" command, which controls how (certain) preferences are handled.

This command affects the handling of preferences (other than acceptable and reject preferences) for non-context slots. It takes a single numeric argument:

  • 0 - Handle them the normal (Soar 6) way.
  • 1 - Handle them the normal (Soar 6) way, but print a warning message whenever a preference other than + or - is created for a non-context slot.
  • 2 - Whenever a preferences other than + or - is created for a non-context slot, print an error message and ignore (discard) that preference. For non-context slots, the set of values installed in working memory is always equal to the set of acceptable values minus the set of rejected values.
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           attribute-preferences-mode {0 | 1 | 2}
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the current attribute preferences mode.
Side effects:
Sets current_agent(attribute_preferences_mode).

Definition at line 2442 of file soarapi.c.

References getInt(), setSoarResultResult(), soar_cAttributePreferencesMode(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_BuildInfo (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_BuildInfo -- This is the command procedure for the "build-info" command, which yields information about Soar.

This function indicates compile time setting which affect the current instantiation of Soar. For example, the DETAILED_TIMERS options must be set at compile time. This function prints such compile time options that were defined for the particular build.

Note that the options which are printed using this function are filtered. They are expected to be the most pertanant of all the compile time options.

See also:
soar_ExcludedBuildInfo
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           build-info
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.

Definition at line 2905 of file soarapi.c.

References setSoarResultResult(), soar_ecBuildInfo(), SOAR_OK, soar_version_string, and soarResult.

int soar_CaptureInput (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_CaptureInput -- This is the command procedure for the "capture-input" command which records input wme commands (add|remove) from the INPUT phase.

This command may be used to start and stop the recording of input wmes as created by an external simulation. wmes are recorded decision cycle by decision cycle. Use the command replay-input to replay the sequence.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           capture-input <action>
            <action> ::= -open pathname 
            <action> ::= -query
            <action> ::= -close
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the status of the capture file
Side effects:
Opens and/or closes captured input files.

Definition at line 478 of file soarapi.c.

References appendSoarResultResult(), print(), setSoarResultResult(), soar_ecCaptureInput(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_ChunkNameFormat (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ChunkNameFormat -- This command specifies the format of names of newly created chunks.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           chunk-name-format  [-short|-long]
                              [-prefix [<prefix>]]
                              [-count [<start-chunk-number>]]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets indicated format style, prefix, and starting chunk number. Prints current if -prefix is used without a . Prints current <start-chunk-number> if -count is used without a <start-chunk-number>.

Definition at line 637 of file soarapi.c.

References print(), setSoarResultResult(), soar_cSetChunkNameCount(), soar_cSetChunkNameLong(), soar_cSetChunkNamePrefix(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_CreateAgent (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_CreateAgent -- This command creates a new agent.

If there were no agents previously, the current agent is defined as the newly created agent. Otherwise, the current agent remains the same.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           create-agent [name]
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error
  • On SOAR_OK: Is empty
Side effects:
Creates a new agent, and possibly changes the current agent

Definition at line 90 of file soarapi.c.

References setSoarResultResult(), soar_cCreateAgent(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_DefaultWmeDepth (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_DefaultWmeDepth -- This is the command procedure for the "default-wme-depth" command, which sets/prints the default print depth.

With no arguments, this command prints the current default print depth used by the "print" command. With an integer argument, it sets the current default print depth. This default print depth can be overridden on any particular invocation of the "print" command by using the -depth flag, e.g., print -depth 10 args.... The default print depth is initially 1.

See also:
soar_Print
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           default-wme-depth [integer]
Returns:
Returns a standard Tcl completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets the default print depth for the agent.

Definition at line 2872 of file soarapi.c.

References getInt(), setSoarResultResult(), soar_ecSetDefaultWmeDepth(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_DestroyAgent (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_DestroyAgent -- This is the command procedure for the "destroy-agent" command, which destroys a Soar agent.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax: 
           destroy-agent [agent-name]
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Destroys a Soar agent; resets the current agent if necessary

Definition at line 195 of file soarapi.c.

References setSoarResultResult(), soar_cDestroyAgentByName(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_Excise (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Excise -- This is the command procedure for the "excise" command, which removes productions from Soar's memory.

"excise -chunks" removes all chunks and justifications from the agent. "excise -task" removes all non-default productions from the agent and performs an init-soar command. excise -all removes all productions from the agent. The switches may be abbreviated to 2 characters (e.g, -c for chunks).

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           excise production-name | -chunks | -default | -task 
                                  |-user | -all
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Removes the indicated productions from the agent memory. For -all and -task, does an init-soar.

Definition at line 428 of file soarapi.c.

References setSoarResultResult(), soar_cExciseAllProductions(), soar_cExciseAllProductionsOfType(), soar_cExciseAllTaskProductions(), soar_cExciseProductionByName(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_ExcludedBuildInfo (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ExcludedBuildInfo -- This is the command procedure for the "ex-build-info" command, which yields information about Soar.

This function indicates compile time setting which affect the current instantiation of Soar.

Note that the options which are printed using this function are filtered. The options presented using this command are those which are expected to be of lesser importance. However, using this command in conjunction with soar_BuildInfo will list all compile time options for the current build.

See also:
soar_BuildInfo
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           ex-build-info
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.

Definition at line 2924 of file soarapi.c.

References setSoarResultResult(), soar_ecExcludedBuildInfo(), SOAR_OK, soar_version_string, and soarResult.

int soar_ExplainBacktraces (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ExplainBacktraces -- This is the command procedure for the "explain-backtraces" command.

Explain provides some interpretation of backtraces generated during chunking. Explain mode must be ON when the chunk/ justification is CREATED or no explanation will be available. Explain mode is toggled using the save_backtraces variable. When explain mode is on, more memory is used, and building chunks/justifications will be slower.

The two most useful commands are 'explain-backtraces ' and *'explain-backtraces <cond-num>'. The first command lists all of the conditions for the named chunk/justification, and the 'ground' which resulted in inclusion in the chunk/justification. A 'ground' is a WME which was tested in the supergoal. Just knowing which WME was tested may be enough to explain why the chunk/justification exists. If not, the conditions can be listed with an integer value. This value can be used in 'explain <cond-num>' to obtain a list of the productions which fired to obtain this condition in the chunk/justification (and the crucial WMEs tested along the way). Why use an integer value to specify the condition? To save a big parsing job.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           explain-backtraces arg
           arg := ''                 list chunks/justifications if 
                                     explain is on
           arg := <name>             list all conditions & grounds for 
                                     a chunk/justification
           arg := <name> -full       give the backtrace for a named
                                     chunk/justification
           arg := <name> <cond-num>  explain why this condition is in 
                                     the chunk/justification
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
None.

Definition at line 1139 of file soarapi.c.

References explain_list_chunks(), get_lexeme_from_string(), getInt(), setSoarResultResult(), soar_ecExplainChunkCondition(), soar_ecExplainChunkConditionList(), soar_ecExplainChunkTrace(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and SYM_CONSTANT_LEXEME.

int soar_FiringCounts (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_FiringCounts -- This is the command procedure for the "firing-counts" command, which prints out how many times a production has fired.

This command prints how many times certain productions have fired. With no arguments, it lists all the productions sorted according to how many times they have fired. If an integer argument (call it k) is given, only the top k productions are listed. If k=0, only the productions which haven't fired at all are listed. Note that firing counts are not reset by an (init-soar); the counts indicate the number of firings since the productions were loaded or built.

NB: this is slow, because the sorting takes time O(n*log n)

With one or more production names as arguments, this command prints how many times each of those productions fired.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           firing-counts [[integer] | production-name* ]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: (Currently this never happens)
  • On SOAR_OK: Is unmodified.
Side effects:
Prints information about production firings.

Definition at line 1193 of file soarapi.c.

References getInt(), soar_ecPrintFiringsForProduction(), soar_ecPrintTopProductionFirings(), SOAR_OK, and soarResult.

int soar_FormatWatch (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_FormatWatch -- This is the command procedure for the "format-watch" command, which defines the format to use when printing objects and the Soar goal stack.

Object trace formats control how Soar prints an object-- e.g., a certain operator, problem-space, etc. (This is like trace-attributes in Soar 5.) Stack trace formats control how Soar prints its context stack selections in 'watch 0' and 'pgs' printouts. You specify a trace format by indicating two things:

  • a format string, indicating the printout format to be used
  • what things this format string can be applied to The format string can be any string. Certain 'escape sequences' can be used within the string; for example, '%dc' means print the current decision cycle number.

There are two ways to restrict what objects a format string applies to. The {s|o|*} argument restricts the types of objects: 's' indicates that the format only applies to states; 'o' means it only applies to operators; and '*' means it applies to any type of object. The [object-name] argument (for object trace formats), if given, means it only applies to objects with that ^name. The [ps-name] argument (for stack trace formats) means it only applies within problem spaces with that ^name.

With an -add argument, these commands add new trace formats (replacing any existing ones with identical applicability conditions). With a -remove argument, they remove trace formats with the given applicability conditions. With no arguments, they print out all current trace formats.

The following escape sequences can be used within trace format strings. The S indicates the sequence is ONLY usable in stack traces:

  • cs S- print the current state
  • co S- print the current operator * The cg, cp, cs, and co sequences use the appropriate object trace format.
  • dc S- print the current decision cycle number
  • ec S- print the current elaboration cycle number * The dc and ec sequences are NOT * meaningful in stack traces produced by the "pgs" command. In these cases, nothing is printed.
  • sd S- print the current subgoal depth * The sd sequence uses 0 as the top level).
  • rsd[pattern] S- repeat (subgoal depth) times: print the given pattern.
  • left[num,pattern] - print the pattern left justified in a field of num spaces.
  • right[num,pattern] - print the pattern right justified in a field of num spaces.
  • id - print the identifier of the current object.
  • v[foo] - print the value(s) of attribute ^foo on the current object. If there is no ^foo on the current object, nothing is printed.
  • v[foo.bar.baz] - same as the above, only follow the given attribute path to get the value(s).
  • v[*] - print all values of all attributes on the current object.
  • o[args] - same as v, except that if the value is an identifier it is printed using the appropriate object trace format.
  • av[args] - same as v, except the printed value is preceeded with "^attr " to indicate the attribute name.
  • ao[args] - a combination of the above two.
  • ifdef[pattern] - print the given pattern if and only if all escape sequences inside it are "meaningful" or "well-defined." For example, "%ifdef[foo has value: %v[foo]]" will print nothing if there is no ^foo on the current object.
  • nl - print a newline.
  • % - print a percent sign.
  • [ - print a left bracket.
  • ] - print a right bracket.
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           format-watch {-object | -stack} 
                     [{ { -add    {s|o|*} [name] format}  | 
                        { -remove {s|o|*} [name]       }  }]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets the indicated format.

Definition at line 1224 of file soarapi.c.

References add_trace_format(), get_lexeme_from_string(), make_sym_constant(), print_all_trace_formats(), remove_trace_format(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), SYM_CONSTANT_LEXEME, and Symbol.

int soar_IndifferentSelection (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_IndifferentSelection -- This is the command procedure for the "indifferent-selection" command which controls indifferent preference arbitration.

With no arguments, this command prints the current setting of indifferent-selection. With an argument, it sets indifferent-selection to the given value. This controls how Soar's decision procedure chooses between multiple indifferent items:

  • -first -- just choose the first one found (deterministically)
  • -last -- choose the last one found (deterministically)
  • -ask -- ask the user to choose one of the items
  • -random -- choose one randomly
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           indifferent-selection [-first | -ask | -last | -random ]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Modifies the setting of the indifferent-selection option.

Definition at line 1342 of file soarapi.c.

References set_sysparam(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_InputPeriod (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_InputPeriod -- This is the command procedure for the "input-period" command, which sets/prints the Soar input period.

With no arguments, this command stores the current period used to control the input rate to the Soar agent in the SoarResult. With an integer argument, it sets the current input period. If the argument is 0, Soar behaves as it did in versions before 6.2.4, accepting input every elaboration cycle. An input period of "n" means that input is accepted only every "n" decision cycles. The input period is initially set to 0. Negative integer values are disallowed.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           input-period [integer]
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current input period.
Side effects:
Sets/prints the input period for the agent.
----------------------------------------------------------------------

Definition at line 973 of file soarapi.c.

References getInt(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_InternalSymbols (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_InternalSymbols -- This is the command procedure for the "internal-symbols" command which prints information about the Soar agent symbol table.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           internal-symbols
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the current Soar agent symbol table

Definition at line 1393 of file soarapi.c.

References setSoarResultResult(), soar_ecPrintInternalSymbols(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_Interrupt (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

Definition at line 2962 of file soarapi.c.

References appendSoarResultResult(), find_sym_constant(), production_struct::interrupt, INTERRUPT_OFF, INTERRUPT_ON, INTERRUPT_PRINT, variable_struct::name, production_struct::name, print(), sym_constant_struct::production, production, symbol_union::sc, setSoarResultResult(), soar_apiInterruptSetting, soar_ecPrintAllProductionsWithInterruptSetting(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), Symbol, and symbol_union::var.

int soar_Learn (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Learn -- This is the command procedure for the "learn" command.

With no arguments, this command prints out the current learning status. Any of the following arguments may be given:

  • on - turns all learning on
  • off - turns all learning off
  • only - learning is off except as specified by RHS force-learn
  • except - learning is on except as specified by RHS dont-learn
  • list - print lists of force-learn and dont-learn states
  • all-goals - when learning is on, this allows learning at all goal stack levels (in contrast to bottom-up learning)
  • bottom-up - when learning is on, this allows learning at only the lowest goal stack level; i.e., a chunk is learned at a given level only if no chunk has yet been learned at a lower level.
See also:
chunk-free-problem-spaces

soar_Watch

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           learn arg*
              arg  ::=  -on | -only | -except | -off 
              arg  ::=  -all-goals | -bottom-up
              arg  ::=  -list
Returns:
Returns a standard Tcl completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains info from the 'list' sub-command.
Side effects:
Sets booleans for whether or not chunking done.

Definition at line 713 of file soarapi.c.

References ALL_LEVELS, appendSoarResultResult(), BOTTOM_UP, cons, EXCEPT, cons_struct::first, OFF, ON, ONLY, print_current_learn_settings(), cons_struct::rest, setSoarResultResult(), soar_cSetLearning(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), string_match_up_to(), Symbol, and symbol_to_string().

int soar_Log (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Log -- This is the command procedure for the "log" command which records session information to a log file.

This command may be used to open and close log files. With the -add argument, specific strings can also be added to the log file.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           log <action>
            <action> ::= [-new | -existing] pathname 
            <action> ::= -add string
            <action> ::= -query
            <action> ::= -off
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the state of the log file
Side effects:
Opens and/or closes log files.

Definition at line 2337 of file soarapi.c.

References appendSoarResultResult(), LOG_CALLBACK, setSoarResultResult(), soar_agent, soar_ecCloseLog(), soar_ecOpenLog(), SOAR_ERROR, soar_exists_callback(), soar_invoke_first_callback(), SOAR_OK, soarResult, and string_match_up_to().

int soar_Matches (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Matches -- This is the command procedure for the "matches" command.

This command prints partial match information for a selected production. It also prints information about the current match set.

The match set is a list of productions that are about to fire or retract in the next preference phase. With no arguments, this command prints out the production names for both Assertions and Retractions. The first optional argument specifies listing of either Assertions or Retractions.

The last optional argument specifies the level of detail wanted: -counts (the default for single productions) prints out just the partial match counts; -names (the default for match sets) prints out just the production names; -timetags also prints the timetags of wmes matched; and -wmes prints the wmes rather than just their timetags.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           matches production-name [ -count | -timetags | -wmes]
           matches production-name [ 0 | 1 | 2 ]
           ms [-assertions | -retractions] [-names| -timetags | -wmes]
           ms [-assertions | -retractions] [ 0 | 1 | 2 ]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints production match information.

Definition at line 1417 of file soarapi.c.

References ms_trace_type, setSoarResultResult(), soar_ecPrintMatchInfoForProduction(), soar_ecPrintMatchSet(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), string_match_up_to(), and wme_trace_type.

int soar_MaxChunks (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_MaxChunks -- This is the command procedure for the "max-chunks" command, which sets/prints the maximum number of chunks allowed.

With no arguments, this command returns the current value of the system variable "max-chunks" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of chunks allowed in a single decision cycle. After this many chunks have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-chunks is initially 50.) The maximum number of chunks can also be limited by setting the soar variable max_chunks.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           max-chunks [integer]
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current value of max-chunks
Side effects:
Sets the maximum chunks allowed.
----------------------------------------------------------------------

Definition at line 804 of file soarapi.c.

References getInt(), set_sysparam(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_MaxElaborations (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_MaxElaborations -- This is the command procedure for the "max-elaborations" command, which sets/prints the maximum elaboration cycles allowed.

With no arguments, this command returns the current value of the system variable "max-elaborations" in the SoarResult. With an integer argument, it sets the current value. This variable controls the maximum number of elaboration cycles allowed in a single decision cycle. After this many elabloration cycles have been executed, Soar proceeds to decision phase even if quiescence hasn't really been reached yet. (Max-elaborations is initially 100.)

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           max-elaborations [integer]
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current value of max-elaborations
Side effects:
Sets the maximum elaborations allowed.
----------------------------------------------------------------------

Definition at line 772 of file soarapi.c.

References getInt(), set_sysparam(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_Memories (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Memories -- This is the command procedure for the "memories" command, which prints information about memory use.

Information is displayed about the memory usage in tokens, of partial matches of productions. If a production-name is given, memory use for that production is printed. If no production name is given, memories will list 'count' productions of the specified type (or all types, if no type is specified). If 'count' is omitted, memory use of all productions is printed.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           memories [arg*]
            arg  ::=  -chunk | -user | -default | -justification 
                             | production-name | count
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints information about memory usage of partial matches.

Definition at line 1465 of file soarapi.c.

References count_rete_tokens_for_production(), getInt(), name_to_production(), print(), production, setSoarResultResult(), soar_ecPrintMemories(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_MultiAttributes (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_MultiAttributes -- This is the command procedure for the "multi-attributes" command, which enables a symbol to have multiple attribute values.

If given, the value must be a positive integer > 1. The default is 10. If no args are given on the cmdline, the list of symbols that are multi-attributed is printed.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           multi-attributes symbol [value]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Defines the symbol to be multi-attributed or prints a list of symbols that are declared to multi-attributed.

Definition at line 1011 of file soarapi.c.

References getInt(), print_multi_attribute_symbols(), setSoarResultResult(), soar_cMultiAttributes(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_NumericIndifferentMode (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_NumericIndifferentMode -- This is the command procedure for the "numeric-indifferent-mode" , command which controls the way o-support calculations are done (for the current agent).

It takes a single string argument:

  • -avg - do numeric indiffernce by averaging all values asserted by the rules. Indifferent preferrences with no explicit value are assigned the numeric weight of 50.
  • -sum - do numeric indifference by summing all values asserted by the rules. Indifferent prefferences with no explicit value are assigned the numeric weight of 0.
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           numeric-indifferent-mode arg*
					    arg ::=   -avg | -sum
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the current o-support mode.
Side effects:
Sets current_agent(numeric_indifferent_mode).

Definition at line 1055 of file soarapi.c.

References NUMERIC_INDIFFERENT_MODE_AVG, NUMERIC_INDIFFERENT_MODE_SUM, setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_Operand2 (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Operand2 -- This is the command procedure for the "soar8" command.

With no arguments, this command prints out the current operand state. Otherwise it turns on or off soar8 mode.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           operand2 arg*
              arg  ::=  -on | -off
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current operand state.
Side effects:
re-initializes soar and puts it in the requested mode. Also modifies the soar_version_string.

Definition at line 839 of file soarapi.c.

References print(), setSoarResultResult(), soar_cSetOperand2(), SOAR_ERROR, SOAR_OK, soarResult, and string_match().

int soar_OSupportMode (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_OSupportMode -- This is the command procedure for the "o-support-mode" command, which controls the way o-support calculations are done (for the current agent).

It takes a single numeric argument:

  • 0 - do o-support calculations the normal (Soar 6) way.
  • 1 - do o-support calculations the normal (Soar 6) way, but print a warning message whenever a preference is created that would get different support under Doug's proposal.
  • 2 - do o-support calculations according to Doug Pearson's proposal. (See osupport.c for details.)
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           o-support-mode {0 | 1 | 2}
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the current o-support mode.
Side effects:
Sets current_agent(o_support_calculation_type).

Definition at line 1099 of file soarapi.c.

References setSoarResultResult(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_Pool (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Pool -- This is the command procedure for the "pool" command, which yields debugging information on various internal memory pools

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           pool [-all] <pool-name> <pool-args>
pool-name is one of: -wme -condition -preference -instantiation -identifier -production

pool-arguements:

for -instantiation, one of: -none (no wme information) -full (full wme information)

for -production, one of: -name (print production name only) -full (print entire production)

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
None

Definition at line 2069 of file soarapi.c.

References examine_memory_pool(), print_all_conditions_in_block(), print_all_identifiers_in_block(), print_all_instantiations_in_block(), print_all_preferences_in_block(), print_all_productions_in_block(), print_all_wmes_in_block(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and string_match_up_to().

int soar_Preferences (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Preferences -- This is the command procedure for the "preferences" command, which prints all the preferences for the given slot.

This command prints all the preferences for the slot given by the 'id' and 'attribute' arguments. The optional 'detail' argument must be one of the following (-none is the default):

  • -none -- prints just the preferences themselves
  • -names -- also prints the names of the productions that generated them
  • -timetags -- also prints the timetags of the wmes matched by the productions
  • -wmes -- prints the whole wmes, not just their timetags.
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           preferences [id] [attribute] [-none | -names | -timetags | -wmes]
	   preferences [id] [attribute] [ 0 | 1 | 2 | 3 ]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints preference information.

Definition at line 1662 of file soarapi.c.

References read_attribute_from_string(), read_id_or_context_var_from_string(), read_pref_detail_from_string(), setSoarResultResult(), soar_ecPrintPreferences(), SOAR_ERROR, SOAR_OK, soarResult, Symbol, symbol_to_string(), and wme_trace_type.

int soar_Print (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Print -- This is the command procedure for the "print" command, which prints various Soar items.

The print command is used to print items from production memory or working memory. It can take several kinds of arguments. When printing items from working memory, the objects are printed unless the -internal flag is used, in in which case the wmes themselves are printed.

See also:
default-wme-depth
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           print <stack>|<items>
            <stack>  ::= -stack [-state | -operator]*
            <items>  ::= [-depth n] [-internal] [-filename] <arg>*
            <arg>    ::= production-name  print that production
            <arg>    ::= production type  [-name | -full] -all | -chunks | 
                                          -defaults | -user | -justifications
            <arg>    ::= identifier       id of the object to print
            <arg>    ::= integer          timetag of wme--the identifier 
                                          from the wme indicates the object 
                                          to be printed
            <arg>    ::= <pattern>        pattern--same as if you listed 
                                          as arguments the timetags of all 
                                          wmes matching the pattern,
                                          often results in multiple copies
                                          of the same object being printed
   
          <pattern> ::= '{' '('  {identifier | '*'} 
                               ^ {attribute  | '*'} 
                                 {value      | '*'} 
                                 [+] ')' '}'
The optional [-depth n] argument overrides default-wme-depth. The optional [-internal] argument tells Soar to print things in their internal form. For productions, this means leaving conditions in their reordered (rete net) form. For wmes, this means printing the individual wmes with their timetags, rather than the objects. The optional [-filename] argument tells Soar to print the filename for source'd productions.

-depth 0 is meaningful only for integer and pattern arguments. It causes only the matching wmes to be printed, instead of all wmes whose id is an id in one of the matching wmes.

-name | -full apply to printing productions. For the specified production type, only the production name will be printed, unless the -full flag is specified. For named productions, the default is to print the entire production unless -name is specified. (-name for an individual prod seems silly, but it's included for completeness...)

The -depth n, -internal, -name, and -full flags apply only to the args that appear after them on the command line.

Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the selected objects.
kjh CUSP(B11) = "Soar should know the file name from which a given production was loaded."

The changes here to PrintCmd are meant to be more illustrative of how to provide a production's file name to the user than they are meant to be final changes to PrintCmd, which is undergoing concurrent work at this time.

print -filename <production-name>+

Definition at line 1772 of file soarapi.c.

References cons, do_print_for_identifier(), do_print_for_production_name(), do_print_for_wme(), cons_struct::first, free_list(), get_lexeme(), get_lexeme_from_string(), getInt(), symbol_union::id, IDENTIFIER_LEXEME, INT_CONSTANT_LEXEME, list, identifier_struct::lower_goal, identifier_struct::operator_slot, print(), print_stack_trace(), QUOTED_STRING_LEXEME, read_identifier_or_context_variable(), read_pattern_and_get_matching_wmes(), cons_struct::rest, wme_struct::rete_next, setSoarResultResult(), soar_agent, soar_alternate_input(), soar_ecPrintAllProductionsOfType(), SOAR_ERROR, SOAR_OK, soarResult, string_match_up_to(), SYM_CONSTANT_LEXEME, Symbol, wme_struct::timetag, wme_struct::value, VARIABLE_LEXEME, wme, and slot_struct::wmes.

int soar_ProductionFind (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ProductionFind -- This is the command procedure for the "production-find" command, which finds Soar productions by characteristic.

pf is a production finding facility. It allows you to find productions that either test a particular LHS pattern or produce particular RHS preferences.

The syntax of the lhs-conditions or rhs-actions is exactly their syntax within SP's. In addition, the symbol '*' may be used as a wildcard for an attribute or value. Note that variable names do not have to match the specific names used in productions.

Specifying -chunks means only chunks are searched (and -nochunks means no chunks are searched).

Note that leading blanks in the clause will cause pf to fail.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Examples:

Find productions that test that some object gumby has attribute ^alive t, and test an operator named foo: production-find {( ^gumby ^operator.name foo)( ^alive t)}

Find productions that propose foo: production-find -rhs {( ^operator +)( ^name foo)}

Find productions that test the attribute ^pokey: production-find {( ^pokey *)}

Find productions that test the operator foo production-find {( ^operator.name foo)}

Syntax:
           production-find [side] [chnks] [-show-bindings] {clauses}
	        side  :==  -rhs | -lhs
		chnks :==  -chunks | -nochunks
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Prints the productions found

Definition at line 1540 of file soarapi.c.

References free_list(), get_lexeme(), list, print(), read_pattern_and_get_matching_productions(), read_rhs_pattern_and_get_matching_productions(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_PWatch (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_PWatch -- This is the command procedure for the "pwatch" command which enables the tracing of production firing.

This command enables tracing of the firings and retractions of individual productions. (This mechanism is orthogonal to the watch -firings mechanism. See the "watch" command for more information. PWatch, with no arguments, lists the productions currently being traced. With one or more production name arguments, it enables tracing of those productions. Using the -on or -off option explicitly turns tracing on or off for the given productions. Tracing persists until disabled, or until the production is excised.

See also:
soar_Watch

soar_Excise

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           pwatch [-on | -off] production-name*
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Enables the tracing of the specified productions.

Definition at line 2001 of file soarapi.c.

References cons, cons_struct::first, print_with_symbols(), production, cons_struct::rest, setSoarResultResult(), soar_ecBeginTracingProductions(), soar_ecPrintProductionsBeingTraced(), soar_ecStopAllProductionTracing(), soar_ecStopTracingProductions(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_Quit (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Quit -- This is the command procedure for the "quit" command, which prepares Soar to be exited.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           quit
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
turns logging off, does some clean up.

Definition at line 222 of file soarapi.c.

References soar_cQuit(), SOAR_OK, and soarResult.

int soar_ReInitSoar (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ReInitSoar -- This is the command procedure for the "init-soar" command, it (re)initializes the Soar agent.

This command removes all wmes from working memory, wiping out the goal stack, and resets all statistics (except the counts tracking how many times each individual production has fired which is used by the "firing-counts" command).

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the function.
Syntax:
  
           init-soar
Returns:
A standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about the error.
  • On SOAR_OK: Is empty
Side effects:
Empties working memory, removes the goal stack, and resets statistics.

Definition at line 69 of file soarapi.c.

References soar_cReInitSoar(), SOAR_OK, and soarResult.

int soar_RemoveWme (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_RemoveWme -- This is the command procedure for the "remove-wme" command, which removes a wme from Soar's memory.

WARNING: this command is inherently unstable and may have weird side effects (possibly even including system crashes). For example, the chunker can't backtrace through wmes created via add-wme. Removing input wmes or context/impasse wmes may have unexpected side effects. You've been warned.

See also:
soar_AddWme
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           remove-wme integer
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Removes the selected working memory element from Soar.

Definition at line 383 of file soarapi.c.

References getInt(), setSoarResultResult(), soar_cRemoveWmeUsingTimetag(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_ReplayInput (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ReplayInput -- This is the command procedure for the "replay-input" command which is used to playback previously recorded input.

Input originally obtained using the "capture-input" command is replayed with this command

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           replay-input <action>
            <action> ::= -open pathname 
            <action> ::= -query
            <action> ::= -close
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the status of the replay file
Side effects:
Opens and/or closes replay files.

Definition at line 561 of file soarapi.c.

References appendSoarResultResult(), setSoarResultResult(), soar_ecReplayInput(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_ReteNet (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_ReteNet -- This is the command procedure for the "rete-net" command, which saves or loads a rete-network.

The rete-net is a binary file containing the contents of production memory. Because productions are decomposed into their constituent conditions before being added to the network, the productions themselves are difficult to recognize. Although this file format is not encrypted in any real sense, it does obfuscate productions to a degree similar to compilation of source code.

Moreoever, if productions are saved as a rete-net, they can be loaded by a version of Soar which does not contain a productions parser (and supporting elements) this allows a significantly smaller footprint for the executable when memory is at a premium.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           rete-net {-save | -load} {filename}
Returns:
Returns a standard SOAR completion code
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Adds the given wme to working memory.

Definition at line 253 of file soarapi.c.

References setSoarResultResult(), soar_cLoadReteNet(), soar_cSaveReteNet(), SOAR_ERROR, SOAR_OK, soarResult, and string_match().

int soar_Run (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Run -- This is the command procedure for the "run" command which runs the Soar agent.

This is the command for running Soar agents. It takes two optional arguments, one specifying how many things to run, and one specifying what type of things to run (by default all agents are run). The following types are available:

  • p - run Soar for n phases. A phase is either an input phase, preference phase, working memory phase, output phase, or decision phase.
  • e - run Soar for n elaboration cycles. (For purposes of this command, decision phase is counted as an elaboration cycle.)
  • d - run Soar for n decision cycles.
  • s - run Soar until the nth time a state is selected.
  • o - run Soar until the nth time an operator is selected.
  • out - run Soar by decision cycles until output is generated.
  • context-variable - run Soar until the nth time a selection is made for that particular context slot, or until the context stack pops to above that context. Unlike Soar 6 "go" , "run" has no memory of settings from previous run commands.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           run [integer | 'forever'] [type] [-self]
           type ::= p | e | d | s | o | context-variable
           if no integer given, but [type] is specified, n = 1 assumed
           if no [type] given, but [int] specified, decisions assumed
Examples:
  • run 5 d -> run all agents for 5 decision cycles
  • run d -self -> run the current agent only for 5 decision cycles
  • run 3 -> run all agents for 3 decision cycles
  • run e -> run all agents for 1 elaboration cycle
  • run 1 s -> run all agents until the next state is selected (i.e., until the next time an impasse arises)
  • run -> run until the next superoperator is selected (or until the supergoal goes away)
  • run 3 -> run for 3 operator selections at this level (continuing through any subgoals that arise)
Returns:
Returns a standard SOAR completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Runs the Soar agents for the indicated duration

Definition at line 119 of file soarapi.c.

References agent, all_soar_agents, cons, GO_DECISION, go_type_enum, goal_stack_level, parse_run_command(), cons_struct::rest, run_all_agents(), run_current_agent(), soar_agent, SOAR_ERROR, SOAR_OK, soarResult, and Symbol.

int soar_Sp (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Sp -- This is the command procedure for the "sp" command, which defines a new Soar production.

This command adds a new production to the system. (If another production with the same name already exists, it is excised.) The optional flags are as follows:

  • :o-support -- specifies that all the RHS actions are to be given o-support when the production fires
  • :no-support -- specifies that all the RHS actions are only to be given i-support when the production fires
  • :default -- specifies that this production is a default production (this matters for (excise-task) and (watch task))
  • :chunk -- specifies that this production is a chunk (this matters for (learn trace))
See also: lhs-grammar, rhs-grammar

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           sp {rule-body}
            rule-body := name 
                        ["documentation-string"] 
                        [ flag ]*
                        LHS
                        ->
                        RHS
  
            flag  ::=  :o-support
            flag  ::=  :i-support
            flag  ::=  :default
            flag  ::=  :chunk
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty -- note OK so long as the proper number of arguments is supplied. Invalid productions don't cause an error....
Side effects:
Runs the agent for the indicated number of decision cycles.

Definition at line 2155 of file soarapi.c.

References setSoarResultResult(), soar_ecSp(), SOAR_ERROR, SOAR_OK, and soarResult.

int soar_Stats (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Stats -- This is the command procedure for the "stats" command, which prints out internal statistical information.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           stats [-system <stype> | -memory <mtype> | -rete <rtype>] 
           <stype> ::= -default-production-count
                       -user-production-count
                       -chunk-count
                       -justification-count
                       -all-productions-count
                       -dc-count
                       -ec-count
                       -ecs/dc
                       -firings-count
                       -firings/ec
                       -wme-change-count
                       -wme-addition-count
                       -wme-removal-count
                       -wme-count
                       -wme-avg-count
                       -wme-max-count
                       -total-time             |T
                       -ms/dc                  |T
                       -ms/ec                  |T
                       -ms/firing              |T
                       -ms/wme-change          |T
                       -match-time             |D
                       -ownership-time         |D
                       -chunking-time          |D
  
           The items marked |T are available when Soar has been
           compiled with the NO_TIMING_STUFF flag NOT SET and 
           the items marked |D are available when Soar has been
           compiled with the DETAILED_TIMING_STATS flag SET.
   
           <mtype> ::= -total
                       -overhead
                       -strings
                       -hash-table
                       -pool [-total | pool-name [<aspect>]]
                       -misc
          <aspect> ::= -used                   |M
                       -free                   |M
                       -item-size
                       -total-bytes
  
            The items marked |M are available only when Soar has
            been compiled with the MEMORY_POOL_STATS option.
  
            <rtype> ::= -total-nodes
                        -dummy-top-nodes
                        -pos-nodes
                        -unhashed-pos-nodes
                        -neg-nodes
                        -unhashed-neg-nodes
                        -cn-nodes
                        -cn-partner-nodes
                        -production-nodes
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is unmodified.
Side effects:
Prints the selected statistics

Definition at line 2186 of file soarapi.c.

References parse_memory_stats(), parse_rete_stats(), parse_system_stats(), printTimingInfo(), setSoarResultResult(), soar_ecPrintDCHistogram(), soar_ecPrintKTHistogram(), SOAR_ERROR, soarResult, and string_match_up_to().

int soar_Stop (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Stop -- This is the command procedure for the "stop-soar" command, halts the Soar agents.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           stop-soar [-s[elf] [reason-string]]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
All agents are halted.

Definition at line 2226 of file soarapi.c.

References setSoarResultResult(), soar_cStopAllAgents(), soar_cStopCurrentAgent(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_Verbose (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Verbose -- This is the command procedure for the "verbose" command

With no arguments, this command prints out the current verbose state. Any of the following arguments may be given:

  • on - turns verbose on
  • off - turns verbose off
Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           verbose arg*
             arg  ::=  -on | -off
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
none. it just sets soar_verbose_flag.

Definition at line 2263 of file soarapi.c.

References print(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and string_match_up_to().

int soar_WaitSNC (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_WaitSNC -- This is the command procedure for the "waitsnc" command.

With no arguments, this command stores the current wait/snc state in the SoarResult. If this mode is on, soar waits (in its current state) for new things to happen. If it is off, then soar generates impasses when the state does not change.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           waitsnc arg*
              arg  ::=  -on | -off
Returns:
Returns a standard Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty or contains the current wait/snc state.
Side effects:
Changes the wait/snc state
----------------------------------------------------------------------

Definition at line 932 of file soarapi.c.

References print(), setSoarResultResult(), soar_cSetWaitSNC(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and string_match_up_to().

int soar_Warnings (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Warnings -- This is the command procedure for the "warnings" command, which enables/disables the printing of warning messages.

warnings -on enables the printing of warning messages. This is the default. warnings -off turns off most warning messages. warnings prints an indication of whether warning messages are enabled or not.

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Synax:
           warnings [-on | -off]
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Contains the state of the warnings.
Side effects:
Sets the warnings option.

Definition at line 2301 of file soarapi.c.

References set_sysparam(), setSoarResultResult(), SOAR_ERROR, SOAR_OK, soarResult, and string_match_up_to().

int soar_Watch (  int  argc,
const char *  argv[],
soarResult *  res
) 
 

soar_Watch -- This is the command procedure for the "watch" command, which controls run-time tracing.

This command controls what information gets printed in the run-time trace. With no arguments, it just prints out the current watch status. The numeric arguments are different from the semantics in Soar 5 and 6; for details, see help watch. Setting either the -on or -off switch selectively turns on or off only that setting. Setting the -inclusive switch (which can be abbreviated as -inc) or setting no flag at all has the effect of setting all levels up to and including the level specified. For example, watch productions -on selectively turns on the tracing of production firings/retractions; watch productions -off selectively turns it off again. watch productions [-inc] turns on the tracing of productions and also turns on tracing of all levels below productions: decisions and phases, too. Individual watch parameters may be used to modify the inclusive settings as well, selectively turning on or off and levels outside or inside the inclusive range.

The following keyword arguments may be given to the 'watch' command:

  • 0|none -- turns off all printing about Soar's internals
  • 1|decisions -- controls whether state and operator decisions are printed as they are made
  • 2|phases -- controls whether phase names are printed as Soar executes
  • 3|productions -- controls whether the names of productions are printed as they fire and retract. See individual production-type args below.
  • 4|wmes -- controls whether changes to working memory are printed
  • 5|preferences -- controls whether the preferences generated by the traced productions are printed when those productions fire or retract. When a production fires, all the preferences it generates are printed. When it retracts, only the ones being removed from preference memory are printed (i.e., the i-supported ones).
  • -nowmes|-timetags|-fullwmes -- controls the level of detail given about the wmes matched by productions whose firings and retractions are being traced. Level 0|-nowmes means no information about the wmes is printed. Level 1|-timetags means the wme timetags are printed. Level 2|-fullwmes means the whole wmes are printed.
  • -all|-default|-chunks|-justifications|-user {-noprint|-print|-fullprint} allows user to selectively print production *types* as they fire and retract. -noprint prints nothing, -print prints the production name, -fullprint prints the entire production. (fullprint not yet implemented) NOTE: these args can be abbreviated by the first char ONLY, otherwise the full arg must be specified.
  • -prefs|-noprefs -- turns on|off the printing of preferences for the productions being watched. These args need to be made to apply to just the given production type, instead of to all productions.
  • aliases -on|-off -- controls the echoing of aliases as they are defined.
  • backtracing -on|-off -- controls the printing of backtracing information when a chunk or justification os created.
  • learning -noprint|-print|-fullprint -- controls the printing of chunks/justifications as they are created. -noprint is don't print anything, -names prints just the names, -fullprint prints the entire chunk/justification.
  • loading -on|-off -- controls the printing of '*' for each production loaded and a '#' for each production excised.
Currently the following args apply to all productions being watched, but they need to be changed to apply to only the specified production type. This requires the addition of many new kernel flags, one for each arg for each production type. -nowmes|-timetags|-fullwmes -noprint|-print|-fullprint -prefs|-noprefs

See also:
soar_Learn

soar_PWatch

soar_Print

Parameters:
-> argc The number of arguments is the argv block
-> argv An array of strings, each of which is a word in the argument list to this function
<- res A SoarResult structure which will be filled in by the
Syntax:
           watch arg*
             arg  ::=  0 | 1 | 2 | 3 | 4 | 5
             arg  ::=  0 | none
             arg  ::=  decisions | phases | productions | wmes | preferences
                          [-on | -off | -inc[lusive]]
             arg  ::=  -nowmes | -timetags | -fullwmes
             arg  ::=  aliases  {-on|-off}
             arg  ::=  backtracing {-on|-off}
             arg  ::=  learning {-noprint|-print|-fullprint}
             arg  ::=  loading  {-on|-off}
Returns:
Returns a Soar completion code.
SoarResult:
  • On SOAR_ERROR: Contains details about error.
  • On SOAR_OK: Is empty.
Side effects:
Sets booleans for printing information during Soar execution cycles.

Definition at line 2486 of file soarapi.c.

References appendSoarResultResult(), parse_filter_type(), print(), print_current_watch_settings(), set_sysparam(), set_watch_prod_group_setting(), set_watch_setting(), setSoarResultResult(), soar_ecAddWmeFilter(), soar_ecListWmeFilters(), soar_ecRemoveWmeFilter(), soar_ecResetWmeFilters(), soar_ecWatchLevel(), SOAR_ERROR, SOAR_OK, soarResult, string_match(), and string_match_up_to().

Generated on Thu Dec 11 13:00:34 2003 for Soar Kernel by doxygen 1.3.5