cmd_output

output

Controls settings related to Soar's output

Synopsis

=======================================================
-           Output Sub-Commands and Options           -
=======================================================
output                                       [? | help]
-------------------------------------------------------
enabled                                              on   Global toggle
console                                             off   For debugging
callbacks                                            on   Standard printing
-------------------------------------------------------
output log                   [--append | -A] <filename>   Log output to file
output log                               --add <string>
output log                                    [--close]
-------------------------------------------------------
output command-to-file         [-a] <file> <cmd> [args]   Log single command
-------------------------------------------------------
print-depth                                           2   Default print depth
warnings                                             on   Print all warnings
verbose                                             off   Print erbose output
echo-commands                                       off   Echo to debugger
-------------------------------------------------------
To view/change a setting:    output <setting> [<value>]

For a detailed explanation of these settings:             help output

Summary Screen

Using the output command without any arguments will display some key output settings:

=======================================================
-                   Output Status                     -
=======================================================
Printing enabled                                    Yes
Print warnings                                      Yes
Print verbose output                                 No

To enable specific types of trace messages, use the 'trace' command.

Use 'output ?' for a command overview or 'help output' for the manual page.

Sub-Commands

command-to-file

This command logs a single command. It is almost equivalent to opening a log using clog, running the command, then closing the log, the only difference is that input isn't recorded.

Running this command while a log is open is an error. There is currently not support for multiple logs in the command line interface, and this would be an instance of multiple logs.

This command echoes output both to the screen and to a file, just like clog.

Command-to-file Options

Option	Description
-a, --append	Append if file exists.
filename	The file to log the results of the command to
command	The command to log
args	Arguments for command

log

The output log command allows users to save all user-interface input and output to a file. When Soar is logging to a file, everything typed by the user and everything printed by Soar is written to the file (in addition to the screen).

Invoke output log with no arguments to query the current logging status. Pass a filename to start logging to that file (relative to the command line interface's home directory). Use the close option to stop logging.

Log Usage

output log [-A] filename
output log --add string
output log --close

Log Options

Option	Description
filename	Open filename and begin logging.
-c, --close	Stop logging, close the file.
-a, --add string	Add the given string to the open log file.
-A, --append	Opens existing log file named filename and logging is added at the end of the file.

Log Examples

To initiate logging and place the record in foo.log:

output log foo.log

To append log data to an existing foo.log file:

output log -A foo.log

To terminate logging and close the open log file:

output log -c

Known Issues with log

Does not log everything when structured output is selected.

Output General Settings

Invoke a sub-command with no arguments to query the current setting. Partial commands are accepted.

Option	Valid Values	Default
echo-commands	yes or no	off
print-depth	>= 1	1
verbose	yes or no	no
warnings	yes or no	yes

echo-commands

'echo-commands' will echo typed commands to other connected debuggers. Otherwise, the output is displayed without the initiating command, and this can be confusing.

print-depth

The 'print-depth' command reflects the default depth used when working memory elements are printed (using the print). The default value is 1. This default depth can be overridden on any particular call to the print command by explicitly using the --depth flag, e.g. print --depth 10 args.

By default, the print command prints objects in working memory, not just the individual working memory element. To limit the output to individual working memory elements, the --internal flag must also be specified in the print command. Thus when the print depth is 0, by default Soar prints the entire object, which is the same behavior as when the print depth is 1. But if --internal is also specified, then a depth of 0 prints just the individual WME, while a depth of 1 prints all WMEs which share that same identifier. This is true when printing timetags, identifiers or WME patterns.

When the depth is greater than 1, the identifier links from the specified WME's will be followed, so that additional substructure is printed. For example, a depth of 2 means that the object specified by the identifier, wme-pattern, or timetag will be printed, along with all other objects whose identifiers appear as values of the first object. This may result in multiple copies of the same object being printed out. If --internal is also specified, then individuals WMEs and their timetags will be printed instead of the full objects.

verbose

The 'verbose' command enables tracing of a number of low-level Soar execution details during a run. The details printed by verbose are usually only valuable to developers debugging Soar implementation details.

warnings

The 'warnings' command enables and disables the printing of warning messages. At startup, warnings are initially enabled. If warnings are disabled using this command, then some warnings may still be printed, since some are considered too important to ignore.

The warnings that are printed apply to the syntax of the productions, to notify the user when they are not in the correct syntax. When a lefthand side error is discovered (such as conditions that are not linked to a common state or impasse object), the production is generally loaded into production memory anyway, although this production may never match or may seriously slow down the matching process. In this case, a warning would be printed only if warnings were on. Righthand side errors, such as preferences that are not linked to the state, usually result in the production not being loaded, and a warning regardless of the warnings setting.

Default Aliases

output command-to-file     ctf
output log                 clog
output print-depth         default-wme-depth 
output echo-commands       echo-commands 
output verbose             verbose 
output warnings            warnings