net.scheinerman.phoenix.interpreter
Class Interpreter

java.lang.Object
  extended by net.scheinerman.phoenix.interpreter.Interpreter
Direct Known Subclasses:
CatchInterpreter, Function, ImportInterpreter, InteractiveInterpreter, LoopInterpreter, SwitchInterpreter, TryInterpreter

public class Interpreter
extends java.lang.Object

Interprets a block of code and allocates variables and functions. This class provides basic parsing of Phoenix programs. This class is meant to be subclassed in order to provide more specific parsing capability.

Since:
1.5
Version:
1.0
Author:
Jonah Scheinerman

Field Summary
protected  boolean _break
          Indicates whether or not a break was encountered in this scope.
protected  boolean _continue
          Indicates whether or not a continue was encountered in this scope.
protected  boolean _return
          Indicates whether or not a return was encountered in this scope.
protected  int breakValue
          Indicates the value after a break statement that was called within this scope.
protected  java.lang.String code
          The raw code that is to be interpreted in this section.
protected  java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat
          The Function Allocation Table (FAT) stores functions and their values for all scopes of the interpretation process.
protected  java.lang.String file
          The path of the file that is being interpreted.
private  java.util.regex.Pattern identPattern
          Sets up a compiled pattern which is used to test the validity of function and variable identifiers.
 java.util.HashSet<java.lang.String> keywordList
          This set contains all the Phoenix keywords for cross referencing when testing whether a identifier for a function or a variable is valid.
protected  int line
          The current relative line that is being interpreted.
protected  int line_diff
          The amount of lines of code that were encountered before this interpretation.
protected  boolean printValues
          Indicates whether or not answer values should be printed to the screen.
protected  Variable retType
          A simple variable whose type indicates what the return type of this interpreter is.
protected  boolean retTypeSet
          Indicates whether or not the return type of this interpreter has been set.
protected  Variable retValue
          The value returned after a return statement.
protected  java.lang.String[] run_code
          The code to be interpreted broken into an array of strings by new line characters.
protected  boolean stop
          Indicates whether or not the interpretation should stop prematurely.
private  boolean topLevel
          Indicates whether or not this is a top level interpreter.
protected  java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat
          The Variable Allocation Table (VAT) stores variables and their values for all scopes of the interpretation process.
 
Constructor Summary
Interpreter()
          Instantiates a new Interpreter with no given code to interpret.
Interpreter(boolean topLevel, java.lang.String file, java.lang.String code, int line, java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat, java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat)
          Instantiates a new Interpreter that starts at some point in a file.
Interpreter(boolean topLevel, java.lang.String file, java.lang.String code, java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat, java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat)
          Instantiates a new Interpreter that starts at the beginning of a file.
 
Method Summary
private  void _break(java.lang.String code)
          Deals with what should happen if a break is encountered.
private  int _continue(int line)
          Deals with what should happen if a continue is encountered.
private  int _do(java.lang.String code, int line)
          Deals with what should happen if a do block is encountered.
private  int _for(java.lang.String code, int line)
          Deals with what should happen if a for block is encountered.
private  int _if(java.lang.String code, int line)
          Deals with what should happen if a if/else statement is encountered.
private  int _return(java.lang.String code, int line)
          Deals with what should happen if a return statement is encountered.
private  int _switch(java.lang.String code, int line)
          Deals with what should happen if a switch block is encountered.
private  void _throw(java.lang.String code)
           
private  int _try(int line)
           
private  int _while(java.lang.String trimmed, int line)
          Deals with what should happen if a while block is encountered.
protected  void dealWithBreak(int value)
          Deals with a break statement with a given integer value.
protected  int dealWithContinue(int line)
          Deals with a continue statement on a given line of code.
protected  void dealWithError(PhoenixRuntimeException e)
           
protected  void dealWithReturn(Variable passed)
          Deals with a return statement with a given variable that has been passed through the return statement.
 boolean delete(java.lang.String identifier)
          Deletes any instance of the use of the identifier from the VAT or FAT.
