16. The Jess Function List

In this chapter, every Jess language function shipped with Jess version 7 is described. Previous versions of Jess had a notion of "optional functions," but Jess 7 does not: all of the functions described here are always available.

You may also like to look at a list of functions grouped by category or sorted by name.
Note: many functions documented as requiring a specific minimum number of arguments will actually return sensible results with fewer; for example, the + function will return the value of a single argument as its result. This behavior is to be regarded as undocumented and unsupported. In addition, all functions documented as requiring a specific number of arguments will not report an error if invoked with more than that number; extra arguments are simply ignored.

16.1. (- <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the first argument minus all subsequent arguments. The return value is an INTEGER or LONG unless any of the arguments are FLOAT, in which case it is a FLOAT.

16.2. (-- <variable>)
Arguments:
A variable
Returns:
Number
Description:
Subtracts one from the variable (which should contain a numeric value,) sets the variable to the new value, and returns the new value. Throws an exception if the argument is not a variable containing a numeric type. The type of the variable is preserved.

16.3. (/ <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the first argument divided by all subsequent arguments. The return value is a FLOAT.

16.4. (* <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the products of its arguments. The return value is an INTEGER or LONG unless any of the arguments are FLOAT, in which case it is a FLOAT.

16.5. (** <numeric-expression> <numeric-expression>)
Arguments:
Two numeric expressions
Returns:
Number
Description:
Raises its first argument to the power of its second argument (using Java's Math.pow() function). Note: the return value may be NaN (not a number); see the Java API documentation for details.

16.6. (+ <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the sum of its arguments. The return value is an INTEGER or LONG unless any of the arguments are FLOAT, in which case it is a FLOAT.

16.7. (++ <variable>)
Arguments:
A variable
Returns:
Number
Description:
Adds one to the variable (which should contain a numeric value,) sets the variable to the new value, and returns the new value. Throws an exception if the argument is not a variable containing a numeric type. The type of the variable is preserved.

16.8. (< <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if each argument is less than the argument following it; otherwise, returns FALSE. The definition of "less than" varies depending on the types being compared.

16.9. (<= <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is less than or equal to the value of the argument following it; otherwise, returns FALSE. The definition of "less than or equal to" depends on the objects being compared.

16.10. (<> <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if the value of the first argument is not equal in value to all subsequent arguments; otherwise returns FALSE. The definition of "not equal" depends on the objects being compared.

16.11. (= <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if the value of the first argument is equal in value to all subsequent arguments; otherwise, returns FALSE. The integer 2 and the float 2.0 are =, but not eq.

16.12. (> <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is greater than that of the argument following it; otherwise, returns FALSE. The definition of "greater than" depends on the objects being compared

16.13. (>= <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions or Comparable objects
Returns:
Boolean
Description:
Returns TRUE if the value of each argument is greater than or equal to that of the argument following it; otherwise, returns FALSE. The definition of "greater than or equal to" depends on the objects being compared.

16.14. (abs <numeric-expression>)
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the absolute value of its only argument.

16.15. (add <Java object>)
Arguments:
A Java object
Returns:
nil
Description:
Adds the given object to working memory. Creates a "shadow fact" representing the given Java object, using the template whose name is the same as the given object's class, without the package prefix. If this template doesn't exist, it is created. Equivalent to calling 
(definstance <classname> <Java object> auto)
See the description of the definstance function for more information.

16.16. (agenda [<module-name> | *])
Arguments:
Optionally, a module name or the symbol "*"
Returns:
NIL
Description:
Displays a list of rule activations to the WSTDOUT router. If no argument is specified, the activations in the current module (not the focus module) are displayed. If a module name is specified, only the activations in that module are displayed. If "*" is specified, then all activations are displayed.

16.17. (and <expression>+)
Arguments:
One or more expressions
Returns:
Boolean
Description:
Returns TRUE if all arguments evaluate to a non-FALSE value; otherwise, returns FALSE.

16.18. (apply <expression>+)
Arguments:
A function name or lambda followed by zero or more expressions
Returns:
An expression
Description:
Returns the result of calling the first argument, either the name of a Jess function or a lambda expression, on all the remaining arguments. The strength of this method lies in the fact that you can call a function whose name, for instance, is in a Jess variable.

16.19. (asc <string>)
Arguments:
Any string or symbol
Returns:
Integer
Description:
Returns the Unicode value of the first character of the argument, as an RU.INTEGER.

16.20. (as-list <java-object>)
Arguments:
A Java object (must be an array)
Returns:
A list
Description:
Converts the given Java array into a Jess list. This happens automatically for arrays returned by functions declared to return an array, but you can easily fetch an array from a Java method that returns Object, and in this case this function is useful.

16.21. (assert <fact>+)
Arguments:
One or more facts
Returns:
A Fact, or FALSE
Description:

Adds all the facts to the working memory; returns the last fact asserted or FALSE if no facts were successfully asserted (for example, if all facts given are duplicates of existing facts.) A jess.JessEvent of type JessEvent.FACT will be sent if the event mask is set appropriately.

It is important to remember that all pattern-matching happens during calls to assert, retract, modify, and related functions. Pattern-matching happens whether the engine is running or not.

Example:

Jess> (reset)
TRUE

Jess> (assert (testing 1 2 3))
<Fact-1>

16.22. (assert-string <string-expression>)
Arguments:
One string representing a fact
Returns:
A Fact, or FALSE
Description:

Converts a string into a fact and asserts it. Attempts to parse string as a fact, and if successful, returns the value returned by assert with the same fact. Note that the string must contain the fact's enclosing parentheses.

Example:

Jess> (reset)
TRUE

Jess> (assert-string "(testing 1 2 3)")
<Fact-1>

16.23. (bag <bag-command> <bag-arguments>+)
Arguments:
A symbol (a sub-command) and one or more additional arguments
Returns:
(Varies)
Description:
The bag command lets you manipulate Java hashtables from Jess. The net result is that you can create any number of associative arrays or property lists. Each such array or list has a name by which it can be looked up. The lists can contain other lists as properties, or any other Jess data type.

The bag command does different things based on its first argument. It's really seven commands in one:
  • create accepts a String, the name of a new Bag to be created. The bag object itself is returned. For example: 
    Jess> (bag create my-bag)
  • delete accepts the name of an existing bag, and deletes it from the list of bags.
  • find accepts the name of a bag, and returns the corresponding bag object, if one exists, or nil.
  • list returns a list of the names of all the existing bags.
  • set accepts as arguments a bag, a String property name, and any Jess value as its three arguments. The named property of the given bag is set to the value, and the value is returned.
  • get accepts as arguments a bag and a String property name. The named property is retrieved and returned, or nil if there is no such property. For example: 
    Jess> (defglobal ?*bag* = 0)
    TRUE

    Jess> (bind ?*bag* (bag create my-bag))
    <Java-Object:java.util.Hashtable>

    Jess> (bag set ?*bag* my-prop 3.0)
    3.0

    Jess> (bag get ?*bag* my-prop)
    3.0
  • props accepts a bag as the single argument and returns a list of the names of all the properties of that bag.

16.24. (batch <filename> [<charset>])
Arguments:
One string representing the name of a file, and optionally a character set name
Returns:
(Varies)
Description:

Attempts to parse and evaluate the given file as Jess code. If successful, returns the return value of the last expression in the file.

Note: the argument must follow Jess' rules for valid strings. On UNIX systems, this presents no particular problems, but Win32 filenames may need special treatment. In particular: pathnames should use either '\\' (double backslash) or '/' (forward slash) instead of '\' (single backslash) as directory separators.

In an applet, batch will try to find the file relative to the applet's document base. In any program, if the file is not found, the name is then passed to ClassLoader.getSystemResourceAsStream(). This allows files along the class path, including files in JARs, to be batched.

If you specify a character set name as the optional second argument, Jess will assume the file is written using that character set.

16.25. (bind <variable> <expression>)
Arguments:
A variable name and any value
Returns:
(Varies)
Description:

Binds a variable to a new value. Assigns the given value to the given variable, creating the variable if necessary. Returns the given value.

Example:

Jess> (bind ?x 3)
3

Jess> ?x
3

If the variable name contains a period, like ?x.y, then this function will attempt to modify slot y of a fact in variable ?x to the given value.

16.26. (bit-and <integer-expression>+)
Arguments:
One or more integer expressions
Returns:
int
Description:
Performs the bitwise AND of the arguments. (bit-and 7 4) is 4, and is equivalent to the Java 7 & 4.

16.27. (bit-not <integer-expression>)
Arguments:
One integer expression
Returns:
int
Description:
Performs the bitwise NOT of the argument. (bit-not 0) is -1, and is equivalent to the Java ~0.

16.28. (bit-or <integer-expression>+)
Arguments:
One or more integer expressions
Returns:
int
Description:
Performs the bitwise OR of the arguments. (bit-or 2 4) is 6, and is equivalent to the Java 2 | 4.

16.29. (bload <filename>)
Arguments:
One string representing the name of a file
Returns:
TRUE
Description:

The argument is the path to a file previously produced by the bsave command. The file is decompressed and deserialized to restore the state of the current Rete object. I/O routers are not restored from the file; they retain their previous state. Furthermore, JessListeners are not restored from the file; again, they are retained from their state prior to the bload.

To decode the dump file, this function decompresses the data using java.util.zip.GZIPInputStream and sends the result to the jess.Rete.bload(java.io.InputStream) method. Therefore, this function cannot be directly read data saved by jess.Rete.bsave(java.io.OutputStream) method because the decompression step will fail.

16.30. (break)
Arguments:
None
Returns:
N/A
Description:
Immediately exit any enclosing loop or control scope. Can be used inside of for, while, and foreach loops, as well as within the body of a deffunction or the right hand side of a defrule. If called anywhere else, will throw an exception.

16.31. (bsave <filename>)
Arguments:
One string representing the name of a file
Returns:
TRUE
Description:

Dumps the engine in which it is called to the given filename argument in a format that can be read using bload. Any input/output streams and event listeners are not saved during the serialization process.

To produce the dump file, this function calls the jess.Rete.bsave(java.io.OutputStream) method and compresses the data using java.util.zip.GZIPOutputStream. Therefore, data saved by this method cannot be directly read by the jess.Rete.bload(java.io.InputStream) method without first decompressing it.

16.32. (build <string-expression>)
Arguments:
One string representing some Jess code
Returns:
(Varies)
Description:
Evaluates a string as though it were entered at the command prompt. Only allows constructs to be evaluated. Attempts to parse and evaluate the given string as Jess code. If successful, returns the return value of the last expression in the string. This is typically used to define rules from Jess code. For instance:

(build "(defrule foo (foo) => (bar))")

Note: The string must consist of one single construct; multiple constructs can be built using multiple calls to build.

16.33. ([call] <java object> | <class-name> <method-name> <argument>*)
Arguments:
A java object or class name, optionally a method or field name, and any number of additional arguments
Returns:
(Varies)
Description:
Calls a Java method on the given object, a static method of the class named by the first argument, invokes a lambda, or returns the value of a Java field in the object. Unless the first argument is a lambda, the second argument is the name of the method or field. All subsequent arguments, if any, are passed to the lambda or method. When calling Java methods, arguments are promoted and overloaded methods selected precisely as for new. The return value is converted to a suitable Jess value before being returned. Array return values are converted to lists.

The functor call may be omitted unless the method being called is a Java static method. The following two method calls are equivalent: 
Jess> (bind ?list (new java.util.ArrayList))
Jess> ;; These are legal and equivalent
(call ?list add "Foo")
(?list add "Foo")

Note that call can even be omitted if the object comes from the return value of another function call:

Jess> ;; This is legal
((new java.util.ArrayList 10) add "Foo")

If the first argument is a Java object, and the second a symbol, and there are no other arguments, and the object does not have a no-argument method by the given name, then Jess will attempt to return the value of a field by that name in the object, if one exists. As with method calls, the "call" functor can be omitted. So, for example, 

Jess> (bind ?dim (new java.awt.Dimension 10 20))
Jess> ;; These are legal and equivalent
(get-member ?dim width)
(?dim width)

16.34. (call-on-engine <Java object> <jess-code>)
Arguments:
an jess.Rete object, and an executable snippet of Jess code
Returns:
(Varies)
Description:
Executes some Jess code in the context of the given Rete object. This is a nice way to send messages between multiple Rete engines in one process. Note that the current variable context is used to evaluate the code, so (for instance) all defglobal values will be from the calling engine, not the target.

16.35. (clear)
Arguments:
None
Returns:
TRUE
Description:
Clears Jess. Deletes all rules, deffacts, defglobals, templates, facts, activations, and so forth. Java Userfunctions are not deleted.

16.36. (clear-focus-stack)
Arguments:
None
Returns:
nil
Description:
Removes all modules from the focus stack.

16.37. (clear-storage)
Arguments:
None
Returns:
TRUE
Description:
Clears the hashtable used by store and fetch.

16.38. (close <router-identifier>*)
Arguments:
One or more router identifiers (symbols)
Returns:
TRUE
Description:
Closes any I/O routers associated with the given name by calling close() on the underlying stream, then removes the routers. Any I/O errors are ignored. Any subsequent attempt to use a closed router will report bad router. See open.

16.39. (complement$ <list-expression> <list-expression>)
Arguments:
Two lists
Returns:
List
Description:
Returns a new list consisting of all elements of the second list not appearing in the first list.

16.40. (context)
Arguments:
None
Returns:
A jess.Context object
Description:
Returns the execution context (a jess.Context object) it is called in. This provides a way for deffunctions to get a handle to this useful class.

16.41. (continue)
Arguments:
None
Returns:
N/A
Description:
Immediately jump to the end of any enclosing loop and begin the next iteration of the loop. For "while" loops, the loop test will be executed next; for "for" loops, the increment function will be executed. Can be used inside of for, while, and foreach loops. If called anywhere else, will throw an exception.

16.42. (count-query-results <query-name> <expression>*)
Arguments:
A query name, and zero or more additional expressions
Returns:
INTEGER
Description:
Runs a query and returns a count of the matches. See the documentation for defquery for more details. Also see run-query for caveats concerning calling count-query-results on a rule RHS.

16.43. (create$ <expression>*)
Arguments:
Zero or more expressions
Returns:
List
Description:
Creates and returns a new list containing all the given arguments, in order. For each argument that is a list, the individual elements of the list are added to the new list; this function will not create nested lists (which are not meaningful in the Jess language.) Note: lists must be created explicitly using this function or others that return them. Lists cannot be directly parsed from Jess input.

16.44. (defadvice (before | after) (<function-name> | <list> | ALL ) <function-call>+)
Arguments:
The symbol before or the symbol after, followed by either one function name or a list of function names or the symbol ALL, followed by one or more function calls.
Returns:
(varies)
Description:
Lets you supply extra code to run before or after the named function(s) or all functions. If before is specified, the code will execute before the named function(s); the variable $?argv will hold the entire function call vector (function name and parameters) on entry to and exit from the code block. If after is specified, the function will be called before the code block is entered. When the block is entered, the variable ?retval will refer to the original function's return value.

Whether before or after is specified, if the code block explicitly calls return with a value, the returned value will appear to the caller to be the return value of the original function. For before advice, this means the original function will not be called in this case.

16.45. (defclass <template-name> <Java class name> [extends <template-name>])
Arguments:
Two or four symbols, as noted above
Returns:
The second argument
Description:

Defines a template with the given name, with slots based on the Java Beans properties found in the named class. If the optional extends clause is included, the second named template will become the parent of the new template. The common slots in the two templates will be in the same order, at the beginning of the new template. Rules defined to match instances of the parent template will also match instances of the new child template.

Note that anything you can do using the defclass function, you can also do with the deftemplate construct -- but deftemplate lets you do even more.

16.46. (definstance <template-name> <Java object> [static | dynamic | auto] )
Arguments:
A symbol, a Java object, and (optionally) one of the symbols static, dynamic, or auto
Returns:
The new shadow fact
Description:

Creates a "shadow fact" representing the given Java object, according to the named template. By default, or if the "dynamic" qualifier is specified, and if the object accepts java.beans.PropertyChangeListeners, then Jess will install a listener in the given object, so that Jess can keep the shadow fact updated if the object's properties change. If the object doesn't accept PropertyChangeListeners, or if the "static" qualifier is specified, then no listener will be registered and the shadow fact will not be updated when the object changes. The "auto" qualifier is equivalent to the default behavior.

Note that it is an error for a given Java object to be added to working memory more than once. The second and subsequent definstance calls for a given object will return a fact-id with value -1.

This function is a generalized form of add.

16.47. (delete$ <list-expression> <begin-integer-expression> <end-integer-expression>)
Arguments:
A list and two integer expressions
Returns:
List
Description:
Returns a new list like the original list but with the elements in the specified range removed. The first numeric expression is the 1-based index of the first element to remove; the second is the 1-based index of the last element to remove. It is an error to use any index value less than 1 or greater than the list length, or an end index less than the begin index.

16.48. (dependencies <fact-id>)
Arguments:
A Fact
Returns:
A list
Description:
Returns a list containing all the jess.Token objects that give logical support from the argument fact; if there are none this function returns an empty list. A jess.Token object is a list of facts; they're the same objects returned by run-query.

16.49. (dependents <fact-id>)
Arguments:
A Fact or fact-id
Returns:
A list
Description:
Returns a list containing all the jess.Fact objects that get logical support from the argument fact; if there are none this function returns an empty list.

16.50. (div <numeric-expression> <numeric-expression>+)
Arguments:
Two or more numeric expressions
Returns:
Number
Description:
Returns the first argument divided by all subsequent arguments using integer division. The return value is an INTEGER.

16.51. (do-backward-chaining <template-name>)
Arguments:
Name of a template (ordered or unordered)
Returns:
TRUE
Description:
Marks a template as being eligible for backwards chaining, as described in the text. If the template is unordered -- i.e., if it is explicitly defined with a (deftemplate) construct -- then it must be defined before calling do-backward-chaining. In addition, this function must be called before defining any rules which use the template.

16.52. (duplicate <fact-specifier> (<slot-name> <value>)+)
Arguments:
A fact and one or more two-element lists
Returns:
A fact
Description:

Makes a copy of the fact; the fact must be an unordered fact. Each list is taken as the name of a slot in this fact and a new value to assign to the slot. A new fact is asserted which is similar to the given fact but which has the specified slots replaced with new values. The new fact is returned. It is an error to call duplicate on a shadow fact.

As of Jess version 7, the slot names can be variables.

16.53. (e)
Arguments:
None
Returns:
Number
Description:
Returns the transcendental number e.

16.54. (engine)
Arguments:
None
Returns:
A jess.Rete object
Description:
Returns the jess.Rete object in which the function is called.

16.55. (eq <expression> <expression>+)
Arguments:
Two or more arbitrary arguments
Returns:
Boolean
Description:

Returns TRUE if the first argument is equal in type and value to all subsequent arguments. For strings, this means identical contents. Uses the Java Object.equals() function, so can be redefined. Note that the integer 2 and the floating-point number 2.0 are not eq, but they are eq* and =.

While often used in procedural code, this function is only rarely used during pattern matching. Direct matching is preferable.

16.56. (eq* <expression> <expression>+)
Arguments:
Two or more arbitrary arguments
Returns:
Boolean
Description:
Returns TRUE if the first argument is equivalent to all the others. Uses numeric equality for numeric types, unlike eq. Note that the integer 2 and the floating-point number 2.0 are not eq, but they are eq* and =.

16.57. (eval <lexeme-expression>)
Arguments:
One string containing a valid Jess expression
Returns:
(Varies)
Description:
Evaluates a string as though it were entered at a command prompt. Only allows functions to be evaluated. Evaluates the string as if entered at the command line and returns the result.

Note: The string must consist of one single function call; multiple calls can be evaluated using multiple calls to eval.

16.58. (evenp <expression>)
Arguments:
One numeric expression
Returns:
Boolean
Description:
Returns TRUE for even numbers; otherwise, returns FALSE. Results with non-integers may be unpredictable.

16.59. (exit)
Arguments:
None
Returns:
Nothing
Description:
Exits Jess and halts Java.

16.60. (exp <numeric-expression>)
Arguments:
One numeric expression
Returns:
Number
Description:
Raises the value e to the power of its only argument.

16.61. (explode$ <string-expression>)
Arguments:
One string
Returns:
List
Description:
Creates a list value from a string. Parses the string as if by a succession of read calls, then returns these individual values as the elements of a list.

16.62. (external-addressp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Deprecated. Use java-objectp instead.

16.63. (fact-id <integer>)
Arguments:
One number, a fact-id
Returns:
The given number as a jess.Fact
Description:
If the argument is the fact-id of an existing fact, returns that jess.Fact object; otherwise throws an exception. The lookup done by this function is slow. Be sure you really need to call this function. If you have a value that prints as "<Fact-1>", then it's already a Fact object.

16.64. (facts [<module name> | *])
Arguments:
Module name or * (optional)
Returns:
TRUE
Description:
Prints a list of all facts in working memory from the current module. If a module name is provided as an argument, facts from that module are listed instead. If the argument "*" is given, all facts from all modules are listed.

16.65. (fact-slot-value <fact-id> <slot-name>)
Arguments:
A jess.Fact and a slot name
Returns:
(varies)
Description:
Returns the value in the named slot of the fact. You should never need to call this on the left hand side of a rule; direct matching is always better. You should only occasionally need it in other code; again, directly matching the slots on the left hand side of a rule is better.

16.66. (fetch <string or symbol>)
Arguments:
One string or symbol
Returns:
(varies)
Description:
Retrieves and returns any value previously stored by the store function under the given name, or nil if there is none. Analogous to the fetch() member function of the Rete class. See the section on using store and fetch for details.

16.67. (filter <predicate function> <list>)
Arguments:
A function and a list
Returns:
A list
Description:
Calls the function on each item in the list; returns a list of all the results for which the function does not return FALSE. The function can either be the name of a Userfunction, or it can be a lambda expression.

16.68. (first$ <list-expression>)
Arguments:
One list
Returns:
List
Description:
Returns the first field of a list as a new 1-element list.

16.69. (float <numeric-expression>)
Arguments:
One numeric expression
Returns:
Floating-point number
Description:
Converts its only argument to a float.

16.70. (floatp <expression>)
Arguments:
One numeric expression
Returns:
Boolean
Description:
Returns TRUE for floats; otherwise, returns FALSE.

16.71. (focus <module-name>+)
Arguments:
One or more symbols, the names of modules
Returns:
The name of the previous focus module
Description:
Changes the focus module. The next time the engine runs, the first rule to fire will be from the first module listed (if any rules are activated in this module.) The previously active module is pushed down on the focus stack. If more than one module is listed, they are pushed onto the focus stack in order from right to left.

16.72. (for <initializer> <condition> <increment> <body expression>*)
Arguments:
Three or more expressions
Returns:
(Varies)
Description:
Jess's for function works just like Java's for loop. First the initializer is evaluated. Then the condition is evaluated. If it does not evaluate to FALSE, the body expressions are evaluated in order. Next, the increment is evaluated, and then the condition is checked again. The loop continues until the condition evaluates to FALSE or until a return or break is encountered.

Example: 
Jess> (for (bind ?i 0) (< ?i 10) (++ ?i)
    (printout t ?i crlf))
In Java, the initializer, condition, or increment can be empty. In Jess, you can use the constant nil as an equivalent.

16.73. (foreach <variable> <list-expression> <action>*)
Arguments:
A variable, a list expression or iterator, and zero or more arguments
Returns:
Varies
Description:

The named variable is set to each value from the list, in turn. For each value, all of the other arguments are evaluated in order. The break function can be used to break the iteration.

Example:

Jess> (foreach ?x (create$ a b c d) (printout t ?x crlf))
a
b
c
d

There are two ways to specify the series of values: you can either specify a Jess list (as created by create$) or you can provide a java.util.Iterator.

16.74. (format <router-identifier> <string-expression> <expression>*)
Arguments:
A router identifier, a format string, and zero or more arguments
Returns:
A string
Description:
Sends formatted output to the specified logical name. Formats the arguments into a string according to the format string, which is identical to that used by printf in the C language (find a C book for more information). Returns the string, and optionally prints the string to the named router. If you pass nil for the router name, no printing is done.

16.75. (gensym*)
Arguments:
None
Returns:
Symbol
Description:
Returns a special unique sequenced value. Returns a unique symbol which consists of the letters gen plus an integer. Use setgen to set the value of the integer to be used by the next gensym call.

16.76. (get <Java object> <string-expression>)
Arguments:
A Java object and a string.
Returns:
(Varies)
Description:

Retrieves the value of a JavaBean's property or instance variable. The first argument is the JavaBean and the second argument is the name of the property or variable. Jess will first try to find a JavaBean property by this name; if none is found, it will look for an instance variable. The return value is converted to a suitable Jess value exactly as for call.

If applied to a jess.Fact object get returns the value of the named slot, exactly as for fact-slot-value.

16.77. (get-current-module)
Arguments:
None
Returns:
The name of the current module
Description:
Gets the current module (see set-current-module).

16.78. (get-focus)
Arguments:
None
Returns:
Symbol
Description:
Returns the name of the current focus module (see focus).

16.79. (get-focus-stack)
Arguments:
None
Returns:
List
Description:
Returns the module names on the focus stack as a list. The top module on the stack is the first entry in the list.

16.80. (get-member (<Java object> | <string-expression>) <string-expression>)
Arguments:
A Java object or a string, and a member variable name.
Returns:
(Varies)
Description:
Retrieves the value of a Java object's data member. The first argument is the object (or the name of a class, for a static member) and the second argument is the name of the field. The return value is converted to a suitable Jess value exactly as for call.

16.81. (get-multithreaded-io)
Arguments:
None
Returns:
Boolean
Description:
Returns TRUE is Jess is currently using a separate thread to flush I/O streams. Turning this on can lead to a modest performance enhancement, at the expense of possible loss of output on program termination.

16.82. (get-reset-globals)
Arguments:
None
Returns:
Boolean
Description:
Indicates the current setting of global variable reset behavior. See set-reset-globals for an explanation of this property.

16.83. (get-salience-evaluation)
Arguments:
None
Returns:
Symbol
Description:
Indicates the current setting of salience evaluation behavior. See set-salience-evaluation for an explanation of this property.

16.84. (get-strategy)
Arguments:
(None)
Returns:
A symbol, the name of the current conflict resolution strategy.
Description:
Returns the name of the current conflict resolution strategy. See set-strategy.

16.85. (halt)
Arguments:
None
Returns:
TRUE
Description:
Halts rule execution. No effect unless called from the RHS of a rule.

16.86. (help <function-name>)
Arguments:
A function name
Returns:
nil
Description:
Prints a description of the named function to WSTDOUT.

16.87. (if <expression> then <action>* [elif <expression> then <action>*]* [else <action>*])
Arguments:
A Boolean expression, the symbol then, and any number of additional expressions; followed (zero or more times) by the symbol elif, a Boolean expression, then, and another list of expressions; optionally followed by the symbol else and another list of expressions.
Returns:
(Varies)
Description:
Allows conditional execution of a group of actions. The first Boolean expression is evaluated. If it does not evaluate to FALSE, the first list of actions is evaluated, and the return value is that returned by the last action of that list. If it does evaluate to FALSE, and there are optional elif blocks, then the Boolean expression of each of these is evaluated in turn; the first time one of them evaluates to non-FALSE, the associated list of actions is evaluated and the last result is returned. Finally, if none of the expressions is non-FALSE, and the optional else block is supplied, then the final list of actions is evaluated and the value of the last is returned.

Example: 
Jess> (if (> ?x 100) then
    (printout t "X is big" crlf)
 elif (> ?x 50) then
    (printout t "X is average" crlf)
 else
    (printout t "X is small" crlf))

16.88. (implement <interface> [using] <function>)
Arguments:
The name of an interface, the optional symbol "using", and a Jess function or lambda expression
Returns:
An object that implements the given interface
Description:
Lets you implement any interface from Jess. Here's an example of creating a Runnable object entirely from Jess and running it in a new Thread: 
Jess> ;; Function's arguments will be the name of the method called on proxy object
;; (run, here ), followed by the individual arguments passed to called
;; method (none here).
(deffunction my-runnable ($?args)
  (printout t "Hello, World" crlf))
TRUE

Jess> ;; Make a Runnable whose run() method will call my-runnable
(bind ?runnable (implement Runnable using my-runnable))
Jess> ;; Use the Runnable
((new Thread ?runnable) start)

16.89. (implode$ <list-expression>)
Arguments:
One list
Returns:
String
Description:
Creates a string from a list value. Converts each element of the list to a string, and returns these strings concatenated with single intervening spaces.

16.90. (import <symbol>)
Arguments:
One symbol
Returns:
TRUE
Description:

Works like the Java import statement. You can import either a whole package using

Jess> (import java.io.*)

or a single class using

Jess> (import java.awt.Button)

After that, all functions that can accept a Java class name (new, defclass, call, etc) will refer to the import list to try to find the class that goes with a specific name. Note that java.lang.* is now implicitly imported.

In addition, when you import a single class by name, Jess will define a series of Userfunctions that provide easy access to that class's static members. These functions are named ClassName.memberName. For example, because the classes in java.lang are imported this way, there are functions named "Thread.currentThread", "Integer.parseInt" which give access to those Java methods; there are also functions named "Short.MAX_VALUE" and "Thread.NORM_PRIORITY" which return the values of those Java constants. 

Jess> (if (> ?i (Short.MAX_VALUE)) then
    ((System.out) println "Too large for short")
    else
    ((System.out) println "Would fit in a short"))

16.91. (insert$ <list-expression> <integer-expression> <single-or-list-expression>+)
Arguments:
A list, an integer, and one or more lists
Returns:
A list
Description:
Returns a new list like the original but with one or more values inserted. Inserts the elements of the second and later lists so that they appear starting at the given 1-based index of the first list. An index value one greater than the list length is legal and will result in the second list being appended at the end of the first list.

16.92. (instanceof <Java object> <class-name>)
Arguments:
A Java object and the name of a Java class
Returns:
Boolean
Description:
Returns true if the Java object can be assigned to a variable whose type is given by the class name. Implemented using java.lang.Class.isInstance() . The class name can be fully-qualified or it can be an imported name; see the discussion of the import function.

16.93. (integer <numeric-expression>)
Arguments:
One numeric expression
Returns:
Integer
Description:
Converts its only argument to an integer. Truncates any fractional component of the value of the given numeric expression and returns the integral part.

16.94. (integerp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for integers; otherwise, returns FALSE.

16.95. (intersection$ <list-expression> <list-expression>)
Arguments:
Two lists
Returns:
List
Description:
Returns the intersection of two lists. Returns a list consisting of the elements the two argument lists have in common.

16.96. (java-objectp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE if the expression evaluates to a Java object.

16.97. (jess-type <value>)
Arguments:
Any value
Returns:
Symbol
Description:
Returns a symbol denoting the Jess data type of the argument.

16.98. (jess-version-number)
Arguments:
None
Returns:
Float
Description:
Returns a version number for Jess; currently 7.0 .

16.99. (jess-version-string)
Arguments:
None
Returns:
String
Description:
Returns a human-readable string descriptive of this version of Jess.

16.100. (lambda (<arguments>) <function call>+)
Arguments:
A list of arguments followed by any number of function calls
Returns:
An anonymous deffunction
Description:
Lets you create an unnamed deffunction. This is useful in conjunction with the implement function. In this example, we create a Runnable and execute it in a Thread. 
Jess> ((new Thread (implement Runnable using
     (lambda ($?args)
         (printout t "Hello, World" crlf))
     )
  ) start)

This looks a lot like doing the same thing with an anonymous class in Java:

new Thread(new Runnable() {
    public void run() {
        System.out.println("Hello, World!");
    }
}.start();

16.101. (length$ <list-expression>)
Arguments:
List
Returns:
Integer
Description:
Returns the number of elements in a list value.

16.102. (lexemep <expression>)
Arguments:
Any expression
Returns:
Boolean
Description:
Returns TRUE for symbols and strings; otherwise, returns FALSE.

16.103. (list <value>*)
Arguments:
Any number of values
Returns:
A list
Description:
An alias for create$.

16.104. (list-deftemplates [module-name | *])
Arguments:
Optionally, a module name, or the symbol "*"
Returns:
nil
Description:
With no arguments, prints a list of all deftemplates in the current module (not the focus module) to the 't' router. With a module name for an argument, prints the names of the templates in that module. With "*" as an argument, prints the names of all templates.

16.105. (list-focus-stack)
Arguments:
None
Returns:
nil
Description:
Displays the module focus stack, one module per line; the top of the stack (the focus module) is displayed first.

16.106. (list-function$)
Arguments:
None
Returns:
List
Description:
Returns a list list of all the functions currently callable, including intrinsics, deffunctions, and jess.Userfunctions. Each function name is a symbol. The names are sorted in alphabetical order.

16.107. (listp <expression>)
Arguments:
Any value
Returns:
Boolean
Description:
Returns TRUE for list values; otherwise, returns FALSE.

16.108. (load-facts <file-name>)
Arguments:
A string representing the name of a file of facts
Returns:
Boolean
Description:

Asserts facts loaded from a file. The argument should name a file containing a list of facts (not deffacts constructs, and no other commands or constructs). Jess will parse the file and assert each fact. The return value is the return value of assert when asserting the last fact. In an applet, load-facts will use getDocumentBase() to find the named file.

Note: See the batch command for a discussion about specifying filenames in Jess.

The file can be in either of two formats. The first format is just a list of facts in Jess language syntax. The second format is an XML file with a fact-list root element containing nothing but fact elements, as in JessML.

16.109. (load-function <class-name>)
Arguments:
The name of a Java class
Returns:
Boolean
Description:
The argument must be the fully-qualified name of a Java class that implements the jess.Userfunction interface. The class is loaded in to Jess and added to the engine, thus making the corresponding command available. See Extending Jess with Java for more information.

16.110. (load-package <class-name>)
Arguments:
The name of a Java class
Returns:
Boolean
Description:
The argument must be the fully-qualified name of a Java class that implements the jess.Userpackage interface. The class is loaded in to Jess and added to the engine, thus making the corresponding package of commands available. See Extending Jess with Java for more information.

16.111. (log <numeric-expression>)
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the logarithm base e of its only argument.

16.112. (log10 <numeric-expression>)
Arguments:
One numeric expression
Returns:
Number
Description:
Returns the logarithm base-10 of its only argument.

16.113. (long <expression>)
Arguments:
One expression, either numeric or String
Returns:
RU.LONG
Description:
Interprets the expression as a Java long (if possible) and returns a long value. This function is retained for backward compatibility only, as the Jess language now allows long literals.

16.114. (longp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE if the expression is of type RU.LONG; FALSE otherwise.

16.115. (lowcase <lexeme-expression>)
Arguments:
One symbol or string.
Returns:
String or symbol
Description:
Converts uppercase characters in a string or symbol to lowercase. Returns the argument as an all-lowercase symbol unless the argument is a string, in which case a string is returned.

16.116. (map <function> <list>)
Arguments:
A function and a list
Returns:
A list
Description:
Calls the function on each item in the list; returns a list of all the results. The function can either be the name of a Userfunction, or it can be a lambda expression.

16.117. (matches <lexeme-expression>)
Arguments:
One symbol, a rule or query name
Returns:
TRUE
Description:
Produces a printout, useful for debugging, of the contents of the left and right Rete memories of each two-input node on the given rule or query's LHS.

16.118. (max <numeric-expression>+)
Arguments:
One or more numerical expressions
Returns:
Number
Description:
Returns the value of its largest numeric argument

16.119. (member$ <expression> <list-expression>)
Arguments:
A value and a list
Returns:
Integer or FALSE
Description:
Returns the first position (1-based index) of a value within a list; otherwise, returns FALSE.

16.120. (min <numeric-expression>+)
Arguments:
One or more numeric expressions
Returns:
Number
Description:
Returns the value of its smallest numeric argument.

16.121. (mod <numeric-expression> <numeric-expression>)
Arguments:
Two integer expressions
Returns:
Integer
Description:
Returns the remainder of the result of dividing the first argument by its second (assuming that the result of the division must be an integer).

16.122. (modify <fact-specifier> (<slot-name> <value>)+)
Arguments:
A Fact and one or more two-element lists
Returns:
A Fact
Description:

Modifies a given unordered fact in working memory. The first argument specifies the fact to modify, and can be either a Fact object (such as you'd obtain from a pattern binding) or an integer (the id number of a fact.) If you use the id number, the corresponding fact must be looked up using jess.Rete.findFactByID(int), a slow operation. The fact must be an unordered fact.

Subsequent arguments are two-item lists. Each list is taken as the name of a slot in this fact and a new value to assign to the slot. The fact is removed from working memory, the values in the specified slots are replaced with the new values, and the fact is reasserted. The fact-ID of the fact does not change. The fact itself is returned. A jess.JessEvent of type FACT + MODIFIED will be sent if the event mask is set appropriately.

Modifying a shadow fact will cause the appropriate object properties to be set as well.

As of Jess version 7, the slot names can be variables.

It is important to remember that all pattern-matching happens during calls to assert, retract, modify, and related functions. Pattern-matching happens whether the engine is running or not.

16.123. (multifieldp <expression>)
Arguments:
Any value
Returns:
Boolean
Description:
Deprecated. Use listp instead.

16.124. (neq <expression> <expression>+)
Arguments:
Two or more values
Returns:
Boolean
Description:

Returns TRUE if the first argument is not equal in type and value to all subsequent arguments (see eq).

While often used in procedural code, this function is only rarely used during pattern matching. Direct matching is preferable.

16.125. (new <class-name> <argument>*)
Arguments:
The name of a Java class and zero or more expressions
Returns:
Boolean
Description:
Creates a new Java object and returns it. The first argument is the class name: java.util.Vector, for example. The second and later arguments are constructor arguments. The constructor will be chosen from among all constuctors for the named class based on a first-best fit algorithm. Built-in Jess types are converted as necessary to match available constructors. See the text for more details. Also see the import function.

16.126. (not <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE if its only arguments evaluates to FALSE; otherwise, returns FALSE. Note that this function is distinct from the not conditional element.

16.127. (nth$ <integer-expression> <list-expression>)
Arguments:
A number and a list
Returns:
(Varies)
Description:
Returns the value of the specified (1-based index) field of a list value.

16.128. (numberp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for numbers; otherwise, returns FALSE.

16.129. (oddp <integer-expression>)
Arguments:
One integer expression
Returns:
Boolean
Description:
Returns TRUE for odd numbers; otherwise, returns FALSE; see evenp.

16.130. (open <file-name> <router-identifier> [r|w|a])
Arguments:
A file name, an identifier for the file (a symbol), and optionally a mode string, one of r, w, a.
Returns:
The file identifier, a router name.
Description:
Opens a file. Subsequently, the given router identifier can be passed to printout, read, readline, or any other functions that accept I/O routers as arguments. By default, the file is opened for reading; if a mode string is given, it may be opened for reading only (r), writing only (w), or appending (a).

Note: See the batch command for a discussion about specifying filenames in Jess.

16.131. (or <expression>+)
Arguments:
One or more expressions
Returns:
Boolean
Description:
Returns TRUE if any of the arguments evaluates to a non-FALSE value; otherwise, returns FALSE. Note that this function is distinct from the or conditional element.

16.132. (pi)
Arguments:
None
Returns:
Number
Description:
Returns the number pi.

16.133. (pop-focus)
Arguments:
None
Returns:
The name of a module
Description:
Removes the top module from the focus stack and returns its name.

16.134. (ppdeffacts <symbol>)
Arguments:
The name of a deffacts
Returns:
String
Description:
Returns a pretty-print rendering of a deffacts.

16.135. (ppdeffunction <symbol>)
Arguments:
The name of a deffunction
Returns:
String
Description:
Returns a pretty-print representation of a deffunction.

16.136. (ppdefglobal <symbol>)
Arguments:
The name of a defglobal
Returns:
String
Description:
Returns a pretty-print representation of a defglobal

16.137. (ppdefquery <symbol> | *)
Arguments:
The name of a defquery or *
Returns:
String
Description:
An alias for ppdefrule .

16.138. (ppdefrule <symbol> | *)
Arguments:
The name of a rule or query, or the symbol *
Returns:
String
Description:
Returns a pretty-print rendering of a defrule or defquery. If the argument is the symbol "*", a single string containing all existing rules and queries in alphabetical order of their names is returned.

16.139. (ppdeftemplate <symbol>)
Arguments:
The name of a template
Returns:
String
Description:
Returns a pretty-print representation of a deftemplate.

16.140. (printout <router-identifier> <expression>*)
Arguments:
A router identifier followed by zero or more expressions
Returns:
nil
Description:
Sends unformatted output to the specified logical name. Prints its arguments to the named router, which must be open for output. No spaces are added between arguments. The special symbol crlf prints as a newline. The special router name t can be used to signify standard output.

16.141. (progn <expression>*)
Arguments:
Zero or more expressions
Returns:
The result of evaluating the last expression, or nil
Description:
A simple control structure that allows you to group multiple function calls where syntactically only one is allowed - for instance, on the LHS of a rule.

16.142. (provide <symbol>)
Arguments:
A symbol
Returns:
Returns the symbol.
Description:

Provides a feature to Jess. The symbol is entered in the feature table. See require.

If the feature is meant to be loaded from a subdirectory of the current directory or a subdirectory of a class path root, then the feature name must reflect that. For example if a feature X is implemented in the file com/company/X.clp, then the feature name must be "com/company/X". This full feature name must be used by require to load the feature or the feature may not be found.

16.143. (random)
Arguments:
None
Returns:
Number
Description:
Returns a pseudo-random integer between 0 and 65536.

16.144. (read [<router-identifier>])
Arguments:
An optional input router identifier (when omitted t is the default)
Returns:
(Varies)
Description:
Reads a single-field value from a specified logical name. Read a single symbol, string, or number from the named router, returns this value. The router t means standard input. Newlines are treated as ordinary whitespace. If you need to parse text line-by-line, use readline and explode$.

16.145. (readline [<router-identifier>])
Arguments:
An optional input router identifier (when omitted t is the default)
Returns:
String
Description:
Reads an entire line as a string from the specified logical name (router). The router t means standard input.

16.146. (regexp <regular expression> <data>)
Arguments:
A regular expression and a target, as symbols or strings
Returns:
Boolean
Description:
Compiles the regular expression and tries to match it against the entire target string, returning the Boolean result of the match. Uses the java.util.regexp package.

16.147. (remove <symbol>)
Arguments:
A symbol, the name of a template
Returns:
(Nothing)
Description:

Retracts all the facts currently in working memory that use the given template. Removing a shadow fact template will result in an implicit call to undefinstance for the corresponding objects (the objects will no longer be pattern-matched). A jess.JessEvent of type FACT + REMOVED will be sent for each fact removed if the event mask is set appropriately.

It is important to remember that all pattern-matching happens during calls to assert, retract, modify, and related functions. Pattern-matching happens whether the engine is running or not.

16.148. (replace$ <list-expression> <begin-integer-expression> <end-integer-expression> <expression>+)
Arguments:
A list, two numeric expressions, and one or more additional single or list values
Returns:
List
Description:
Returns a copy of a the original list with the elements in a specified range replaced with a new set of values. The variable number of final arguments are inserted into the first list, replacing elements between the 1-based indices given by the two numeric arguments, inclusive. Example: 
Jess> (replace$ (create$ a b c) 2 2 (create$ x y z))
(a x y z c)

16.149. (require <symbol> [<filename>])
Arguments:
A symbol, and optionally a filename
Returns:
Returns the symbol, or throws an exception on failure.
Description:

"Require" is similar to batch. The main difference is that it will only load a file once. If a file has been read before, this function won't read it a second time, whereas batch would.

The symbol argument is a "feature name". A file can "provide a feature" (see the provide function.) Once a feature has been provided, subsequent calls to require for this same feature name will be ignored.

If the optional filename is supplied, Jess passes that name to batch to attempt to read the file, if necessary. If the optional filename is not provided, Jess appends ".clp" to the feature name and uses that as the argument to batch. If the feature is not provided by the first file that is read, an exception is thrown to announce this failure.

The most important use of "require" is to establish dependencies between files in the JessDE editor.

16.150. (require* <symbol> [<filename>])
Arguments:
A symbol, and optionally a filename
Returns:
Returns the symbol, or nil on failure.
Description:

This function is just like require, except that it fails silently if the file is missing or if there is an error while parsing the required file. If the feature is provided, the feature name is returned; otherwise, nil is returned instead.

16.151. (reset)
Arguments:
None
Returns:
TRUE
Description:
Removes all facts from working memory, removes all activations, then asserts the fact (initial-fact), then asserts all facts found in deffacts, asserts a fact representing each registered Java object, and (if the set-reset-globals property is TRUE) initializes all defglobals.

16.152. (rest$ <list-expression>)
Arguments:
One list
Returns:
List
Description:
Returns all but the first field of a list as a new list.

16.153. (retract <expression>+)
Arguments:
One or more jess.Fact objects or integers
Returns:
TRUE
Description:

Retracts the facts given. Retracting a shadow fact will result in an implicit call to undefinstance for the corresponding object (the object will no longer be pattern-matched). A jess.JessEvent of type FACT + REMOVED will be sent if the event mask is set appropriately. Note that the arguments to this function must be integers or actual jess.Fact objects; they cannot be explicit facts as are accepted by assert.

It is important to remember that all pattern-matching happens during calls to assert, retract, modify, and related functions. Pattern-matching happens whether the engine is running or not.

16.154. (retract-string <string>)
Arguments:
A string, a representation of a Fact
Returns:
TRUE
Description:
Parses the string as a Fact; if such a fact exists in working memory, calls retract on it.

16.155. (return [<expression>])
Arguments:
An optional expression
Returns:
(Varies)
Description:
From a deffunction, returns the given value and exits the deffunction immediately. From the RHS of a defrule, terminates the rule's execution immediately and pops the current focus module from the focus stack. No argument should be given when return is called from the RHS of a rule.

16.156. (round <numeric-expression>)
Arguments:
One numeric expression
Returns:
Integer
Description:
Rounds its argument to the closest integer.

16.157. (rules [ <module-name> | * ])
Arguments:
Optionally, a module name, or the symbol "*"
Returns:
nil
Description:
With no arguments, prints a list of all rules and queries in the current module (not the focus module) to the 't' router. With a module name for an argument, prints the names of the rules and queries in that module. With "*" as an argument, prints the names of all rules and queries.

16.158. (run [<integer>])
Arguments:
Optionally, a single integer
Returns:
Integer
Description:
Starts the inference engine. If no argument is supplied, Jess will keep running until no more activations remain or halt is called. If an argument is supplied, it gives the maximum number of rules to fire before stopping. The function returns the number of rules actually fired.

16.159. (run-query <query-name> <expression>*)
Arguments:
The name of a query, and zero or more additional expressions
Returns:
A java.util.Iterator
Description:

Deprecated. Use run-query* instead.

Runs a query and returns a java.util.Iterator of the matches. See the documentation for defquery for more details. Note that run-query can lead to backwards chaining, which can cause rules to fire; thus if run-query is called on a rule RHS, other rules' RHSs may run to completion before the instigating rule completes. Putting run-query on a rule RHS can also cause the count of executed rules returned by run to be low.

Note that the Iterator returned by this function should be used immediately. It will become invalid if any of the following functions are called before you've used it: reset, count-query-results, or run-query. It may become invalid if any of the following are called: assert, retract, modify, or duplicate, and if any of the affected facts are involved in the active query's result.

16.160. (run-query* <query-name> <expression>*)
Arguments:
The name of a query, and zero or more additional expressions
Returns:
A jess.QueryResult
Description:
Runs a query and returns a jess.QueryResult of the matches. See the documentation for defquery for more details. Note that run-query can lead to backwards chaining, which can cause rules to fire; thus if run-query is called on a rule RHS, other rules' RHSs may run to completion before the instigating rule completes. Putting run-query* on a rule RHS can also cause the count of executed rules returned by run to be low.

16.161. (run-until-halt)
Arguments:
None.
Returns:
Integer
Description:
Runs the engine until halt is called. Returns the number of rules fired. When there are no active rules, the calling thread will be blocked waiting on the activation semaphore.

16.162. (save-facts <file-name> [<template-name>])
Arguments:
A filename, and optionally a symbol
Returns:
Boolean
Description:

Saves facts to a file in Jess language format. Attempts to open the named file for writing, and then writes a list of all facts in working memory to the file. This file is suitable for reading with load-facts. If the optional second argument is given, only facts whose head matches this symbol will be saved.

Note: See the batch command for a discussion about specifying filenames in Jess.

16.163. (save-facts-xml <file-name> [<template-name>])
Arguments:
A filename, and optionally a symbol
Returns:
Boolean
Description:

Saves facts to a file in XML format. This function attempts to open the named file for writing, and then writes a list of all facts in working memory to the file. A well-formed document containing an XML declaration, a fact-list root element, and one fact element for each fact will be written. This file is suitable for reading with load-facts. If the optional second argument is given, only facts whose head matches this symbol will be saved.

Note: See the batch command for a discussion about specifying filenames in Jess.

16.164. (set <Java object> <string-expression> <expression>)
Arguments:
A Java object, a property name, and an expression
Returns:
The last argument
Description:
Sets a JavaBean's property or instance variable to the given value. The first argument is the Bean object; the second argument is the name of the property or variable. The third value is the new value for the property; the same conversions are applied as for new and call. Jess will first try to find a JavaBean property by the given name; if none is found, it will look for an instance variable.

16.165. (set-current-module <module-name>)
Arguments:
The name of a valid module
Returns:
The name of the previous current module
Description:
Sets the current module. Any constructs defined without explicitly naming a module are defined in the current module. Note that defining a defmodule also sets the current module.

16.166. (set-factory <factory object> )
Arguments:
An object that implements the interface jess.factory.Factory
Returns:
A jess.factory.Factory
Description:
Set the "thing factory" for the active Rete object. Providing an alternate "thing factory" is a very advanced, and currently undocumented, way to extend Jess's functionality.

16.167. (setgen <numeric-expression>)
Arguments:
A numeric expression
Returns:
TRUE
Description:
Sets the starting number used by gensym*. Note that if this number has already been used, gensym* uses the next larger number that has not been used.

16.168. (set-member (<Java object> | <string-expression>) <string> <expression>)
Arguments:
A Java object or class name, a member variable name and an expression
Returns:
The last argument
Description:
Sets a Java object's member variable to the given value. The first argument is the object (or the name of the class, in the case of a static member variable). The second argument is the name of the variable. The third value is the new value for the variable; the same conversions are applied as for new and call.

16.169. (set-multithreaded-io (TRUE | FALSE))
Arguments:
Boolean
Returns:
Boolean
Description:
Specify whether Jess should use a separate thread to flush I/O streams. Turning this on can lead to a modest performance enhancement, at the expense of possible loss of output on program termination. Returns the previous value of this property.

16.170. (set-node-index-hash <integer>)
Arguments:
One integral value
Returns:
TRUE
Description:
Sets the default hashing key used in all Rete network join node memories defined after the function is called; this function will not affect parts of the network already in existence at the time of the call. A small value will give rise to memory-efficient nodes; a larger value will use more memory. If the created nodes will generally have to remember many partial matches, large numbers will lead to faster performance; the opposite may be true for nodes which will rarely hold more than one or two partial matches. This function sets the default; explicit declare statements can override this for specific rules.

16.171. (set-reset-globals <Boolean>)
Arguments:
One Boolean value
Returns:
Boolean
Description:
Changes the current setting of the global variable reset behavior. If this property is set to TRUE (the default), then the (reset) command reinitializes the values of global variables to their initial values (if the initial value was a function call, the function call is reexecuted.) If the property is set to FALSE, then (reset) will not affect global variables. Note that in previous versions of Jess, defglobals were always reset; but if the initial value was set with a function call, the function was not reevaluated. Now it is.

16.172. (set-salience-evaluation (when-defined | when-activated | every-cycle))
Arguments:
One of the symbols when-defined, when-activated, or every-cycle
Returns:
One of the potential arguments (the previous value of this property)
Description:
Changes the current setting of the salience evaluation behavior. By default, a rule's salience will be determined once, when the rule is defined (when-defined.) If this property is set to when-activated, then the salience of each rule will be redetermined immediately before each time it is placed on the agenda. If the property is set to every-cycle, then the salience of every rule is redetermined immediately after each time any rule fires.

16.173. (set-strategy <strategy-name>)
Arguments:
A symbol or string representing the name of a strategy (can be a fully-qualifed Java class name). You can use depth and breadth to represent the two built-in strategies.
Returns:
The previous strategy as a symbol.
Description:
Lets you specify the conflict resolution strategy Jess uses to order the firing of rules of equal salience. Currently, there are two strategies available: depth (LIFO) and breadth (FIFO). When the depth strategy is in effect (the default), more recently activated rules are fired before less recently activated rules of the same salience. When the breadth strategy is active, rules of the same salience fire in the order in which they are activated. Note that in either case, if several rules are activated simultaneously (i.e., by the same fact-assertion event) the order in which these several rules fire is unspecified, implementation-dependent and subject to change. More built-in strategies may be added in the future. You can implement your own strategies in Java by creating a class that implements the jess.Strategy interface and then specifying its fully-qualified classname as the argument to set-strategy. Details can be gleaned from the source.

16.174. (set-value-class <string-expression> TRUE|FALSE)
Arguments:
The name of a Java class
Returns:
TRUE
Description:

A value object is an instance of a class that represents a specific value. They are often immutable like Integer, Double, and String. For Jess's purposes, a value object is one whose hashCode() method returns a constant -- i.e., whose hash code doesn't change during normal operation of the class. Integer, Double, and all the other wrapper classes qualify, as does String, and generally all immutable classes. Any class that doesn't override the default hashCode() method also qualifies as a value object by the definition. Java's Collection classes (Lists, Maps, Sets, etc.) are classic examples of classes that are not value objects, because their hash codes depend on the collection's contents.

As far as Jess is concerned, an object is a value object as long as its hash code won't change while the object is in working memory. This includes the case where the object is contained in a slot of any fact. If the hash code will only change during calls to modify, then the object is still a value object.

Jess can make certain assumptions about value objects that lead to large performance increases during pattern matching. Because many classes are actually value classes by Jess's broad definition, Jess now assumes that all objects (except for Maps and Collections) are value objects by default. If you're working with a class that is not a value class, it's very important that you tell Jess about it by using the set-value-class function or the static method jess.HashCodeComputer.setIsValueClass(Rete, String, boolean) Failure to do so will lead to undefined (bad) behavior.

16.175. (set-watch-router <router-name>)
Arguments:
A symbol, the name of a valid output router
Returns:
The previous watch router name
Description:
Sets the router that the output from watch goes to. The old value is returned. Note that the watch router is not reset by reset or clear.

16.176. (show-deffacts)
Arguments:
None
Returns:
nil
Description:
Displays all defined deffacts to the 't' router.

16.177. (show-deftemplates)
Arguments:
None
Returns:
nil
Description:
Displays all defined deftemplates to the 't' router.

16.178. (show-jess-listeners)
Arguments:
None
Returns:
nil
Description:
Displays all jess.JessListeners registered with the engine to the 't' router.

16.179. (socket <Internet-hostname> <TCP-port-number> <router-identifier>)
Arguments:
An Internet hostname, a TCP port number, and a router identifier
Returns:
The router identifier
Description:
Somewhat equivalent to open, except that instead of opening a file, opens an unbuffered TCP network connection to the named host at the named port, and installs it as a pair of read and write routers under the given name.

16.180. (sqrt <numeric-expression>)
Arguments:
A numeric expression
Returns:
Number
Description:
Returns the square root of its only argument.

16.181. (store <string or symbol> <expression>)
Arguments:
A string or symbol and any other value
Returns:
(varies)
Description:
Associates the expression with the name given by the first argument, such that later calls to the fetch will retrieve it. Storing the symbol nil will clear any value associated with name. Analagous to the store() member function of the jess.Rete class. See section on using store and fetch for more details.

16.182. (str-cat <expression>*)
Arguments:
Zero or more expressions
Returns:
String
Description:
Concatenates its arguments as strings to form a single string. For Java objects, the toString() method of the contained object is called.

16.183. (str-compare <string-expression> <string-expression>)
Arguments:
Two symbols or strings
Returns:
Integer
Description:
Lexicographically compares two strings. Returns 0 if the strings are identical, a negative integer if the first is lexicographically less than the second, a positive integer if lexicographically greater.

16.184. (str-index <lexeme-expression> <lexeme-expression>)
Arguments:
Two symbols or strings
Returns:
Integer or FALSE
Description:
Returns the position of the first argument within the second argument. This is the 1-based index at which the first string first appears in the second; otherwise, returns FALSE.

16.185. (stringp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for strings; otherwise, returns FALSE.

16.186. (str-length <lexeme-expression>)
Arguments:
A symbol or string
Returns:
Integer
Description:
Returns the length of a symbol in characters.

16.187. (subseq$ <list-expression> <begin-integer-expression> <end-integer-expression>)
Arguments:
A list and two numeric expressions
Returns:
List
Description:
Extracts the specified range from a list value consisting of the elements between the two 1-based indices of the given list, inclusive. Index values less than 1 and greater than the list length are accepted, and so is a begin index greater than an end index, resulting in an empty list.

16.188. (subsetp <list-expression> <list-expression>)
Arguments:
Two lists
Returns:
Boolean
Description:
Returns TRUE if the first argument is a subset of the second (i.e., all the elements of the first list appear in the second list); otherwise, returns FALSE.

16.189. (sub-string <begin-integer-expression> <end-integer-expression> <string-expression>)
Arguments:
Two numbers and a string
Returns:
String
Description:
Retrieves a subportion from a string. Returns the string consisting of the characters between the two 1-based indices of the given string, inclusive. Both index values must not be less than 1 or greater than the string length. A begin index that is equal to the end index plus one results in the null string.

16.190. (symbolp <expression>)
Arguments:
One expression
Returns:
Boolean
Description:
Returns TRUE for symbols; otherwise, returns FALSE.

16.191. (sym-cat <expression>*)
Arguments:
Zero or more expressions
Returns:
Symbol
Description:
Concatenates its arguments as strings to form a single symbol. For Java objects, the toString() method of the contained object is called.

16.192. (synchronized <java-object> <action>*)
Arguments:
Any Java object, followed by any number of expressions
Returns:
(varies)
Description:
Executes the expressions inside a Java "synchronized" block which locks the given object. Returns the value of the last expression evaluated.

16.193. (system <lexeme-expression>+ [&])
Arguments:
One or more symbols or strings
Returns:
a java.lang.Process object, or FALSE
Description:
Sends a command to the operating system. Each symbol or string becomes one element of the argument array in a call to the Java java.lang.Runtime.exec(String[] cmdaray) method; therefore to execute the command edit myfile.txt, you should call (system edit myfile.txt), not (system "edit myfile.txt").

Normally blocks (i.e., Jess stops until the launched application returns), but if the last argument is an ampersand (&), the program will run in the background. The standard output and standard error streams of the process are connected to the 't' router, but the input of the process is not connected to the terminal.

Returns the Java Process object. You can call waitFor and then exitValue to get the exit status of the process.

16.194. (throw <java-object>)
Arguments:
A Java object that must inherit from java.lang.Throwable
Returns:
Does not return
Description:
Throws the given exception object. If the object is a jess.JessException, throws it directly. If the object is some other type of exception, it is wrapped in a JessException before throwing. The object's stack trace is filled in such that the exception will appear to have been created by the throw function.

16.195. (time)
Arguments:
None
Returns:
Number
Description:
Returns the number of seconds since 12:00 AM, Jan 1, 1970.

16.196. (try <expression>* [catch <expression>*] [finally <expression>*])
Arguments:
One or more expressions, followed optionally by the symbol catch followed by zero or more expressions, followed optionally by the symbol finally followed by zero or more expressions. Either the catch, or the finally, or both must be included.
Returns:
(Varies)
Description:
This command works something like Java try with a few simplifications. The biggest difference is that the catch clause can specify neither a type of exception nor a variable to receive the exception object. All exceptions occurring in a try block are routed to the single catch block. The variable ?ERROR is made to point to the exception object. For example: 
Jess> 
(try
    (open NoSuchFile.txt r)
 catch
    (printout t (call ?ERROR toString) crlf))
prints 
Jess reported an error in routine open
    while executing (open NoSuchFile.txt r).
Message: I/O Exception.

An empty catch block is fine. It just signifies ignoring possible errors.

The code in the finally block, if present, is executed after all try and/or catch code has executed, immediately before the try function returns.

16.197. (undefadvice <function-name> | ALL | <list>)
Arguments:
A function name, or ALL, or a list of function names
Returns:
TRUE
Description:
Removes all advice from the named function(s).

16.198. (undeffacts <deffacts-name> | *)
Arguments:
The name of a deffacts, or the symbol "*"
Returns:
Boolean
Description:
Deletes a deffacts. The next time the engine is reset, the facts in that deffacts will not be asserted. If the argument is "*", all deffacts are deleted.

16.199. (undefinstance (<java-object> | * ))
Arguments:
A Java object, or the symbol "*"
Returns:
TRUE
Description:
If the object currently has a shadow fact, it is removed from the working memory. Furthermore, if the object has a java.beans.PropertyChangeListener installed, this is removed as well. If the argument is "*" this is done for all Java objects in working memory.

16.200. (undefrule <rule-name>)
Arguments:
The name of a rule
Returns:
Boolean
Description:
Deletes a rule. Removes the named rule from the Rete network and returns TRUE if the rule existed. This rule will never fire again.

16.201. (union$ <list-expression>+)
Arguments:
One or more lists
Returns:
List
Description:
Returns a new list consisting of the union of all of its list arguments (i.e., of all the elements that appear in any of the arguments with duplicates removed).

16.202. (unwatch <symbol>)
Arguments:
One or more of the symbols all, rules, compilations, activations, facts, focus
Returns:
Description:
Causes trace output to not be printed for the given indicators. See watch.

16.203. (upcase <lexeme-expression>)
Arguments:
A string or symbol
Returns:
A string or symbol
Description:
Converts lowercase characters in a string or symbol to uppercase. Returns the argument as an all-uppercase symbol, unless the argument is a string, in which case a string is returned.

16.204. (update <java-object>+)
Arguments:
One or more Java objects, previously passed as arguments to add or definstance.
Returns:
The shadow fact tied to the last argument.
Description:
Java objects in working memory aren't necessarily updated automatically, since Jess may not know when an object object has been changed. This function lets you tell Jess explicitly that one or more Java objects have been updated. In response, Jess will find their corresponding shadow facts and update all their slots.

16.205. (view)
Arguments:
None
Returns:
TRUE
Description:
The view command displays a live snapshot of the Rete network in a graphical window. See How Jess Works for details.

16.206. (watch <symbol>)
Arguments:
One or more of the symbols all, rules, compilations, activations, facts, focus
Returns:
TRUE
Description:
Produces additional debug output when specific events happen in Jess, depending on the argument(s). Any number of different watches can be active simultaneously:
  • rules: prints a message when any rule fires.
  • compilations: prints a message when any rule is compiled.
  • activations: prints a message when any rule is activated, or deactivated, showing which facts have caused the event.
  • facts: print a message whenever a fact is asserted or retracted.
  • focus: print a message for each change to the module focus stack.
  • all: all of the above.

16.207. (while <expression> [do] <action>*)
Arguments:
A Boolean expression, the symbol do, and zero or more expressions
Returns:
(Varies)
Description:
Allows conditional looping. Evaluates the boolean expression repeatedly. As long as it does not equal FALSE, the list of other expressions are evaluated. A break also terminates the iteration. The value of the last expression evaluated is the return value of this function.