ARL Master Index


Miscellaneous

This section covers some miscellaneous topics dealing with ABLE rulesets.

On this page...


Built-in Variables

ARL provides the following built-in variables, all of which may be referenced in rules. These variables are, for the most part, read-only variables. You must not attempt to redefine them in the variables section of a ruleset.

this
A reference to the ruleset itself.
parent
A reference to the object, if any, that contains the ruleset (typically an AbleAgent).
functionList
The list of library functions.
variableList
A list of global variables declared in the ruleset variables section.
inputBuffer
A reference to the ruleset's external input buffer. It is a Java Object array.
outputBuffer
A reference to the ruleset's external output buffer. It is a Java Object array.
wm
A reference to the ruleset's working memory.
null
The value null.
Return to top

Functions - Interacting with the World Outside of the RuleSet

Functions allow rules to interact with the outside world. For example, a rule can invoke a function to read a gauge, such as a thermometer, and use the returned value to set a variable. Or, a function can be used notify some other program about some action it should take, causing some side-effect. Or a function might be used to send an e-mail. The uses of functions are many and varied.

There are several ways to make functions available to rules. First of all, there are built-in functions provided by all rulesets. These are described in Built-In Functions below. Another way is to import Java classes into a ruleset so that all the public methods in the imported classes become accessible to your rules. This technique is described below in Function Libraries. And yet another way is to use Externally Attached Functions, also described below.


Built-in Functions

ABLE provides a set of built-in functions that are always available in all rulesets. The built-in functions listed below may be referenced in any rule without any additional work on the part of the rule writer.

Note that built-in functions always take precedence over imported function library functions of the same name and arity, but that externally attached functions can override built-in and imported functions.

invokeRuleBlock(string)
Invokes the specified rule block, which must be declared in the current ruleset.
getRuleSetName()
Returns a string that is the ruleset's name.
getVariable(string)
Returns a reference to the specified variable.
getNumInputVars()
Returns the number of variables listed in the InputVariables statement.
getNumOutputVars()
Returns the number of variables listed in the OutputVariables statement.
getOutputVars()
Returns a list of the variables listed in the OutputVariables statement.
setBaseTraceLevelNone()
setBaseTraceLevelLow()
setBaseTraceLevelMedium()
setBaseTraceLevelHigh()
Turns base ruleset tracing to off, low, medium, or high.
getBaseTraceLevel()
Returns the current base ruleset tracing level.
isBaseTraceActive()
Returns a boolean that indicates whether base ruleset tracing is on or off.
setInferenceTraceLevelNone()
setInferenceTraceLevelLow()
setInferenceTraceLevelMedium()
setInferenceTraceLevelHigh()
Turns inference engine tracing to off, low, medium, or high.
getInferenceTraceLevel()
Returns the current inference engine tracing level.
isInferenceTraceActive()
Returns a boolean that indicates whether inference engine tracing is on or off.
logInferenceTrace(string)
Writes a message to the trace log.
logInferenceMessage(string)
Writes a message to the message log.
setParseTraceLevelNone()
setParseTraceLevelLow()
setParseTraceLevelMedium()
setParseTraceLevelHigh()
Turns parser tracing to off, low, medium, or high.
getParseTraceLevel()
Returns the current parser tracing level.
isParseTraceActive()
Returns a boolean that indicates whether parser tracing is on or off.
getCurrentDateAndTime()
Returns a Calendar instance obtained from Calendar.getInstance() that can be assigned to Object variables or user-defined variables.
getCurrentDateAndTime(String theTimeZoneId, String theLanguage, String theCountry)
Returns a Calendar instance obtained from Calendar.getInstance() that can be assigned to Object variables or user-defined variables.

Function Libraries

The entire set of public methods in any arbitrary Java class can be made available to a ruleset all at once by simply loading the function library into the ruleset. The Java class becomes a function library of the ruleset, and means that you can write your own specialized set of functions to meet your unique needs. The only restriction on Java classes you import is that, if you intend to serialize your ABLE ruleset, any library classes must also be serializable. See the library statement for details.

Note that if a library function has the same name and arity as a built-in function, the built-in function takes precedence. Note also that externally attached functions can override both built-in and imported functions.

Able provides you with these built-in function libraries:

Of these libraries, the highly specialized AbleCalendarLib, AbleDebugLib, AbleGUILib, AblePredicateLib, and AbleStringLib require an explicit library statement to use their methods. The other libraries are imported automatically for you.

AbleBeanLib is experimental and may change from release to release. As of this writing, AbleBeanLib provides methods for instantiating arbitrary Java objects from rules and for calling methods on those objects. One interesting use is to write rules that create additional Able ruleset objects and then invoke those newly created rulesets. In this way, rulesets can be cascaded, calling one another and returning values. This library is built-in and does not need to be explicitly imported for its methods to be used. As always, read the JavaDoc output to see what is available. You will find examples in the AbleBeanLibDemo.rs example ruleset.

