NAME

output-strings-destination - Specify destination of print actions

SYNOPSIS

output-strings-destination action

DESCRIPTION

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", or procedure.

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 Soar 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:

-append-to-result
Instead of printing, append the output string to the result returned by a command. This option is useful for getting all the output when the command is invoked remotely.
-channel open-file-id
Redirect prints to the open channel (file or pipe) denoted by open-file-id
-discard
Ignore prints (similar to redirecting to /dev/null in the Bourne shell, sh)
-procedure proc-name
Redirect prints to the Tcl procedure named proc-name in the current interpreter. Tk widgets are also procedures, so this action sends output to widget procedures (or any other Tcl procedure).
-text-widget widget-name [interp-name]
Redirect prints to the text widget named widget-name in the current interpreter. If interp-name is specified, then prints are redirected to the text widget named widget-name in the interpreter named interp-name.

EXAMPLES

This example redirects prints to the text widget ".text":
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

WARNINGS

This command only affects the printing generated by Soar commands such as print and echo. It does not affect printing done by the Tcl commands such as puts.

SEE ALSO

echo, print, log