4. Defining Functions in Jess

4.1. Deffunctions

You can define your own functions in the Jess rule language using the deffunction construct. A deffunction construct looks like this:
(deffunction <function-name> [<doc-comment>] (<parameter>*)
   <expr>* [<return-specifier>])
The <function-name> must be a symbol. Each <parameter> must be a variable name. The optional <doc-comment> is a double-quoted string that can describe the purpose of the function. There may be an arbitrary number of <expr> expressions. The optional <return-specifier> gives the return value of the function. It can either be an explicit use of the return function or it can be any value or expression. Control flow in deffunctions is achieved via control-flow functions like foreach, if, and while. The following is a deffunction that returns the larger of its two numeric arguments:

Jess> (deffunction max (?a ?b)
  (if (> ?a ?b) then
      (return ?a)
  else
      (return ?b)))
TRUE

Note that this could have also been written as:

Jess> (deffunction max (?a ?b)
  (if (> ?a ?b) then
      ?a
   else
      ?b))
TRUE

This function can now be called anywhere a Jess function call can be used. For example

Jess> (printout t "The greater of 3 and 5 is " (max 3 5) "." crlf)
The greater of 3 and 5 is 5.

Normally a deffunction takes a specific number of arguments. To write a deffunction that takes an arbitrary number of arguments, make the last formal parameter be a multifield -- a variable prefixed with a '$' character. When the deffunction is called, the multifield variable will contain all the remaining arguments passed to the function, as a list. A deffunction can accept no more than one such wildcard argument, and it must be the last argument to the function.

You can also customize the Jess language with functions written in Java. These are indistinguishable from built-in functions, and in fact, you write them using the same interface used to define built-in functions. See here for details.

4.2. Defadvice

Sometimes a Jess function won't behave exactly as you'd like. The defadvice construct lets you write some Jess code which will be executed before or after each time a given Jess function is called. defadvice lets you easily "wrap" extra code around any Jess function, such that it executes before (and thus can alter the argument list seen by the real function, or short-circuit it completely by returning a value of its own) or after the real function (and thus can see the return value of the real function and possibly alter it. ) defadvice provides a great way for Jess add-on authors to extend Jess without needing to change any internal code.

Here are some examples of what defadvice looks like.

This intercepts calls to 'plus' (+) and adds the extra argument '1', such that (+ 2 2) becomes (+ 2 2 1) -> 5. The variable '$?argv' is special. It always refers to the list of arguments the real Jess function will receive when it is called.

Jess> (defadvice before + (bind $?argv (create$ $?argv 1)))
TRUE
Jess> (+ 2 2)
5

This makes all additions equal to 1. By returning, the defadvice keeps the real function from ever being called.

Jess> (defadvice before + (return 1))
TRUE
Jess> (+ 2 2)
1

This subtracts one from the return value of the + function. ?retval is another magic variable - it's the value the real function returned. When we're done, we remove the advice with undefadvice.

Jess> (defadvice after + (return (- ?retval 1)))
TRUE
Jess> (+ 2 2)
3
Jess> (undefadvice +)
Jess> (+ 2 2)
4