This command redirects the printing of output strings. This is useful for applications which need to change where printed results are placed. Printed output is normally sent to standard output. However, if a Graphical User Interface (GUI) is being used in place of the command line interpreter, then printed output should appear in the GUI. GUIs are composed of elements called "widget"s and printed output would be directed to a "text widget".
Printed output is normally sent to standard output which is an open file descriptor in UNIX. Printed output can be sent to any other open file descriptor as well, such as an open file or pipe. It is also possible that the user is not interested in an agent's printed output. In that case, the printed output can be discarded -- which results in faster processing for the agent as well.
Some commands return results and some print results. If the user wishes to have printed results returned so that they can be saved for later use, then this command can setup the agent to append the printed output to the normal result. This capability is also useful when sending Soar commands from remote Tcl/Tk interpreters. By appending the printed results, all printed characters can be returned to the remote interpreter rather than going to a screen.
The printing facility is implemented as a stack, so newly installed print redirections are in force until popped off the stack. This is done to allow easy transient redirection and the restoration of prior printing contexts after completing a printing task. Hence, there are two primary actions, -push and -pop. The -pop action takes no additional arguments as it serves only to pop the print-redirection stack to re-establish the prior printing context. The -push action takes the following additional arguments:
output-strings-destination -push -text-widget .text
This example redirects prints to the text widget ".textual" in the interpreter named control.
output-strings-destination -push -text-widget .textual control
This example redirects prints to the open file "stdout":
output-strings-destination -push -file-id stdout
This example causes all printing to be supressed:
output-strings-destination -push -discard
This example removes the most recently added print destination:
output-strings-destination -pop