AbleCalendarLib provides methods that make it easy to do temporal reasoning. You can determine whether dates are before, after, or between other dates, and do date manipulation. To take full advantage of AbleCalendarLib, use the library with your own user-defined Calendar data type:

import java.util.GregorianCalendar;   
library com.ibm.able.rules.AbleCalendarLib;

variables  { GregorianCalendar currentTime = new GregorianCalendar();} 
void main() { T1: currentTime = getCurrentTime(); }
      
and so on.... You do have to explicitly import this library in order to use its methods.

AbleDebugLib provides a handy graphical debugging console that you can use to debug your rulesets when within the Able Editor environment. When enabled, you can step through your rules a clause, rule, ruleblock, or ruleset at a time. Refer to Debugging a RuleSet in this section for more information. You do have to explicitly import this library in order to use its methods.

AbleGUILib is used exclusively by backward chaining inference engines and contains methods to allow an inference engine to prompt a user to supply values of variables that can not be determined through inferencing. If you run your rule agents in an environment that allows an inference engine to interact with an end user, simply import this library to activate potential end user interaction. If you run your rule agents in an environment where it is not possible to interact with end users, do not import this library, and the inference engine will make no attempt to query a user for indeterminant variable values.

AbleListLib provides most of the function of the java.util.List interface and is provided for manipulating List variables. The methods in this library all begin with the word list which is then followed by a java.util.List method name; for example, the method addAll() becomes listAddAll(). The example source ruleset, AbleListLibDemo.rs, provides many examples of using the list library. This library is built-in and does not need to be imported for its methods to be used. For a list of available methods, read the JavaDoc output for this class.

AbleMathLib provides almost all the function of java.lang.Math to rule writers. The method names in this library are exactly the same as in the java.lang.Math class. This library is built-in and does not need to be imported for its methods to be used. For a list of available methods, read the JavaDoc output for this class. For examples of using some of the methods provided by this class, see the AbleMathLibDemo.rs example ruleset.

AblePredicateLib is useful only to predicate logic rulesets and provides a few mathematical functions designed to work with the predicate inference engine. You do have to explicitly import this library in order to use its methods.

AbleStringLib provides selected functions from java.lang.String and java.lang.StringBuffer to rule writers. The method names in this library follow those in the java.lang classes with a prefix of 'string'. You must explicitly import this library in order to use its methods. For a list of available methods, read the JavaDoc output for this class. For examples of using some of the methods provided by this class, see the AbleStringLibDemo.rs example ruleset.

AbleWorkingMemoryLib provides functions, such as assert() and retract(), to manipulate working memory from within your rules. This library is built-in and does not need to be imported for its methods to be used. For a list of available methods, read the JavaDoc output for this class.

Externally Attached Functions

Built-in and imported functions must exist at the time a ruleset is compiled and they occupy space in the compiled ruleset. Externally attached functions are functions that are added to a ruleset at runtime under control of some external Java program, just before the ruleset is actually processed, and the functions occupy space somewhere else in the Java virtual machine. Because the ABLE Rule Language compiler needs to know the names of these functions, however, you must use the functions statement to specify, by name and arity, those functions that will be attached to the ruleset at runtime. Then, if declared externally attached functions are not available when the ruleset is processed, a runtime exception is thrown.

ABLE's examples/rules directory contains the source code of an example program that attaches external functions to a ruleset and then processes the ruleset. The program's name is SampleSensorEffector.java.

Note that externally attached functions always take precedence over built-in and imported functions of the same name and arity, so you can use external functions to override the behavior of built-in and imported functions.

Return to top

Debugging a RuleSet

To interactively debug a ruleset within the Able Editor environment, follow these steps:

Note that the debug console will close at the end of each inference cycle even though a stopDebugConsole(this) statement hasn't been reached. Note also that a startDebugConsole(this) statement will cause the debug console to reappear at any time, even though Rule, RuleBlock, Run, or Quit is in effect.

Return to top

Working with a RuleSet Programmatically

To create and work with a ruleset in a Java program, follow these steps:

The above code snippets demonstrate working with a ruleset at its simplest. An example Java program, SampleSensorEffector.java, is provided in Able's examples/rules directory and clearly shows these techniques. Of course, there are many other ways to work with rulesets, such as wiring them to input data sources and filters, sending the output to Able agents, and so on. These techniques are beyond the scope of this document.

Return to top

Tips for Writing Rules

Rule Formatting

Rule Labels

List Variables

Boolean Literals

Numeric Literals

String References

Function Arguments

Function Return Value

Operators

Return to top
Able Rule Language master index.
Able RuleSet Editor master index.
Rules package table of contents.

Last modified: Wed Oct 03 10:39:11 Central Daylight Time 2001