protected  void doRun()
          Does simple interpretation of the given code for this Interpreter class.
 java.lang.String getBlock(int start)
          Returns a block of code with greater indentation than the current block starting at the given line.
 Function getFunction(java.lang.String identifier)
          Returns the function from the FAT with the given identifier.
 java.lang.Object[][] getFunctionArguments(java.lang.String line)
           
 Function getFunctionFromDefinition(java.lang.String line, java.lang.String code, boolean nat, boolean setupDocs)
           
 Variable getReturnValue()
          Gets the variable returned by a return statement in this interpretation.
 Variable getVariable(java.lang.String identifier)
          Returns the variable with the given identifier.
static int getWhitespace(java.lang.String line)
          Returns the amount of whitespace prior to the code in a line of code.
private  void initKeywordList()
          Sets up the list of keywords in the language.
protected  void initNewTables()
          Creates a new VAT and a new FAT and adds them to the front of the overall VAT queue and FAT queue.
 boolean isValidIdentifier(java.lang.String identifier)
          Determines whether or not a given identifier is a valid variable or function identifier in the current scope.
static Variable makeDefaultVariable(java.lang.String type)
          Creates an empty variable (using that variable's default constructor) given the identifier of the variable.
 int makeFunction(java.lang.String line, java.lang.String code, java.lang.String prefix)
          Creates a Function based on the given line of code and adds it to the appropriate place in the FAT.
 void makeVariable(java.lang.String code)
          Creates a variable and adds it to the appropriate VAT based on a line of code.
 Variable makeVariable(java.lang.String type, Variable value)
          Given a variable type and a value, creates a Variable object with that value.
 Variable parsePhrase(java.lang.String phrase)
          Returns the variable equivalent of a line of code.
 void putFunction(Function f, java.util.HashMap<java.lang.String,Function> hm)
          Adds a function to the FAT if it has a valid identifier.
static java.lang.String removeComments(java.lang.String line)
          Returns a version of the string with the comments stripped from it.
static void removeWhitespace(java.lang.String code)
          Strips a string of code of any extraneous whitespace outside of quotes within that string.
protected  boolean retValueMatches()
          Tests whether or not the value returned by a return has the same type as the predetermined return value type for a function.
 void run()
          Begins the interpretation process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

file

protected java.lang.String file
The path of the file that is being interpreted. This field is used when in the output of error messages.


topLevel

private boolean topLevel
Indicates whether or not this is a top level interpreter. If it is, this is used to throw errors on break, continue, and return statements.


retTypeSet

protected boolean retTypeSet
Indicates whether or not the return type of this interpreter has been set. This is used in the Function class.


retType

protected Variable retType
A simple variable whose type indicates what the return type of this interpreter is. This is used in the Function class to determine whether the returned variable is of the correct type. If this is an instance of NumberVariable the return type is num. If it is an instance of StringVariable the return type is str. If this is null, then the return type is void.


retValue

protected Variable retValue
The value returned after a return statement. This must match in type with the field retType . This is used in the Function class.


printValues

protected boolean printValues
Indicates whether or not answer values should be printed to the screen. This is true for interactive Phoenix sessions.


breakValue

protected int breakValue
Indicates the value after a break statement that was called within this scope.


_break

protected boolean _break
Indicates whether or not a break was encountered in this scope.


_continue

protected boolean _continue
Indicates whether or not a continue was encountered in this scope.


_return

protected boolean _return
Indicates whether or not a return was encountered in this scope.


stop

protected boolean stop
Indicates whether or not the interpretation should stop prematurely.


line

protected int line
The current relative line that is being interpreted. This starts at 0.


line_diff

protected int line_diff
The amount of lines of code that were encountered before this interpretation. This is used to report error messages.


code

protected java.lang.String code
The raw code that is to be interpreted in this section.


run_code

protected java.lang.String[] run_code
The code to be interpreted broken into an array of strings by new line characters.


vat

protected java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat
The Variable Allocation Table (VAT) stores variables and their values for all scopes of the interpretation process. Each element of the list is a new scope. Each element is a map from the identifier of a variable to its Variable class equivalent. The last element of the list is the global scope, the second to the last is the top-level local scope. The front element of the list is the the most local scope.


fat

protected java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat
The Function Allocation Table (FAT) stores functions and their values for all scopes of the interpretation process. Each element of the list is a new scope. Each element is a map from the identifier of a function to its Function class equivalent. The last element of the list is the global scope, the second to the last is the top-level local scope. The front element of the list is the the most local scope.


keywordList

public java.util.HashSet<java.lang.String> keywordList
This set contains all the Phoenix keywords for cross referencing when testing whether a identifier for a function or a variable is valid. This set is initialized by the private initKeywordList() method in the constructors of this class.


identPattern

private java.util.regex.Pattern identPattern
Sets up a compiled pattern which is used to test the validity of function and variable identifiers. This pattern tests to see that the only characters in a string are either alphanumeric characters or underscores.

Constructor Detail

Interpreter

public Interpreter()
Instantiates a new Interpreter with no given code to interpret. The interpretation cannot be started using run().


Interpreter

public Interpreter(boolean topLevel,
                   java.lang.String file,
                   java.lang.String code,
                   java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat,
                   java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat)
Instantiates a new Interpreter that starts at the beginning of a file. The constructor is given the file of input, the code, the variable and function allocation tabes.

Parameters:
topLevel - - This is true if this interpreter is on the top level scope of the file, false otherwise.
file - - The relative path of the file of input. Used for error message outputs.
code - - The code contained in the file. If this is a top-level interpretation, this should be the entire contents of the file. Otherwise, it should be the section of the file meant to be interpreted.
vat - - The Variable Allocation Table (VAT) for this interpretation. If this is a top-level interpretation, this should only contain a table for global variables.
fat - - The Function Allocation Table (FAT) for this interpretation. If this is a top-level interpretation, this should only contain a table for global functions.

Interpreter

public Interpreter(boolean topLevel,
                   java.lang.String file,
                   java.lang.String code,
                   int line,
                   java.util.LinkedList<java.util.HashMap<java.lang.String,Variable>> vat,
                   java.util.LinkedList<java.util.HashMap<java.lang.String,Function>> fat)
Instantiates a new Interpreter that starts at some point in a file. The location in the file is determined by the value of the line parameter, and the contents of the code parameter.

Parameters:
topLevel - - This is true if this interpreter is on the top level scope of the file, false otherwise.
file - - The relative path of the file of input. Used for error message outputs.
code - - The code contained in the file. If this is a top-level interpretation, this should be the entire contents of the file. Otherwise, it should be the section of the file meant to be interpreted.
line - - The starting line of this interpretation.
vat - - The Variable Allocation Table (VAT) for this interpretation. If this is a top-level interpretation, this should only contain a table for global variables.
fat - - The Function Allocation Table (FAT) for this interpretation. If this is a top-level interpretation, this should only contain a table for global functions.
Method Detail

initKeywordList

private final void initKeywordList()
Sets up the list of keywords in the language. This is used to cross-reference when checking the validity of a variable or function identifier.


initNewTables

protected final void initNewTables()
Creates a new VAT and a new FAT and adds them to the front of the overall VAT queue and FAT queue. This effectively creates a new scope in which the current interpreter operates. These new tables are created at the beginning of the interpretation and are destroyed at the end, thus going in andout of this scope.


run

public void run()
Begins the interpretation process. This method only calls the doRun() method and then removes the front entries of the VAT and FAT queues. If the interpreter class is to be subclassed, this method should be overridden to provide surrounding functionality to the doRun() method.


doRun

protected void doRun()
Does simple interpretation of the given code for this Interpreter class. For most subclasses,this method should not be overridden. However, there are some instances where it might prove useful to override this method (for example, the SwitchInterpreter class overrides this method).

See Also:
SwitchInterpreter}

