The main drawback to this whole situation was that Tcl didn’t always lend itself to friendly embedding in other programs. It had funny rules about threads and, if Tk was involved, demanded to have its message queue pumped. And, of course, very few people get to know Tcl enough to like it :)

On the other hand, you could create macros for repetitive Soar structures, define new RHS functions, manipulate I/O. In short, you had the power of a full programming language mixed in with your Soar code.

With Soar 8.6 Soar’s tight integration with Tcl was broken, replaced by SML and a stricter command interpreter. It still looked like Tcl commands, but there were no Tcl control structures, variables, etc. Way it goes. When I initially started work on JSoar, I needed to quickly bootstrap a command interpreter so I could load existing code into the kernel. I turned to Tcl, in the form of Jacl, a Java implementation of Tcl. It saved a lot of time and, since Soar’s syntax was still basically Tcl, no one would really notice.

Of course, as I mentioned, no one wants Tcl, so over the last couple weeks, I’ve added a new scripting layer to JSoar. This time, I’m taking advantage of the Java Scripting API, JSR-223. This allows any scripting language with a JSR-223 implementation to be pretty seamlessly accessed from Java (and vice versa). With this new capability, it’s now possible to automate Soar agents, implement simple agent environments, and extend SoarUnit testing to include I/O, all from within a Soar source file. All with a variety of languages including Ruby, JavaScript, Python, Clojure, Groovy, etc.

A scripting engine (a language implementation) is invoked with the script command:

script javascript {
   soar.onInput(function(e) {
      soar.wmes.add("my-input", "hello");
   });
   soar.onOutputCommand("say", function(e) {
      soar.print("The agent says: " + e.greeting);
   });
}

This little bit of code sets up an input phase callback and creates a WME on the agen’ts input-link. It also handles an output command called “say”. The equivalent Java code would be … more ceremonious. Not to mention setting up a new project, compiling, etc, etc is a major hassle.

As an example, I’ve implemented a simple waterjugs environment in JavaScript, Ruby, and Python. Here are some things you can do:

• Generate input
• Handle output commands
• Auto-convert hashes (JavaScript objects, Python dicts, or Ruby hashes) to input structures
• Install new RHS functions
• Add new commands
• and on and on

Also, with maybe a little more work, I might have a pretty good story for dealing with I/O in SoarUnit tests. Stay tuned.

More detailed info on JSoar scripting support can be found on the JSoar wiki.

(For more complete docs and examples, see the SoarUnit wiki page, and the Bebot source code. There’s a snapshot (20100801) of JSoar with the latest SoarUnit on the JSoar downloads page.)

SoarUnit UI

The one advantage that this effort may have over previous Soar testing attempts is that I developed it at the same time that I was actively working on Soar code. When I first started working on Soar99 and Bebot, my testing strategy was very ad hoc. I had a big Soar file that looks something like this:

   source "test1.soar"
   run
   excise --all

   source "test2.soar"
   run
   excise --all

   ... and so on ...

To run my tests, I’d just source the file and eyeball the trace for errors, which, if you’re familiar with Soar, you’ll know are usually pretty easy to spot. Of course, there were some drawbacks to this approach:

• Manually checking for success/failure is painful. The “green bar” is so much nicer.
• To add a single new test, I had to add another three lines to  my “master test” file.
• There was no way to put more than one test in a file, necessitating either a bunch of duplicate code, or some confusing trickery with the source command.
• When a test failed, I had to manually source it to debug.

Basically, all the same problems you get when manually testing code in any other language.

So, with 30 or so ad hoc tests already built, I started working on SoarUnit. Here’s the basic structure of a testcase file:

setup {
   ... Code run before every test. Here you can source code under test,
       setup test data, propose initialization opreators, etc ...
}

test "name of test" {
   ... Code for an individual test. Here you put any code
       you need for the test. When the test's success condition's
       have been detected, a rule should call the (pass) RHS function.
       Similarly, there's a (fail) RHS function for detecting failures ...
}

... More tests ...

Nice and simple.

I think the existing tests were key to how well development has gone. Every previous attempt I’ve made for testing Soar code has been based on imagining how someone might use such a framework, without any real-world requirements to build from. Although I’ve only been working on it a little more than a week, SoarUnit already has:

• Test case discovery by file name pattern
• Multiple tests per file
• Setup blocks to handle code shared by multiple tests
• A graphical interface similar to Eclipse’s JUnit view (see below)
• Single-click debugging from the user interface
• Support for both JSoar and CSoar 9.3.0 (CSoar requires that a SOAR_HOME environment variable be set so it can find native libraries and stuff)
• Basic code coverage reporting

Best of all, I’ve used it a lot on Bebot and Soar99 and it’s honestly really nice. I did a major refactoring, basically renaming all of the major data structures and operators in the library, and it was a breeze. I guess that’s the point of having tests…

