Introduction

This background section is intended to familiarize you with available resources and tools that are available. Some may be referenced elsewhere in this guide. Essentially, this is intended to be a brief reference for information that you might otherwise have trouble finding on your own.

Learning Soar

This guide assumes you already understand Soar syntax and the decision cycle. It explains various patterns for solving various problems, but generally does not explain syntax or how programs execute at a detailed level.

If you'd like to learn Soar, there are several resources:

• The Soar Tutorial: http://soar.eecs.umich.edu/Downloads
  • The tutorial is available as a complete downloadable version of Soar that includes the tutorial documents and example agents. A new version is released with each new version of Soar, although mostly this is just updating Soar, not the tutorial itself. You can also get Soar without the tutorial if desired.
• The Soar Manual: http://soar.eecs.umich.edu/articles/articles/documentation/72-soar-manual
  • It also comes with the Soar download. This is really more of a reference document. It explains all the gory details of how Soar actually runs, the syntax, and documents things like RHS functions, etc. I found it useful to skim through this when I was learning Soar as you will find out about a lot of details you would otherwise miss.
• The Soar code: https://github.com/SoarGroup/Soar,https://github.com/soartech/jsoar
  
  • Not for the faint of heart :) The real value in looking at the code is either for those who want to integrate Soar with their systems (the SML layer is pretty well documented), or for those interested in the undocumented RHS functions (there are a lot).
• The Soar Workshop: https://web.eecs.umich.edu/~soar/workshop/
  • Held every year, usually in early June, usually at University of Michigan in Ann Arbor. Attendance is free, and typically the first 2 days are a hands-on tutorial.
• Of course, feel free to join the soar-group mailing list and ask questions there: https://lists.sourceforge.net/lists/listinfo/soar-group

Tcl and Soar

Tcl is perhaps one of the most useful tools for writing Soar code. Specifically Tcl (as opposed to any other language) because, for historical reasons, Soar's syntax was designed to be Tcl compatible. If you think you aren't interested in Tcl, feel free to skip this subsection. Perhaps the examples throughout the rest of the guide will change your mind.