dealWithError

protected void dealWithError(PhoenixRuntimeException e)

retValueMatches

protected boolean retValueMatches()
Tests whether or not the value returned by a return has the same type as the predetermined return value type for a function. This method is only used by Interpreters that are within the scope of a function.

Returns:
true if the types match, false otherwise.

putFunction

public final void putFunction(Function f,
                              java.util.HashMap<java.lang.String,Function> hm)
Adds a function to the FAT if it has a valid identifier. If the function has a valid identifier, it will be added to the given table.

Parameters:
f - - The function to add to the table.
hm - - The table the function will be added to.
Throws:
IllegalIdentifierException - if the identifier is invalid, as determined by the isValidIdentifier() method.

removeComments

public static final java.lang.String removeComments(java.lang.String line)
Returns a version of the string with the comments stripped from it.

Returns:
the string without comments.

parsePhrase

public final Variable parsePhrase(java.lang.String phrase)
Returns the variable equivalent of a line of code. This method calls an arithmetic parsing of the code phrase using the Parser class.

Parameters:
phrase - - a phrase of code
Returns:
a variable returned from the parsing of that code.

_break

private void _break(java.lang.String code)
Deals with what should happen if a break is encountered.

Parameters:
code - - The code of the break statement.

_continue

private int _continue(int line)
Deals with what should happen if a continue is encountered.