What’s Next?

I’m going to keep working on SoarUnit to support my own Soar development. There are still some obvious holes and open questions.

One area that’s always plagued talk of testing Soar code is I/O. How do you test an agent independent of the environment it will run in. I’m currently of the mind that, like unit testing in every other language, this is where mocking comes in. With a few rules, an agent can easily simulate static structures on the input-link to driver tests. If things get too complicated, one option is simple integration with soar2soar, where for each test, a helper agent would be created to simulate the environment. There are other options as well (plugins, external processes, etc), but none of them maintains the simplicity I want for SoarUnit. For every configuration parameter, you lose a user and with Soar there aren’t that many to start with.

The other open question is whether SoarUnit is effective for testing idiomatic Soar code. Soar has very little encapsulation or modularity which can make it difficult to isolate code for testing. The problems I’m solving with Bebot are very procedural, so they’re easy to test, but I’m not sure that’s true for most Soar code. I’d like to work through creating tests for some of the Soar tutorial problems and see how it goes.

Unfortunately, writing open source documentation isn’t as fun as coding or as gratifying as blog traffic* so there’s a pretty good chance the open source knowledge diaspora will continue. Important, headache preventing, technical information will remain in change logs, mailing lists, and random blog posts while user guides and other documentation will be ignored or buried**.

Stack Overflow is helping a bit, but it would be nice if some of the best answers there were pulled back into (or at least linked to from) the how-tos and getting started guides of the projects they concern.

I, for my part, am going to start writing this stuff down. Where it belongs.

* yes, I recognize the irony here.
** many open source projects could do a hell of a lot better job at making documentation easier to find.

function! s:app_ruby_shell_command(cmd) dict abort
  if self.path() =~ '://'
    return "jruby.bat ".a:cmd
  else
    return "jruby.bat -C ".s:rquote(self.path())." -S ".a:cmd
  endif
endfunction

Basically, just change “ruby” to “jruby.bat” and add the -S parameter.

The -S flag is important. Otherwise, it seems JRuby’s implementation of the -C flag is a little buggy. For example, almost any script/ command will fail:

>jruby -C c:\path\to\rails\app script/generate
C:/Program Files/jruby-1.3.1/bin/../lib/ruby/1.8/pathname.rb:711:in `relative_path_from':
        different prefix: "C:/" and "C:\\path/to/rails/app" (ArgumentError)
        from C:/Program Files/jruby-1.3.1/lib/ruby/gems/1.8/gems/rails-2.3.3/lib/rails_generator/lookup.rb:110:in
        `use_component_sources!'

Everything seems to be working well now. Yay.

So far P27 gave me the most trouble because I refused to use my brain. Figured it out on a nice long walk with the family. P28 was a pain because I was figuring out how Ruby blocks/procs work. Here’s the code.

p.s. an immutable list, like in Scala (or Lisp, etc, etc), with pattern matching of course, would be handy in Ruby. I wonder if one exists…

1) No string join method

How many times have I written this?

2) No way to set additional JVM parameters in manifest of executable jar

It’s really convenient to just double-click a jar … until you need to set your heap size or something and you have to go crawling back to a shell script.

3) java.net.URL constructor throws checked MalformedURLException rather than unchecked IllegalArgumentException

Seriously, what is so special about this exception?

4) java.io.File has no getExtension() method

Same as join() above.

5) No immutable collections.  Collections.unmodifiableList() and friends don’t count

6) java.io.File.delete() silently does nothing if you try to delete a non-empty directory

It’s even more irritating to write deleteFolder() than join() and getExtension().

7) java.util.Random has a setSeed() method, but no getSeed() method

8) java.util.logging is built-in and incredibly lame

They sucked every ounce of the joy out of log4j.

9) JTree selection behavior gives me a headache every time I have to deal with it

10) No method to just read an entire InputStream or Reader into a byte array or string

Same as join() above.

Bonus) No method to copy a file!

First, for better or worse, I’m working in NetBeans.  The Maven support is passable, but out of the box, the error reporting leaves a lot to be desired. In particular, detailed error reporting must be enabled. Otherwise, when there’s an error in your pom.xml file, you’ll get a nice <Badly formed Maven project> error with no other explanation. To enable error reporting go to Tools->Options->Miscellaneous->Maven, and check “Produce Exception Error Messages”. That will make your life easier. Now, about wsimport…

The obvious way to import multiple WSDLs is to include multiple executions in the jaxws-maven-plugin section of pom.xml. In fact, this is even the right way to do it… but if you just take your single-WSDL example, stolen from some tutorial somewhere, and copy it, you’ll end up with a couple of problems. First, when multiple execution are present, they must each be given a unique id, using of all things, the <id> tag.  This wasn’t that tough to figure out once I turned on error reporting as described above.

