simkin
Class Interpreter

java.lang.Object
  |
  +--simkin.ExecutableRoot
        |
        +--simkin.Interpreter
All Implemented Interfaces:
Executable

public class Interpreter
extends ExecutableRoot

This class represents the Simkin interpreter. The interpreter can load, parse and interpret Simkin code.

The Interpreter maintains a list of global variables. This maps names to objects, which are available to all Simkin scripts.

The interpreter itself is a global object with the name "Interpreter".

The Interpreter implements the Executable interface, supports the single field "tracing" which enables/disables tracing of method calls

New from Simkin 1.16: by default a different instance of the Interpreter is created for each thread. This can be overriden with the setInterpreterPerThread method


Field Summary
static java.lang.Boolean g_False
          false object
static Null g_null
          the null object
static java.lang.Boolean g_True
          true object
static java.lang.Integer g_Zero
          zero object
 
Constructor Summary
Interpreter()
          Default constructor - adds a global variable pointing to this interpreter
 
Method Summary
 void addGlobalVariable(java.lang.String name, java.lang.Object r)
          Adds a global variable to the current list
static boolean boolValue(java.lang.Object value)
          This method converts the given value into a boolean value
 java.lang.Object executeParseTree(java.lang.String location, java.lang.Object obj, ParseNode parseNode, java.lang.Object[] args)
          This method executes a piece of Simkin code from a parse tree.
 ExecuteResult executeString(java.lang.String location, java.lang.Object obj, java.lang.String code, java.lang.Object[] args)
          This method executes a piece of Simkin code within a string
 ExecuteResult executeStringExternalParams(java.lang.String location, java.lang.Object obj, java.util.Vector paramNames, java.lang.String code, java.lang.Object[] args)
          This method executes a piece of Simkin code within a string, it assumes that the parameters have been defined outside the statement block.
 java.lang.Object findGlobalVariable(java.lang.String name)
          looks for the given global variable.
static double floatValue(java.lang.Object value)
          This method converts the given value into a double value
static Interpreter getInterpreter()
          This method returns the global interpreter associated with all method calls.
 java.lang.Object getValue(java.lang.String field_name, java.lang.String attrib)
          Returns the value of the "tracing" variable - e.g.
 java.lang.Object getValueAt(java.lang.Object index, java.lang.String attrib_name)
          Returns null - this is not a collection
static int intValue(java.lang.Object value)
          This method converts the given value into an integer value
 java.lang.Object method(java.lang.String method_name, java.lang.Object[] args)
          The interpreter does not expose any methods to Simkin scripts
 ParseNode parse(java.lang.String location, java.lang.String code)
          This method parses a string full of Simkin code and returns the parse tree.
 ParseNode parseExternalParams(java.lang.String location, java.util.Vector paramNames, java.lang.String code)
          This method parses a string of Simkin statements, excluding parameters and enclosing braces.
 java.lang.Object reflectiveGetValue(simkin.Context ctxt, java.lang.Object owner, java.lang.String field_name)
          This function attempts to retrieve a public Java field using reflection
 java.lang.Object reflectiveMethodCall(simkin.Context ctxt, java.lang.Object owner, java.lang.String method_name, java.lang.Object[] arguments)
          This function attempts to make a public method call on a Java object by using reflection
 void reflectiveSetValue(simkin.Context ctxt, java.lang.Object owner, java.lang.String field_name, java.lang.Object value)
          This function attempts to set a public Java field using reflection
 void removeGlobalVariable(java.lang.String name)
          Removes a global variable from the current list
static void runtimeError(java.lang.String buffer)
          this method is called when there is a runtime error and throws a RuntimeException
static void setInterpreter(Interpreter i)
          Sets a global interpreter to be used for method calls - you can use this to override the Interpreter with your own derived classes.
static void setInterpreterPerThread(boolean flag)
          This method enables or disables the interpreter-per-thread feature.
 void setStatementStepper(StatementStepper stepper)
          this method sets an object to be called each time a statement is executed.
 void setTraceCallback(TraceCallback cb)
          this method sets an object to receive trace messages.
 void setValue(java.lang.String field_name, java.lang.String attrib, java.lang.Object value)
          Used to set the "tracing" variable - for example in Simkin:
 void setValueAt(java.lang.Object index, java.lang.String attrib_name, java.lang.Object value)
          Does nothing - this is not a collection
 
Methods inherited from class simkin.ExecutableRoot
createIterator, createIterator
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

g_null

public static final Null g_null
the null object

g_True

public static final java.lang.Boolean g_True
true object

g_False

public static final java.lang.Boolean g_False
false object

g_Zero

public static final java.lang.Integer g_Zero
zero object
Constructor Detail

Interpreter

public Interpreter()
Default constructor - adds a global variable pointing to this interpreter
Method Detail

setValue

public void setValue(java.lang.String field_name,
                     java.lang.String attrib,
                     java.lang.Object value)
              throws java.lang.RuntimeException,
                     FieldNotSupportedException
Used to set the "tracing" variable - for example in Simkin:

Interpreter.tracing=true;