Parameters:
line - - The number of the line on which the continue is encountered.
Returns:
The line that should next be executed after this continue statement.

_do

private int _do(java.lang.String code,
                int line)
Deals with what should happen if a do block is encountered.

Parameters:
code - - The code of the line containing the do statement.
line - - The number of the line on which the do statement is encountered.
Returns:
The line that should next be executed after this do block.
Throws:
SyntaxException - if there is no colon at the end of the statement.

_for

private int _for(java.lang.String code,
                 int line)
Deals with what should happen if a for block is encountered.

Parameters:
code - - The code of the line containing the for statement.
line - - The number of the line on which the for statement is encountered.
Returns:
The line that should next be executed after this for block.
Throws:
SyntaxException - if there is no colon at the end of the statement.

_if

private int _if(java.lang.String code,
                int line)
Deals with what should happen if a if/else statement is encountered.

Parameters:
code - - The code of the line containing the if/else statement.
line - - The number of the line on which the if/ese statement is encountered.
Returns:
The line that should next be executed after this if/else block.
Throws:
SyntaxException - if there is no colon at the end of the statement.

_return

private int _return(java.lang.String code,
                    int line)
Deals with what should happen if a return statement is encountered.

Parameters:
code - - The code of the line containing the return statement.
line - - The number of the line on which the return statement is encountered.
Returns:
The line that should next be executed after this return statement.

_switch

private int _switch(java.lang.String code,
                    int line)
Deals with what should happen if a switch block is encountered.

Parameters:
code - - The code of the line containing the switch statement.
line - - The number of the line on which the switch statement is encountered.
Returns:
The line that should next be executed after this switch block.
Throws:
SyntaxException - if there is no colon at the end of the statement.

_throw

private void _throw(java.lang.String code)

_try

private int _try(int line)

_while

private int _while(java.lang.String trimmed,
                   int line)
Deals with what should happen if a while block is encountered.

Parameters:
code - - The code of the line containing the while statement.
line - - The number of the line on which the while statement is encountered.
Returns:
The line that should next be executed after this while block.
Throws:
SyntaxException - if there is no colon at the end of the statement.

dealWithBreak

protected void dealWithBreak(int value)
Deals with a break statement with a given integer value. This method is meant to be overridden in subclasses if subclasses deal with breaks differently. For example, this class just passes the break up to the Interpreter of greater scope. However, subclasses of LoopInterpreter subtract one from the break value and pass it up if it is greater than zero.

Parameters:
value - - The number of breaks that should be executed.
Throws:
SyntaxException - if this is a top level interpretation or the value is less than or equal to zero.

dealWithContinue