The second issue was more problematic and, in my opinion, probably a bug in the plugin. Each execution includes a “staleFile” which is used to manage dependencies, i.e. correctly recompiling WSDL when it changes. However, it happens that when multiple executions are present they use the same staleFile.  This means that the import of the second WSDL always thinks it’s up to date and thus never runs.  After a bunch of googling, I managed to find a solution in this bug report. So, the solution is to manually set a staleFile for each WSDL. Here’s the resulting <plugin> block from pom.xml:

<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>jaxws-maven-plugin</artifactId>
   <executions>
      <execution>
         <id>FirstWsdl</id>
         <goals>
            <goal>wsimport</goal>
         </goals>
         <configuration>
            <wsdlLocation>http://localhost:8080/FirstWsdl?wsdl</wsdlLocation>
            <wsdlFiles>
            <wsdlFile>path/to/FirstWsdl.wsdl</wsdlFile>
            </wsdlFiles>
            <packageName>com.example.first</packageName>
            <!-- Without this, multiple WSDLs won't be processed :( -->
            <staleFile>${project.build.directory}/jaxws/stale/wsdl.FirstWsdl.done</staleFile>
         </configuration>
      </execution>
      <execution>
         <id>SecondWsdl</id>
         <goals>
            <goal>wsimport</goal>
         </goals>
         <configuration>
            <wsdlLocation>http://localhost:8080/SecondWsdl?wsdl</wsdlLocation>
            <wsdlFiles>
            <wsdlFile>path/to/SecondWsdl.wsdl</wsdlFile>
            </wsdlFiles>
            <packageName>com.example.second</packageName>
            <!-- Without this, multiple WSDLs won't be processed :( -->
            <staleFile>${project.build.directory}/jaxws/stale/wsdl.SecondWsdl.done</staleFile>
         </configuration>
      </execution>
   </executions>
</plugin>

That’s it. Cheers.

The editing is pretty bad. I came across a number of typos which make me wonder if anyone actually read it before going to print. On top of that, this is some seriously sloppy technical writing (kind of like this blog). New or alternative terms are introduced without note, examples are only explained by cryptic, embedded comments, and seemingly complex concepts are given no examples at all.

The one statement that stuck out for me was on page 5 where the author describes the is-a relationship:

The relationship between a class and its superclass is interesting and important; it is usually described as the is-a relationship, because a Square “is a” Rectangle, and a Rectangle “is a” Polygon, and so on.

Ummm, please tell me that your first example of a class hierarchy isn’t one that if not just wrong is at least highly controversial.  You couldn’t have started with Person and Employee?

Hal Fulton calls this chapter “our review of object-oriented programming and our whirlwind tour of the Ruby language” so besides the typos and sloppiness, I’ll give him a break. That’s really a lot to jam into one chapter of a book whose intended audience is assumed to basically know all that stuff.

It’s like a man page. It all makes perfect sense if you already know it.

So as my hesitation grew, I reached section 1.5, “Training Your Intuition: Things to Remember”. This is where, in my opinion, the author turns everything around. This is one of my favorite sections of a technical book I’ve read in a long time. It’s basically a somewhat random laundry list of Ruby idioms, gotchas, and nuggets of general wisdom. It reminds me of the best stuff you find in a FAQ when learning a new language. It reminds me of the lists I write for colleagues when I have to bring them up to speed on a new technology. It reminds me of how I felt the first time I read Effective C++ when I was too young and foolish to recognize that for the oxymoron it was.  It’s all the stuff that you wish that a language manual would come out and tell you right away, but is completely missing or at least hidden between simplistic examples.

Great stuff. Anyway, at least he ended on a high note. Flipping through the rest of the recipe-style chapters of the book, I’m pretty confident I’ll find it invaluable specifically because it continues that laundry list style that for some reason appeals to me so much.

p.s. my “learning scala” project was a simple rules engine. For Ruby, I’m planning on a tcl interpreter. Hopefully, I can do it in less than 550 lines. Combining the speed of Ruby with the speed and expressiveness of Tcl … good times.

Note that this code makes use of the scala.tools.nsc package which is not part of the standard Scala library. Thus, it may change in future versions of Scala. Also note that after the fact, I was able to track down two partial JSR-223 implementations here and here. It’s comforting that I ended up in basically the same place.

