3 Using the Command-line Interface

This chapter describes the RL command-line that reads rulesets from System.in and writes output from the functions println, watch, and, show to System.out.

This chapter includes the following topics:

Section 3.1, "Starting and Using the Command-Line Interface"
Section 3.2, "RL Command-Line Options"
Section 3.3, "RL Command-Line Built-in Commands"

3.1 Starting and Using the Command-Line Interface

The following invocation provides a simple command-line interface, with the prompt, RL>. Example without Java Beans:

java -jar SOA_ORACLE_HOME/soa/modules/oracle.rules_11.1.1/rl.jar -p "RL> "

Where SOA_ORACLE_HOME is where SOA modules are installed (for example, c:/Oracle/Middleware). The –p option specifies the prompt.

The following shows how an RL Language command-line can be started that can access this Java bean:

java -classpath SOA_ORACLE_HOME/soa/modules/oracle.rules_11.1.1/rl.jar;BeanPath oracle.rules.rl.session.CommandLine -p "RL> "

Where BeanPath is the classpath component to any supplied Java Bean classes.

To exit the command-line interface, use the special action exit; at the command prompt. The exit; action cannot be in an included ruleset. Alternatively, to exit you can invoke the System.exit(int) method in any action.

The RL command-line interface accumulates input line by line, and interprets the input when the input stream includes either:

A complete named ruleset
One or more complete import, include, ruleset, definition, action commands within an unnamed ruleset.

Note:

The if,else and try, catch, and finally actions require lookahead to determine where they end. In order to execute an if without an else clause, or a try without a finally clause at the RL command-line, you should add a semi-colon terminator.

This is not necessary if you execute RL using include, or using the RuleSession API.

Example 3-1 Sample RL Command-Line Input Processing

RL> int i = 1;
RL> if (i > 0) {println("i positive");}
// nothing happens - waiting for possible "else"
;
i positive
RL>

Input must be complete at the end of a line. For example, if an action ends in the middle of a line, then that action is not interpreted until some following action is complete at the end of a line.

Example 3-2 Sample Command-Line Input Processing - Waiting for End of Line

RL> println("delayed"
); println("hello"
); println("world");
delayed
hello
world
RL>

Notes for using command-line input processing:

The command-line segments its input into blocks and then feeds each block to the interpreter. If you never type a closing brace or semicolon, no error is raised because the command line waits for input before it does a full parse of the block
The command-line interpreter, when used interactively or with the –i option, collapses the input, for line numbering purposes, into "small" rulesets ending at a newline. Errors are reported with numbers within the ruleset.

For example, if the input consists of the following:
```
int i = 0; i = 1; // this is a ruleset
i = "i";  // this is another ruleset 
```
For this example, command-line reports an error as follows:
```
Oracle Business Rules RL: type check error
ConversionException: cannot convert from type 'java.lang.String' to type 'int'
at line 1 column 5 in main
```
To avoid this behavior, you can explicitly enclose the input in a ruleset. For example,
```
ruleset main {
     int i = 0; i = 1;
     i = "i";
}
```
Now, the error is on line 3 or, you can include the input file using an include.

3.2 RL Command-Line Options

Table 3-1 RL Command-Line Options

Flag	Description
–i	Read rulesets from the file named by the next argument, instead of from the default, `System.in`. For example, -i myInput.rl Note: the command-line segments its input into blocks and then feeds each block to the interpreter. If the file `myInput.rl` does not include a closing brace or semicolon at the end, then, no error is raised because the command line waits for additional input before it does a full parse of the block. Thus, there are cases where an incomplete input file supplied using the –`i` option could run and execute the valid part of the code from the file `myInput.rl`, and exit, while still waiting for command line input.
–c	Executes the next argument as the first RL command, then start reading input. This option is useful to include a file of settings and functions for debugging. For example, -c "include file:debugSettings.rl;" If you do not want to read from the input after executing the command, include "exit;" at the end of the command. For example, -c "include file:script.rl; exit;"
–p	Sets the next argument as the prompt string. For example, -p "RL> "
-o	Specifies where to write output from `println`, `watch`, and `show` to the file named by the next argument, instead of to `System.out`. For example: –o debug.log
–v	Print version information.

3.3 RL Command-Line Built-in Commands

This section lists commands that are implemented by the RL command-line interface (these commands are not part of RL). Thus, these commands cannot appear in blocks or be included rulesets.

3.3.1 Clear Command

Discard the current RuleSession object and allocate a new one. The effect is that all rules, variables, classes, and functions are discarded.

Instead of using clear; to restart a command-line you can also type exit; and then reissue the Java command to start another command-line.

3.3.2 Exit Command

Exit the command-line interface. The command-line interface also exits when end-of-file is reached on its input.