jess
Class Jesp

java.lang.Object
  jess.Jesp

All Implemented Interfaces:

ErrorSink

public class Jesp

extends java.lang.Object

implements ErrorSink

The Jess language parser. You can parse Jess language code directly with this class. Simply loading the contents of a file (or any other data source that can be supplied as a java.io.Reader is very easy:

 Rete engine = new Rete();
 FileReader file = new FileReader("myfile.clp");
 try {
     Jesp parser = new Jesp(file, engine);
     parser.parse(false);
 } finally {
     file.close();
 }
 

But this class's public interface is much richer than that. If you want to, you can parse the file one expression at a time, and have access to the parsed data. The method parseExpression(jess.Context, boolean) returns java.lang.Object, and the returned object can either be a Value or one of the Jess classes that represent a construct (Defrule, Deftemplate, etc.) In addition, you can choose to have the parser execute function calls as it parses them, or simply return them to you unexecuted (this is controlled by the second argument to parseExpression.

 Rete engine = new Rete();
 FileReader file = new FileReader("myfile.clp");
 Context context = engine.getGlobalContext();
 try {
     Jesp parser = new Jesp(file, engine);
     Object result = Funcall.TRUE;
     while (!result.equals(Funcall.EOF)) {
         result = parser.parseExpression(context, false);
         // Here you can use instanceof to determine what sort
         // of object "result" is, and process it however you want
     }
 } finally {
     file.close();
 }
 

There are also methods in this class to control whether comments should be returned from parseExpression or just skipped, methods to fetch various pieces of information about the parsing process, and a mechanism for controlling whether warnings or just errors should be reported.

Instances of Jesp are not serializable, as they hold a reference to a Reader.

(C) 2006 Sandia National Laboratories

Field Summary

static java.lang.String

PROMPT

Constructor Summary

Jesp(java.io.Reader reader, Rete engine)
Construct a Jesp object.

Jesp(Tokenizer tokenizer, Rete engine)
Construct a Jesp object.

Method Summary

void	addArgumentChecker(java.lang.String name, ArgumentChecker checker) Add an ArgumentChecker to this parser.
void	clear() Flush any partially-parsed information, probably to the next ')'.
void	clearWarnings() Clear any pending parser warnings.
void	eatWhitespace() Consumes all whitespace up to the next non-whitespace token.
void	eatWhitespaceAndComments() Consumes all whitespace and comments up to the next non-whitespace, non-comment token.
void	error(java.lang.String routine, java.lang.String msg, int code, JessToken errorToken)
void	error(java.lang.String routine, java.lang.String msg, int code, JessToken errorToken, Named construct)
void	error(java.lang.String routine, java.lang.String msg, java.lang.String[] alternatives, int code, JessToken errorToken)
void	error(java.lang.String routine, java.lang.String msg, java.lang.String[] alternatives, int code, JessToken errorToken, Named construct)
Rete	getEngine() Return the rule engine this parser is attached to .
int	getStreamPos() Wrapper for JessTokenStream.getStreamPos().
java.util.List	getWarnings() Get the list of currently applicable warnings; each warning is an instance of ParseException.
static boolean	isAConstructName(java.lang.String name)
Value	loadFacts(Context c) Parses an input file containing only facts, asserts each one.
Value	parse(boolean prompt) Parses an input file.
Value	parse(boolean prompt, Context context) Parses an input file by calling promptAndParseOneExpression(boolean, jess.Context) in a loop.
Deffacts	parseDeffacts(Rete engine, jess.JessTokenStream jts) parseDeffacts Syntax: (deffacts ["comment"] (fact) [(fact)...])
Deffunction	parseDeffunction(Rete engine, jess.JessTokenStream jts) Parses a deffunction contstuct to create a Deffunction object.
Defmodule	parseDefmodule(jess.JessTokenStream jts) Parse a defmodule construct and return a Defmodule object.
Defquery	parseDefquery(Context context, Rete engine, jess.JessTokenStream jts) Parses a defquery construct and returns a Defquery object.
Defrule	parseDefrule(Context context, Rete engine, jess.JessTokenStream jts) Parses a defrule construct and creates a Defrule object.
Deftemplate	parseDeftemplate(Context context, Rete engine, jess.JessTokenStream jts) Parses a deftemplate construct and returns the parsed Deftemplate object.
java.lang.Object	parseExpression(Context context, boolean executeFuncalls) Parse and return a single expression.
java.lang.Object	parseExpression(Context context, boolean executeFuncalls, jess.JessTokenStream jts) Parse and return a single expression from the given token stream.
Funcall	parseFuncall(Rete engine, jess.JessTokenStream jts) Parses a function call and returns the parsed Funcall object.
Value	promptAndParseOneExpression(boolean prompt, Context context) Parse and return a single expression.
void	setFileName(java.lang.String fileName) Set the filename used for error reporting.
void	setIssueWarnings(boolean required) Turn parser warnings on (true) or off (false).
void	warning(java.lang.String routine, java.lang.String msg, java.lang.String[] alternatives, int code, JessToken errorToken)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROMPT

public static final java.lang.String PROMPT

See Also:

Constant Field Values

Constructor Detail

Jesp

public Jesp(java.io.Reader reader,
            Rete engine)

Construct a Jesp object. The reader will be looked up in the Rete object's router tables, and any wrapper found there will be used.

Parameters:

reader - The Reader from which this Jesp should get its input

engine - The engine that the parsed commands go to

Jesp

public Jesp(Tokenizer tokenizer,
            Rete engine)

Construct a Jesp object. The given tokenizer will be used directly

Parameters:

tokenizer - The Tokenizer from which this Jesp should get its input

engine - The engine that the parsed commands go to

Method Detail

addArgumentChecker

public void addArgumentChecker(java.lang.String name,
                               ArgumentChecker checker)

Add an ArgumentChecker to this parser. The ArgumentChecker's ArgumentChecker.check(jess.Funcall, jess.JessToken, jess.ErrorSink) method will be called whenever a matching function call is parsed.

Parameters:

name - the name of the function for which this ArgumentChecker should be invoked

checker - the ArgumentChecker to use

getEngine

public Rete getEngine()

Return the rule engine this parser is attached to .

Specified by:

getEngine in interface ErrorSink

Returns:

the Rete instance

setIssueWarnings

public void setIssueWarnings(boolean required)

Turn parser warnings on (true) or off (false).

Parameters:

required - true if warnings should be issued

clearWarnings

public void clearWarnings()

Clear any pending parser warnings.

getWarnings

public java.util.List getWarnings()

Get the list of currently applicable warnings; each warning is an instance of ParseException.

Returns:

a list of warnings

getStreamPos

public int getStreamPos()

Wrapper for JessTokenStream.getStreamPos().

Returns:

the stream position

eatWhitespace

public void eatWhitespace()
                   throws JessException

Consumes all whitespace up to the next non-whitespace token.

Throws:

JessException - if an input error occurs

eatWhitespaceAndComments

public void eatWhitespaceAndComments()
                              throws JessException

Consumes all whitespace and comments up to the next non-whitespace, non-comment token.

Throws:

JessException - if an input error occurs

parse

public Value parse(boolean prompt)
            throws JessException

Parses an input file. Argument is true if a prompt should be printed (to the Rete object's standard output), false for no prompt. Uses the Rete object's global context to resolve variables.

Parameters:

prompt - True if a prompt should be printed.

Returns:

The result of the last parsed entity (often TRUE or FALSE).

Throws:

JessException - If anything goes wrong.

parse

public Value parse(boolean prompt,
                   Context context)
            throws JessException

Parses an input file by calling promptAndParseOneExpression(boolean, jess.Context) in a loop. Argument is true if a prompt should be printed (to the Rete object's standard output), false for no prompt. Uses the given context to resolve variables.

Parameters:

prompt - True if a prompt should be printed.

Returns:

The result of the last parsed entity (often TRUE or FALSE).

Throws:

JessException - If anything goes wrong.

promptAndParseOneExpression

public Value promptAndParseOneExpression(boolean prompt,
                                         Context context)
                                  throws JessException

Parse and return a single expression. The expression is always printed to the Rete object's standard output. Argument is true if a prompt should be printed (to the Rete object's standard output), false for no prompt. Uses the given context to resolve variables.

Parameters:

prompt - True if a prompt should be printed.

Returns:

The result of the last parsed entity (often TRUE or FALSE).

Throws:

JessException - If anything goes wrong.

clear

public void clear()

Flush any partially-parsed information, probably to the next ')'. Useful in error recovery.

loadFacts

public Value loadFacts(Context c)
                throws JessException

Parses an input file containing only facts, asserts each one.

Returns:

The symbol TRUE

Throws:

JessException - If an error occurs

parseExpression

public java.lang.Object parseExpression(Context context,
                                        boolean executeFuncalls)
                                 throws JessException

Parse and return a single expression. Nothing is printed. Uses the given context to resolve variables. Optionally, executes the expression if it's a function call.

Parameters:

context - an execution context

executeFuncalls - true if function calls should be executed immediately

Returns:

The result of the parsed entity

Throws:

JessException - If anything goes wrong.

parseExpression

public java.lang.Object parseExpression(Context context,
                                        boolean executeFuncalls,
                                        jess.JessTokenStream jts)
                                 throws JessException

Parse and return a single expression from the given token stream. Nothing is printed. Uses the given context to resolve variables. Optionally, executes the expression if it's a function call.

Parameters:

context - an execution context

executeFuncalls - true if function calls should be executed immediately

jts - a token stream from which to parse an expression

Returns:

The result of the parsed entity

Throws:

JessException - If anything goes wrong.

setFileName

public void setFileName(java.lang.String fileName)

Set the filename used for error reporting.

Parameters:

fileName - the filename this parser will report in error messages

parseDefmodule

public Defmodule parseDefmodule(jess.JessTokenStream jts)
                         throws JessException

Parse a defmodule construct and return a Defmodule object.

Syntax:
(defmodule modulename "Comment")

Parameters:

jts - the token stream

Returns:

the parsed Defmodule object

Throws:

JessException - if there is a syntax error.

parseFuncall

public Funcall parseFuncall(Rete engine,
                            jess.JessTokenStream jts)
                     throws JessException

Parses a function call and returns the parsed Funcall object.

Syntax:
(functor field2 (nested funcall) (double (nested funcall)))

Trick: If the functor is a variable, we insert the functor 'call' and assume we're going to make an outcall to Java on the object in the variable!

Returns:

the parsed function call

Throws:

JessException - if there is a syntax error.

parseDeffacts

public Deffacts parseDeffacts(Rete engine,
                              jess.JessTokenStream jts)
                       throws JessException

parseDeffacts

Syntax: (deffacts ["comment"] (fact) [(fact)...])

Returns:

the parsed Deffacts construct

Throws:

JessException - if there is a syntax error.

parseDeftemplate

public Deftemplate parseDeftemplate(Context context,
                                    Rete engine,
                                    jess.JessTokenStream jts)
                             throws JessException

Parses a deftemplate construct and returns the parsed Deftemplate object.

Syntax:
(deftemplate (slot foo (default )) (multislot bar))

Returns:

the parsed Deftemplate object

Throws:

JessException - if there is a syntax error.

parseDefrule

public Defrule parseDefrule(Context context,
                            Rete engine,
                            jess.JessTokenStream jts)
                     throws JessException

Parses a defrule construct and creates a Defrule object.

Syntax:
(defrule name
[ "docstring...." ]
[ (declare [(salience 1)] [(node-index-hash 57)]) ]
(pattern 1)
?foo <- (pattern 2)
(pattern 3)
=>
(action 1)
(action ?foo)
)

Returns:

the parsed Defrule object

Throws:

JessException - if there is a syntax error.

parseDefquery

public Defquery parseDefquery(Context context,
                              Rete engine,
                              jess.JessTokenStream jts)
                       throws JessException

Parses a defquery construct and returns a Defquery object.

Syntax:
(defquery name
[ "docstring...." ]
[(declare (variables ?var1 ?var2 ...))]
(pattern))

Returns:

the parsed Defquery object

Throws:

JessException - if there is a syntax error.

parseDeffunction

public Deffunction parseDeffunction(Rete engine,
                                    jess.JessTokenStream jts)
                             throws JessException

Parses a deffunction contstuct to create a Deffunction object.

Syntax:
(deffunction name ["doc-comment"] ( (action)
value
(action))

Returns:

the parsed Deffunction construct

Throws:

JessException - if there is a syntax error.

error

public void error(java.lang.String routine,
                  java.lang.String msg,
                  int code,
                  JessToken errorToken)
           throws JessException

Specified by:

error in interface ErrorSink

Throws:

JessException

error

public void error(java.lang.String routine,
                  java.lang.String msg,
                  int code,
                  JessToken errorToken,
                  Named construct)
           throws JessException

Specified by:

error in interface ErrorSink

Throws:

JessException

error

public void error(java.lang.String routine,
                  java.lang.String msg,
                  java.lang.String[] alternatives,
                  int code,
                  JessToken errorToken)
           throws JessException

Specified by:

error in interface ErrorSink

Throws:

JessException

error

public void error(java.lang.String routine,
                  java.lang.String msg,
                  java.lang.String[] alternatives,
                  int code,
                  JessToken errorToken,
                  Named construct)
           throws JessException

Specified by:

error in interface ErrorSink

Throws:

JessException

warning

public void warning(java.lang.String routine,
                    java.lang.String msg,
                    java.lang.String[] alternatives,
                    int code,
                    JessToken errorToken)

Specified by:

warning in interface ErrorSink

isAConstructName

public static boolean isAConstructName(java.lang.String name)