Overrides:
setValue in class ExecutableRoot
Following copied from interface: simkin.Executable
Parameters:
field_name - the name of the field
attrib_name - the name of the attribute to be set (can be null)
value - the value to be set
Throws:
java.lang.RuntimeException - - if there was a problem running the script (such as not having permission to access a field)
FieldNotSupportedException - - if the field could not be found

method

public java.lang.Object method(java.lang.String method_name,
                               java.lang.Object[] args)
                        throws java.lang.RuntimeException,
                               ParseException,
                               MethodNotSupportedException
The interpreter does not expose any methods to Simkin scripts
Overrides:
method in class ExecutableRoot
Following copied from class: simkin.ExecutableRoot
Returns:
true if the method is found

boolValue

public static boolean boolValue(java.lang.Object value)
This method converts the given value into a boolean value

If the object is an instance of Boolean, the boolean value is returned, otherwise toString() is called, and compared with "true"

Returns:
the boolean equivalent of the object

intValue

public static int intValue(java.lang.Object value)
This method converts the given value into an integer value

If the object is an instance of Integer, the integer value is returned, otherwise toString() is called, and converted to an integer

Returns:
the integer equivalent of the object

floatValue

public static double floatValue(java.lang.Object value)
This method converts the given value into a double value

If the object is an instance of Double, the integer value is returned, otherwise toString() is called, and converted to a double

Returns:
the double equivalent of the object

getValueAt

public java.lang.Object getValueAt(java.lang.Object index,
                                   java.lang.String attrib_name)
                            throws java.lang.RuntimeException
Returns null - this is not a collection
Overrides:
getValueAt in class ExecutableRoot
Following copied from interface: simkin.Executable
Parameters:
array_index - an object whose value indicates the index of the item in the collection
attrib_name - attribute name (null if no attribute specified)
Returns:
the value of the object (null if not present)
Throws:
java.lang.RuntimeException - - if there was a problem running the script
FieldNotSupportedException - - if the field could not be found

setValueAt

public void setValueAt(java.lang.Object index,
                       java.lang.String attrib_name,
                       java.lang.Object value)
                throws java.lang.RuntimeException
Does nothing - this is not a collection
Overrides:
setValueAt in class ExecutableRoot
Following copied from interface: simkin.Executable
Parameters:
array_index - an object whose value indicates the index of the item in the collection
attrib_name - the name of the attribute to be set (can be null)
value - the value to be set
Throws:
java.lang.RuntimeException - - if there was a problem running the script

getValue

public java.lang.Object getValue(java.lang.String field_name,
                                 java.lang.String attrib)
                          throws java.lang.RuntimeException,
                                 FieldNotSupportedException
Returns the value of the "tracing" variable - e.g. in Simkin:

tracing=Interpreter.tracing;

Overrides:
getValue in class ExecutableRoot
Following copied from interface: simkin.Executable
Parameters:
field_name - the name of the field
attrib_name - attribute name (null if no attribute specified)
Returns:
the value of the field (or null, if the field is not supported)
Throws:
java.lang.RuntimeException - - if there was a problem running the script (such as not having permission to access a field)
FieldNotSupportedException - - if the field could not be found

findGlobalVariable

public java.lang.Object findGlobalVariable(java.lang.String name)
looks for the given global variable.
Parameters:
name - - the name of the global variable
Returns:
the object found, or null if the global variable is undefined

addGlobalVariable

public void addGlobalVariable(java.lang.String name,
                              java.lang.Object r)
Adds a global variable to the current list
Parameters:
name - - the name of the global variable, if one already exists it is replaced
r - - the object to be added to the list

removeGlobalVariable

public void removeGlobalVariable(java.lang.String name)
Removes a global variable from the current list
Parameters:
name - - the name of the global variable to be removed

parse

public ParseNode parse(java.lang.String location,
                       java.lang.String code)
                throws ParseException
This method parses a string full of Simkin code and returns the parse tree. If a parse error occurs, a ParseException is thrown

For example the following string could be passed:

(a,b){
a=b+1;
return a;
}
Parameters:
location - used to help identify the code in error messages
code - a string containing the Simkin code
Returns:
a ParseNode representing the parse tree for the code

parseExternalParams

public ParseNode parseExternalParams(java.lang.String location,
                                     java.util.Vector paramNames,
                                     java.lang.String code)
                              throws ParseException
This method parses a string of Simkin statements, excluding parameters and enclosing braces. The method returns a parse tree. If a parse error occurs, a ParseException is thrown

For example the following string could be passed (note the absence of enclosing braces around the statement list):

a=b+1;
return a;
Parameters:
location - used to help identify the code in error messages
paramNames - a vector of names for the parameters
code - a string containing the Simkin code
Returns:
a ParseNode representing the parse tree for the code

executeString

public ExecuteResult executeString(java.lang.String location,
                                   java.lang.Object obj,
                                   java.lang.String code,
                                   java.lang.Object[] args)
                            throws java.lang.RuntimeException,
                                   ParseException
This method executes a piece of Simkin code within a string

For example the following string could be passed:

(a,b){
a=b+1;
return a;
}
Parameters:
location - a name used to identify the code in error messages
obj - the object within whose context the code will execute
code - a string containing some Simkin code
args - and array of RValue arguments to the code
Returns:
returns an object containing the result of the method and the parse tree for the method, which can be safely cached
Throws:
ParseException - this is thrown if there is a syntax error in the code
java.lang.RuntimeException - this is thrown if there is an error during the execution of the code (such as method or field not found)

executeStringExternalParams

public ExecuteResult executeStringExternalParams(java.lang.String location,
                                                 java.lang.Object obj,
                                                 java.util.Vector paramNames,
                                                 java.lang.String code,
                                                 java.lang.Object[] args)
                                          throws java.lang.RuntimeException,
                                                 ParseException
This method executes a piece of Simkin code within a string, it assumes that the parameters have been defined outside the statement block.

For example the following string could be passed (note the absence of enclosing braces around the statement list):

a=b+1;
return a;
Parameters:
location - a name used to identify the code in error messages
obj - the object within whose context the code will execute
paramNames - a vector of names for the parameters
code - a string containing some Simkin code
args - and array of RValue arguments to the code
Returns:
returns an object containing the result of the method and the parse tree for the method, which can be safely cached
Throws:
ParseException - this is thrown if there is a syntax error in the code
java.lang.RuntimeException - this is thrown if there is an error during the execution of the code (such as method or field not found)

executeParseTree

public java.lang.Object executeParseTree(java.lang.String location,
                                         java.lang.Object obj,
                                         ParseNode parseNode,
                                         java.lang.Object[] args)
                                  throws java.lang.RuntimeException,
                                         ParseException
This method executes a piece of Simkin code from a parse tree.

You can call this with a parse tree produced by parse, parseExternalParams,executeString or executeStringExternalParams. This can be useful for caching parse trees to improve performance.

Parameters:
location - a name used to identify the code in error messages
obj - the object within whose context the code will execute
parseNode - a pre-parsed tree of Simkin code
args - and array of RValue arguments to the code
Throws:
ParseException - this is thrown if there is a syntax error in the code
java.lang.RuntimeException - this is thrown if there is an error during the execution of the code (such as method or field not found)

runtimeError

public static void runtimeError(java.lang.String buffer)
                         throws java.lang.RuntimeException
this method is called when there is a runtime error and throws a RuntimeException

getInterpreter

public static Interpreter getInterpreter()
This method returns the global interpreter associated with all method calls.
Returns:
the Interpeter that will be used to execute methods

setInterpreter

public static void setInterpreter(Interpreter i)
Sets a global interpreter to be used for method calls - you can use this to override the Interpreter with your own derived classes. If the interpreter-per-thread feature is used, then the interpreter is set only for the current thread.
Parameters:
the - Interpeter that will be used to execute methods - pass null to clear the current value

setInterpreterPerThread

public static void setInterpreterPerThread(boolean flag)
This method enables or disables the interpreter-per-thread feature.

If the feature is enabled, there is one interpreter for each thread. Calls to getInterpreter() will return the Interpreter defined for the current thread - or create one if one hasn't been encountered yet.

The default value for this is true.

Parameters:
flag - true/false to enable or disable the feature

setTraceCallback

public void setTraceCallback(TraceCallback cb)
this method sets an object to receive trace messages. Pass 0 to fall back to standard mechanism (using Tracer)

setStatementStepper

public void setStatementStepper(StatementStepper stepper)
this method sets an object to be called each time a statement is executed.

reflectiveMethodCall

public java.lang.Object reflectiveMethodCall(simkin.Context ctxt,
                                             java.lang.Object owner,
                                             java.lang.String method_name,
                                             java.lang.Object[] arguments)
                                      throws java.lang.RuntimeException,
                                             MethodNotSupportedException
This function attempts to make a public method call on a Java object by using reflection
Parameters:
owner - - the object to call a method on
method_name - - the name of the method to call
arguments - - the method arguments - types Integer, Double, Boolean and Character are converted to their primitive types
Returns:
the result of the method call
Throws:
java.lang.RuntimeException - - if the method could not be called
MethodNotSupportedException - - if the method could not be found

reflectiveSetValue

public void reflectiveSetValue(simkin.Context ctxt,
                               java.lang.Object owner,
                               java.lang.String field_name,
                               java.lang.Object value)
                        throws java.lang.RuntimeException,
                               FieldNotSupportedException
This function attempts to set a public Java field using reflection
Parameters:
owner - - the object owning the field
field_name - - the name of the field
value - - the value to assign to the field
Throws:
java.lang.RuntimeException - - if the field could not be set (e.g. if it was private)
FieldNotSupportedException - - if the field could not be found

reflectiveGetValue

public java.lang.Object reflectiveGetValue(simkin.Context ctxt,
                                           java.lang.Object owner,
                                           java.lang.String field_name)
                                    throws java.lang.RuntimeException,
                                           FieldNotSupportedException
This function attempts to retrieve a public Java field using reflection
Parameters:
owner - - the object owning the field
field_name - - the name of the field
Returns:
the value of the field
Throws:
java.lang.RuntimeException - - if the field could not be retrieved (e.g. if it was private)
FieldNotSupportedException - - if the field could not be found