The example given in the bug tracker works, but it’s very simple and there are two things it doesn’t do. First, it prints all its output to stdout, including error information. Second, it doesn’t show how to retrieve results from executing scripts. That is, code goes in, but nothing comes out. These are both solved pretty easily.  In the first case, we simply supply our own PrintWriter when instantiating the internal Scala interpreter:

  private val writer = new java.io.StringWriter()
  private val interpreter = new ScalaInterpreter(new Settings(),
                                                 new PrintWriter(writer));

  ...

  def exec(code : String) {
    // Clear the previous output buffer
    writer.getBuffer.setLength(0)

    // Execute the code and catch the result
    val ir = interpreter.interpret(code);

    // Return value or throw an exception based on result
    ir match {
      case Success => ()
      case Error => throw new ScriptException("error in: '" +
                                              code + "'\n" + writer toString)
      case Incomplete => throw new ScriptException("incomplete in :'" +
                                                   code + "'\n" + writer toString)
    }
  }

For the second issue, returning results, I had to think a little longer, probably longer than necessary. scala.tools.nsc.Interpreter doesn’t return anything besides Success, Error, or Incomplete as seen above. But, you can pass objects in, so I ended up creating a container object to hold the result:

class ResultHolder(var value : Any)

  ...

  def eval(code : String) : Any = {
    // Clear the previous output buffer
    writer.getBuffer.setLength(0)

    // Create an object to hold the result and bind in the interpreter
    val holder = new ResultHolder(null)
    bind("$result__", holder);

    // Execute the code and catch the result
    val ir = interpreter.interpret("$result__.value = " + code);

    // Return value or throw an exception based on result
    ir match {
      case Success => holder.value
      case Error => throw new ScriptException("error in: '" +
                                              code + "'\n" + writer toString)
      case Incomplete => throw new ScriptException("incomplete in :'" +
                                                   code + "'\n" + writer toString)
    }
  }

As you can see, I ended up with two separate routines. exec executes a Scala statement, ignoring its return value. This is useful for imports, class declarations, anything that does not evaluate to a value.  eval executes a Scala statement, catches the result and returns it.

Anyway, that’s about it. It seems that full JSR-223 support is in the plan for Scala. Until then, what I have here works for me and it was a good learning experience. Here’s the full source for my solution.

Anyway, my exercise for Scala’s XML support was adding an XML encoding of rules to rooscaloo. My plan is to eventually write a parser with parser combinators, but that’s not until chapter 31.

Overall, Scala’s XML support is a dream compared to anything I’ve done in Java before. I began by creating some case classes for my AST:

  case class RuleAST(name : String,
                     fireCode : String, unfireCode : String,
                     conditions : ConditionAST*)

  case class ConditionAST

  case class ObjectConditionAST(typeName : String,
                                binding : String,
                                testCode : String) extends ConditionAST

  case class NotAST(children : ConditionAST*) extends ConditionAST

really simple stuff.  Here’s what a rule looks like in XML:

    <rule name="bob-is-not-a-cat-lover">
      <if>
        <object type="Person" binding="p"> p.name == "bob" </object>
        <not>
            <object type="Cat" binding="c"> c.owner == p </object>
        </not>
      </if>
      <then>println("bob does not fancy cats")</then>
      <unfire>Tprintln("bob now owns a cat!")</unfire>
    </rule>

(I couldn’t think of a better name for rule retraction than unfire…)

and here’s the satisfyingly compact code to convert an XML node to a RuleAST object:

  def parseRule(node: scala.xml.Node) : RuleAST =
    RuleAST(node \ "@name" text,
            node \ "then" text,
            node \ "unfire" text,
            parseConditionList(node \ "if" \ "_") : _*)

  def parseConditionList(xml : scala.xml.NodeSeq) : Seq[ConditionAST] =
    for(e <- xml)
      yield e match {
        case <object>{ _* }</object> => parseObjectCondition(e)
        case <not>{ _* }</not> => parseNot(e)
      }

  def parseObjectCondition(xml : scala.xml.Node) : ObjectConditionAST =
    ObjectConditionAST(xml \ "@type" text, xml \ "@binding" text, xml.text)

  def parseNot(xml : scala.xml.Node) : NotAST =
    NotAST(parseConditionList(xml \ "_") : _*)

This could actually be much more compact but I chose to break it up into methods so I could test each construct individually. Still, I’m fairly certain there’s an even better way to do this, but this represents 45 minutes of work including unit tests, so I’m still pretty happy. One thing I discovered that wasn’t covered in the book was the use of the “_” wildcard to get all sub-elements of a node. For example we can see above that I use:

   node \ "if" \ "_"

to get the list of all child elements of the <if> node.

The match statement in parseConditionList is a little irritating to me and I feel like there’s probably a better way to do that.

Just like the book, I’ve obviously only started to scratch the surface of  Scala’s XML support. Since I also just read the chapter on extractors, it seems like it might be interesting to define extractors to automatically convert XML to an AST. Of course, there’s also XPath, transforms, etc.

Maybe tomorrow night. It’s time to sleep.

p.s. here are some more Scala XML resources I’ve found useful:

• A Tour of Scala …
• A nice introduction by Michael Galpin
• The Scala XML “book”