jess
Class Jesp

java.lang.Object
  extended by 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) 2013 Sandia Corporation


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<ParseException> 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, Context context)
          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<ParseException> 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,
                                Context context)
                         throws JessException
Parse a defmodule construct and return a Defmodule object.

Syntax:
(defmodule modulename "Comment")

Parameters:
jts - the token stream
context -
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"] (...) ["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)

� 2013 Sandia Corporation