simkin
Class Interpreter

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

public class Interpreter
extends java.lang.Object
implements Executable

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


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 java.lang.String addStrings(java.lang.String one, java.lang.String two)
          Adds two strings together efficiently
static java.lang.String addStrings(java.lang.String one, java.lang.String two, java.lang.String three)
          Adds three strings together efficiently
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.
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 parse tree.
 java.lang.Object reflectiveGetValue(java.lang.Object owner, java.lang.String field_name)
          This function attempts to retrieve a public Java field using reflection
 java.lang.Object reflectiveMethodCall(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(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
 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:
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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,
                     java.lang.NoSuchFieldException
Used to set the "tracing" variable - for example in Simkin:

Interpreter.tracing=true;

Specified by:
setValue in interface Executable
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)
java.lang.NoSuchFieldException - - 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,
                               java.lang.NoSuchMethodException
The interpreter does not expose any methods to Simkin scripts
Specified by:
method in interface Executable
Following copied from interface: simkin.Executable
Parameters:
method_name - the name of the method
arguments - an array of arguments passed to the method
Returns:
the function's return value
Throws:
java.lang.RuntimeException - - if there was a problem running the script (such as divide by zero)
java.lang.NoSuchMethodException - - if the method could not be 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

getValue

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

tracing=Interpreter.tracing;

Specified by:
getValue in interface Executable
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)
java.lang.NoSuchFieldException - - 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 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
Parameters:
the - Interpeter that will be used to execute methods

reflectiveMethodCall

public java.lang.Object reflectiveMethodCall(java.lang.Object owner,
                                             java.lang.String method_name,
                                             java.lang.Object[] arguments)
                                      throws java.lang.RuntimeException,
                                             java.lang.NoSuchMethodException
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
java.lang.NoSuchMethodException - - if the method could not be found

reflectiveSetValue

public void reflectiveSetValue(java.lang.Object owner,
                               java.lang.String field_name,
                               java.lang.Object value)
                        throws java.lang.RuntimeException,
                               java.lang.NoSuchFieldException
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)
java.lang.NoSuchFieldException - - if the field could not be found

reflectiveGetValue

public java.lang.Object reflectiveGetValue(java.lang.Object owner,
                                           java.lang.String field_name)
                                    throws java.lang.RuntimeException,
                                           java.lang.NoSuchFieldException
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)
java.lang.NoSuchFieldException - - if the field could not be found

addStrings

public static java.lang.String addStrings(java.lang.String one,
                                          java.lang.String two)
Adds two strings together efficiently

addStrings

public static java.lang.String addStrings(java.lang.String one,
                                          java.lang.String two,
                                          java.lang.String three)
Adds three strings together efficiently