Long ago, Soar was implemented as a Tcl plugin. This was done for the convenience of being able to use Tcl (which we'll get to in a moment). Even the debugger was implemented in Tk. As a result of this, the Soar syntax has been designed to be Tcl-compatible. That is, it is possible to load Soar code into a Tcl interpreter (if the appropriate Tcl procedures are defined). Since 8.6, Soar has been a standard C/C++ library (and JSoar has always been a Java library), and thus Tcl support was lost to CSoar for a while. But recent work has made it possible again. JSoar has always supported Tcl.

Before we get into why you'd want to load Soar code into a Tcl interpreter, a brief note about what Tcl is generally good at. Tcl is a general programming language, so it can theoretically be used for anything. But it's strength is in generating and manipulating strings.

Thus, the reason you'd want to use Tcl and Soar together is that you can use Tcl to generate Soar code. Indeed, many people treat Tcl as a "macro" language, so they can generate reusable snippets of their code using a macro (more formally, Tcl variables and procedures). Soar itself has direct no support for features that are common in other languages, like constants, reusable code, etc. Since all structures need to be connected to the state, Soar code can sometimes be verbose, where a long chain of conditions is needed to get at the thing you actually care about. This can make the rules hard to read as it's not clear which conditions are actually the important ones – the ones that the rule is really "about". It also makes it easy to introduce errors, especially through typos. Tcl makes it possible to address these issues.

Tcl can be used in lots of ways, from simple to complex:

• Tcl variables as constants: see constants
• Tcl procedures as rule fragments: capture common conditions and actions. NGS does this a lot. This can turn several lines of Soar code into a single line of Tcl code. In this case, the Tcl code is just inline with the other conditions and actions in the Soar rule.
• Tcl procedures to generate entire (sets of) rules: if you have lots of rules that follow the same basic pattern (e.g., everything about the rules is the same except for which constants are tested and created), then you can capture that pattern in a Tcl procedure and generate the rules using just a couple parameters. This also means that if you want to change the pattern, you only have to change it in one place. Binning data gives an example of this.
• Tcl procedures to define entire domain-specific languages: This is beyond the scope of this guide, but you can actually create your own languages. For example, you might write something that looks kind of like a Soar rule, but is composed entirely of Tcl code, and which generates a whole bunch of Soar code when run. This is especially useful for capturing content knowledge (e.g., expert knowledge or heuristics).

Tcl is also the reason why you may see some code that uses sp with braces, and some that uses sp with quotes. Without Tcl, it makes no difference. With Tcl, tells Tcl to either treat the text as literal text (braces) or to perform variable substitutions and execute embedded procedure calls (quotes). Since it makes no difference, and those who use Tcl always want substitutions and procedure execution, it is common for those who use Tcl to always use quotes, even for code that has no Tcl.

Functionally, Tcl code is run by Soar at load time. When the rules are sourced, all the procedures are run and variables are substituted, resulting in pure Soar code that is actually loaded. This means that if you print a loaded rule, it will not necessarily look like the original rule that had Tcl, since all of the Tcl will have been expanded.

JSoar and CSoar support Tcl in slightly different ways. Both load without Tcl support by default. To enable Tcl support in JSoar, you need to give the java executable the "-Djsoar.agent.interpreter=tcl" flag. Alternatively, you can set the system parameter in the program before the agent is created. Tcl cannot be turned off. In CSoar, you use the "cli tcl on" command. This should be the first thing you do in a new agent; turning Tcl on in the middle of an agent may have unpredictable results, and turning Tcl off is not currently supported.

To learn more about Tcl, you can find a number of resources online. Here are a couple:

• A Tcl tutorial: http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html
• A site with lots of resources: http://wiki.tcl.tk/
• A Tcl Style Guide

Thoughout this guide, I will occasionally use Tcl. Sometimes I will assume that this utility code is loaded. It's generally useful code for those using Tcl in Soar.

Finally, you might be wondering if you can add similar support for your favorite language (e.g., maybe you want to use clojure to generate Soar code). The answer is sort of. Tcl and Soar work together well because Soar's syntax has been designed to be compatible with Tcl. If you wanted to use some other language, you might have to either modify Soar's syntax to be compatible with that language, or else completely wrap Soar's syntax, so that you wouldn't be writing pure Soar at all. There has been a couple projects to try to create higher-level languages that would be easier to code in than Soar, but it turns out to be very difficult to create a new language. But maybe a direct mapping of syntax would be more achievable if someone wants to try.

NGS and Michigan style goals

There are multiple ways to represent goals in Soar. One common approach, the Michigan style, takes advantage of Soar's architecture (i.e., impasses and automatic subgoaling). Indeed, this is what Soar is designed to do. Another approach, the New Goal System or NGS, can make concurrent goals easier. The New Goal System or NGS is a set of Tcl macros and supporting Soar code. In recent years, there have been some attempts to combine the approaches, or to better characterize when each is appropriate.

This guide does not take a stance on which approach is "better". Almost everything discussed can be used in either approach, and throughout we give examples in both. In those cases where something is specific to one approach or the other, it is noted.

This guide does not attempt to give an NGS tutorial; NGS comes with documentation and an example agent if you want to learn more. Most of the examples in this guide that use NGS should be pretty understandable to those who aren't familiar with it (and most of those examples are easily translated to Michigan style).

Editors

Soar has several mediocre editors. This is because different subgroups within the Soar community have different needs and resources. I'll briefly describe the editors I know of, and what their pros and cons are:

• VisualSoar: This is no longer supported and should not be used. VisualSoar was originally developed by John Laird's UM group but is now outdated.  It is only include it here because the Soar tutorial has not yet been updated to use a different editor.
• Soar Editor: This is an Eclipse plugin that forked off of Soar IDE (see below). It retains a lot of the feel of VisualSoar, but takes advantage of Eclipse's text editing and other capabilities. It doesn't properly support Tcl, and at the moment is not being actively maintained (although it hasn't been so long as to be considered abandoned). 
• Soar IDE: This is an Eclipse plugin developed by SoarTech whose primary purpose was to create a more robust editing experience than VisualSoar, and also support Tcl. It includes a number of other features that some people like, such as an automated datamap. It does not (yet) contain an authorable datamap. For many years, Soar IDE was not maintained, but recently the code has been dusted off and updates have restarted. The plan is to eventually incorporate all desired features from Soar Editor, so that this becomes the single standard editor. Eventually, debugging support should also be included, so this becomes an IDE in more than just name.
• Any number of custom syntax highlighters for various editors, including emacs, vim, and ultraedit. You can find some of these here. If you are interested in others, you might ask on soar-group to see what people might have laying around. Creating your own is also possible, of course. The Soar manual has an appendix with a grammar you can use to get started, but as it's goal is to briefly give the basic idea and not specify a complete grammar, it is far from perfect. You'll need to spend some time improving it as you find it making mistakes in your code.

Debuggers

Across JSoar and CSoar there are several debuggers.

• JSoar's debugger is Java-based and built-in. Read about it here.
• CSoar's Java debugger is used in the Soar tutorials. It also supports connecting to Soar agents over the network.
• CSoar also has several command line debuggers, including cli, mcli, and testcli.
  • cli: a very simple command line debugger. Not the simplest possible one, but close. A good example to look at if you want to build one into your own project.
  • mcli: like cli, but supports multiple agents.
  • testcli: a more complex (multi-threaded) debugger, supporting things like typing commands while Soar is running (really useful for stopping an agent), and on some platforms using the arrow keys to get previous commands.
• JSoar has an example of a web-based debugger. Read about it here.

Because Soar is a command line language, building simple command line debuggers is actually really easy. Indeed, any project that cannot use one of the above debuggers should really just throw in a simple command line so you have something. Of course, creating more sophisticated command line debuggers with the features you might expect from a nice tool is more work. Looking at CSoar's various command line debuggers will give you some idea of what's involved.

Other resources

The Soar homepage: http://soar.eecs.umich.edu/

The JSoar homepage: http://soartech.github.io/jsoar/

Over the years, the Soar community has generated a lot of stuff. Some of it is available or linked to here: http://soar.eecs.umich.edu/Downloads

• Browse through the download categories on the side

I really recommend SoarUnit if you want a standard way to test your code (it's really great for test-driven development, too):

• https://github.com/soartech/jsoar/wiki/SoarUnit
• A Soar Workshop talk in PDF format
• The same talk in Powerpoint format

You may also be interested in soardoc, which generates HTML documentation from Soar code, much like javadoc.

If you're interested in building Soar, integrating with Soar via SML, or other miscellaneous Soar resources (some outdated), there is information here: http://soar.eecs.umich.edu/articles/articles

• See the categories on the side

Some publications are available here: http://soar.eecs.umich.edu/publications

Soar books: these are not programming guides or tutorials, but more about the underlying theory and future directions if you are interested in that sort of thing:

• Unified Theories of Cognition (Allen Newell, 1990)
• The Soar Cognitive Architecture (John Laird, 2012)