protected int dealWithContinue(int line)
Deals with a continue statement on a given line of code. This method is meant to be overridden in subclasses where continues make a difference. For example, LoopInterpreter classes override this method to perform their specific continue action.

Parameters:
line - - The number of the line on which the continue is encountered.
Returns:
The line that should be interpreted next after the continue.
Throws:
SyntaxException - if this is a top level interpretation.

dealWithReturn

protected void dealWithReturn(Variable passed)
Deals with a return statement with a given variable that has been passed through the return statement. If no variable was passed, the parameter should just be left as null.

Parameters:
passed - - The variable passed via the return statement.
Throws:
SyntaxException - - if this is a top level interpretation.

getBlock

public final java.lang.String getBlock(int start)
Returns a block of code with greater indentation than the current block starting at the given line.

Parameters:
start - - The number of the line to start on.
Returns:
A block of code, delimited by newlines.

makeFunction

public final int makeFunction(java.lang.String line,
                              java.lang.String code,
                              java.lang.String prefix)
Creates a Function based on the given line of code and adds it to the appropriate place in the FAT.

Parameters:
line - - The line of code to create the function from.
code - - The code that the function will run.
prefix - - Any prefix to the functions name that might be appended. This is used for imported functions.

getFunctionFromDefinition

public final Function getFunctionFromDefinition(java.lang.String line,
                                                java.lang.String code,
                                                boolean nat,
                                                boolean setupDocs)

makeVariable

public final void makeVariable(java.lang.String code)
Creates a variable and adds it to the appropriate VAT based on a line of code.

Parameters:
code - - A line of code.

makeVariable

public final Variable makeVariable(java.lang.String type,
                                   Variable value)
Given a variable type and a value, creates a Variable object with that value.

Parameters:
type - - The type of value. This must be either num or str.
value - - The value to assign to that variable type.
Returns:
The created variable.

makeDefaultVariable

public static final Variable makeDefaultVariable(java.lang.String type)
Creates an empty variable (using that variable's default constructor) given the identifier of the variable. The type must be either "num," "str," or "void." If the type is "void" the return variable will be null.

Parameters:
name - - The variable identifier
Returns:
A variable, or null if "void."

isValidIdentifier

public final boolean isValidIdentifier(java.lang.String identifier)
Determines whether or not a given identifier is a valid variable or function identifier in the current scope. This tests to see if the variable or function name is already taken, if it intersects with a keyword, or if it contains any illegal characters.

Parameters:
identifier - - A variable or function identifier.
Returns:
true if it is valid, false otherwise.

getFunction

public final Function getFunction(java.lang.String identifier)
Returns the function from the FAT with the given identifier. If no such function exists, a null value will be returned.

Parameters:
identifier - - The identifier of the desired function.
Returns:
The corresponding function, or null if no such identifier is taken for a function.

getVariable

public final Variable getVariable(java.lang.String identifier)
Returns the variable with the given identifier. If no variable with that identifier exists, a null value is returned.

Parameters:
identifier - - The identifier of the desired variable.
Returns:
The corresponding variable, or null if no such identifier is taken for a variable.

delete

public final boolean delete(java.lang.String identifier)
Deletes any instance of the use of the identifier from the VAT or FAT. If any variable or any function exists with the given identifier, it will be removed and discarded.

Parameters:
identifier - - The identifier of a variable or function to be deleted.
Returns:
true if the identifier is in use and has been deleted, false otherwise.

getFunctionArguments

public final java.lang.Object[][] getFunctionArguments(java.lang.String line)

getWhitespace

public static final int getWhitespace(java.lang.String line)
Returns the amount of whitespace prior to the code in a line of code.

Parameters:
line - - A line of code.
Returns:
The amount of leading whitespace.

removeWhitespace

public static final void removeWhitespace(java.lang.String code)
Strips a string of code of any extraneous whitespace outside of quotes within that string.

Parameters:
code - - The code to be stripped of whitespace.

getReturnValue

public final Variable getReturnValue()
Gets the variable returned by a return statement in this interpretation.

Returns:
The returned variable.