BasicExtendedInterpreter (ScriptBasic for Java 1.0.0 API)

java.lang.Object
- com.scriptbasic.executors.BasicExtendedInterpreter

All Implemented Interfaces:: ExtendedInterpreter, FactoryManaged, Interpreter

public final class BasicExtendedInterpreter
extends Object
implements ExtendedInterpreter

Author:: Peter Verhas

Constructor Summary

Constructors
Constructor and Description

BasicExtendedInterpreter()

Constructors
Constructor and Description
`BasicExtendedInterpreter()`

Method Summary

Methods
Modifier and Type	Method and Description
`Object`	`call(String functionName, Object[] arguments)` Call a function defined by the program passing the objects as arguments.
`void`	`disableHook()` Temporarily disable the hooks.
`void`	`enableHook()` Enable the hook calls.
`void`	`execute()` Execute the program.
`void`	`execute(Command startCommand)` Execute the program.
`Configuration`	`getConfiguration()`
`Command`	`getCurrentCommand()` Get the command that is currently executing.
`Writer`	`getErrorWriter()` `ScriptContext.getReader()`
`Factory`	`getFactory()`
`InterpreterHook`	`getHook()` Get the hook object the interpreter has.
`Method`	`getJavaMethod(Class<?> klass, String methodName)` Get the method named from the klass based on the declaration given in a previously executed `METHOD` basic command.
`Map<String,Object>`	`getMap()` Since the Command objects should not contain runtime information there is a need sometime to store information that is runtime.
`BuildableProgram`	`getProgram()`
`Reader`	`getReader()` `ScriptContext.getReader()`
`RightValue`	`getReturnValue()` Get the return value that was set by the execution of the subroutine.
`CommandSub`	`getSubroutine(String name)` Get a subroutine by its name.
`Map<String,Class<?>>`	`getUseMap()` Programs can access Java static methods from different packages.
`Object`	`getVariable(String name)` Get the value of a global variable.
`HierarchicalVariableMap`	`getVariables()` Get the variables of the program.
`Writer`	`getWriter()` `ScriptContext.getWriter()`
`Command`	`pop()` Pop the command from the top of the stack and also drop the last local variables frame.
`void`	`push()` Same as `ExtendedInterpreter.push(Command)` and pushes the currently executing command on the stack.
`void`	`push(Command command)` Push a command to the stack.
`void`	`registerFunctions(Class<?> klass)` Register the functions defined in the class.
`void`	`registerHook(InterpreterHook hook)`
`void`	`registerJavaMethod(String alias, Class<?> klass, String methodName, Class<?>[] argumentTypes)` Register a BASIC function as Java method.
`void`	`setErrorWriter(Writer errorWriter)`
`void`	`setFactory(Factory factory)`
`void`	`setNextCommand(Command nextCommand)` Tell the interpreter that the next command to call is not the one that follows the actual command but rather the one specified by the argument.
`void`	`setProgram(BuildableProgram buildableProgram)` Set the program to execute.
`void`	`setReader(Reader reader)`
`void`	`setReturnValue(RightValue returnValue)` Register the return value.
`void`	`setVariable(String name, Object value)` Set the value of the global variable.
`void`	`setWriter(Writer writer)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - BasicExtendedInterpreter
```
public BasicExtendedInterpreter()
```
- Method Detail
  - getHook
```
public InterpreterHook getHook()
```
    Description copied from interface: ExtendedInterpreter
    
    Get the hook object the interpreter has.
    
    Specified by:
    
    getHook in interface ExtendedInterpreter
    
    Returns:
  - disableHook
```
public void disableHook()
```
    Description copied from interface: ExtendedInterpreter
    
    Temporarily disable the hooks. Following this call the hooks will not be called until the ExtendedInterpreter.enableHook() is called.
    Hook disabling was designed with the special case in mind when a hook wants to alter the return value returned from a subroutine. To do so the hook method has to invoke the ExtendedInterpreter.setReturnValue(RightValue) method, which was actually calling the hook. To avoid the infinite loop and not to confuse the other hook methods that are in the list sooner the hook method InterpreterHook.setReturnValue(RightValue) should first disable the hook mechanism, call back to the interpreter object and the enable the hook mechanism again.
    
    Specified by:
    
    disableHook in interface ExtendedInterpreter
  - enableHook
```
public void enableHook()
```
    Description copied from interface: ExtendedInterpreter
    
    Enable the hook calls. This method has to be called after the call to ExtendedInterpreter.disableHook() to enable again the calling mechanism.
    
    Specified by:
    
    enableHook in interface ExtendedInterpreter
  - registerHook
```
public void registerHook(InterpreterHook hook)
```
    Specified by:
    
    registerHook in interface Interpreter
  - getReader
```
public Reader getReader()
```
    Description copied from interface: ExtendedInterpreter
    
    ScriptContext.getReader()
    
    Specified by:
    
    getReader in interface ExtendedInterpreter
    
    Returns:
    the reader
  - setReader
```
public void setReader(Reader reader)
```
    Specified by:
    
    setReader in interface Interpreter
    
    Parameters:
    reader - the reader to set
    See Also:
    ScriptContext.setReader(java.io.Reader)
  - getWriter
```
public Writer getWriter()
```
    Description copied from interface: ExtendedInterpreter
    
    ScriptContext.getWriter()
    
    Specified by:
    
    getWriter in interface ExtendedInterpreter
    
    Returns:
    the writer
  - setWriter
```
public void setWriter(Writer writer)
```
    Specified by:
    
    setWriter in interface Interpreter
    
    Parameters:
    writer - the writer to set
    See Also:
    ScriptContext.setWriter(Writer)
  - getErrorWriter
```
public Writer getErrorWriter()
```
    Description copied from interface: ExtendedInterpreter
    
    ScriptContext.getReader()
    
    Specified by:
    
    getErrorWriter in interface ExtendedInterpreter
    
    Returns:
    the errorWriter
  - setErrorWriter
```
public void setErrorWriter(Writer errorWriter)
```
    Specified by:
    
    setErrorWriter in interface Interpreter
    
    Parameters:
    errorWriter - the errorWriter to set
    See Also:
    ScriptContext.setErrorWriter(Writer)
  - setProgram
```
public void setProgram(BuildableProgram buildableProgram)
```
    Description copied from interface: Interpreter
    
    Set the program to execute.
    
    Specified by:
    
    setProgram in interface Interpreter
  - getVariables
```
public HierarchicalVariableMap getVariables()
```
    Description copied from interface: ExtendedInterpreter
    
    Get the variables of the program.
    
    Specified by:
    
    getVariables in interface ExtendedInterpreter
    
    Returns:
    the variables.
  - getSubroutine
```
public CommandSub getSubroutine(String name)
```
    Description copied from interface: ExtendedInterpreter
    
    Get a subroutine by its name.
    
    Specified by:
    
    getSubroutine in interface ExtendedInterpreter
    
    Parameters:
    name - the name of the subroutine
    
    Returns:
    the "SUB" command that starts the subroutine
  - registerFunctions
```
public void registerFunctions(Class<?> klass)
```
    Description copied from interface: Interpreter
    
    Register the functions defined in the class. Functions that can be called from a BASIC program but implemented in Java are static methods that are registered for the interpreter. The easiest way to define these methods are to create a class and annotate the methods that serve as BASIC functions with the annotation @Function
    
    Specified by:
    
    registerFunctions in interface Interpreter
    
    Parameters:
    klass - the class the defines the functions.
  - execute
```
public void execute()
             throws ExecutionException
```
    Description copied from interface: Interpreter
    
    Execute the program.
    
    Specified by:
    
    execute in interface Interpreter
    
    Throws:
    
    ExecutionException
  - execute
```
public void execute(Command startCommand)
             throws ExecutionException
```
    Description copied from interface: ExtendedInterpreter
    
    Execute the program.
    
    Specified by:
    
    execute in interface ExtendedInterpreter
    
    Throws:
    
    ExecutionException
  - setVariable
```
public void setVariable(String name,
               Object value)
                 throws ExecutionException
```
    Description copied from interface: Interpreter
    
    Set the value of the global variable.
    
    Specified by:
    
    setVariable in interface Interpreter
    
    Parameters:
    name - the name of the global variable
    value - the value to be set
    
    Throws:
    
    ExecutionException
  - getVariable
```
public Object getVariable(String name)
                   throws ExecutionException
```
    Description copied from interface: Interpreter
    
    Get the value of a global variable. Since this is not a BASIC interpreter method, but rather a method that helps the embedding of the interpreter the returned value is a raw Java object and not a RightValue. Thus if the variable value is for example a BasicDoubleValue then the implementation should return a Double.
    
    Specified by:
    
    getVariable in interface Interpreter
    
    Parameters:
    name - the name of the variable
    
    Returns:
    the value of the variable
    
    Throws:
    
    ExecutionException
  - call
```
public Object call(String functionName,
          Object[] arguments)
```
    Description copied from interface: Interpreter
    
    Call a function defined by the program passing the objects as arguments.
    
    Specified by:
    
    call in interface Interpreter
    
    Parameters:
    functionName - the name of the function in the program code
    arguments - the arguments to the function
    
    Returns:
    the returned object, or null if the function does not return value
  - getProgram
```
public BuildableProgram getProgram()
```
    Specified by:
    
    getProgram in interface ExtendedInterpreter
    
    Returns:
    the program that the interpreter is executing.
  - setNextCommand
```
public void setNextCommand(Command nextCommand)
```
    Description copied from interface: ExtendedInterpreter
    
    Tell the interpreter that the next command to call is not the one that follows the actual command but rather the one specified by the argument.
    
    Specified by:
    
    setNextCommand in interface ExtendedInterpreter
    
    Parameters:
    nextCommand - is the next command to execute after the current command
  - getCurrentCommand
```
public Command getCurrentCommand()
```
    Description copied from interface: ExtendedInterpreter
    
    Get the command that is currently executing. This method is available for the code that are executing under some command. Typically a function call needs to know what command to push onto the call stack.
    
    Specified by:
    
    getCurrentCommand in interface ExtendedInterpreter
    
    Returns:
    the currently executing command
  - getMap
```
public Map<String,Object> getMap()
```
    Description copied from interface: ExtendedInterpreter
    
    Since the Command objects should not contain runtime information there is a need sometime to store information that is runtime. This method returns a map that is unique to the currently executing Command and is also unique to the Interpreter. Thus if two interpreters simultaneously execute the same command they will return two different maps.
    The interpreter initializes the map when the command asks for it the first time. The life time of the map is the same as the life time of the interpreter. Thus when a program finishes the map is still available to the command when the Interface 'call' method is called or the interpreter is restarted.
    The interpreter does not alter the map in any other way than initializing it to some map implementation containing initially no element.
    
    Specified by:
    
    getMap in interface ExtendedInterpreter
    
    Returns:
    the map
  - getFactory
```
public Factory getFactory()
```
    Returns:
    the factory
  - setFactory
```
public void setFactory(Factory factory)
```
    Specified by:
    
    setFactory in interface FactoryManaged
  - getUseMap
```
public Map<String,Class<?>> getUseMap()
```
    Description copied from interface: ExtendedInterpreter
    Programs can access Java static methods from different packages. To do that the programs have to recognize when the call 'out' to Java instead of looking for an internal function implemented in the program. For example the BASIC program has to declare the use of these packages using the command USE. For example
```
 use Math from java.lang as m
 
```
    (the part following the keyword 'as' is optional, in which case the Java name of the class is used). After this statement is executed the use map will contain the class javal.lang.Math for the key m.
    Specified by:
    
    getUseMap in interface ExtendedInterpreter
    
    Returns:
    the use map itself.
  - getJavaMethod
```
public Method getJavaMethod(Class<?> klass,
                   String methodName)
                     throws ExecutionException
```
    Description copied from interface: ExtendedInterpreter
    Get the method named from the klass based on the declaration given in a previously executed METHOD basic command. The basic command METHOD has the form (example follows):
```
 method sin from java.lang.Math is (double)
 
```
    that defines that the method sin is in the class java.lang.Math and accepts one argument, which is double
    Specified by:
    
    getJavaMethod in interface ExtendedInterpreter
    
    Returns:
    
    Throws:
    
    ExecutionException
  - registerJavaMethod
```
public void registerJavaMethod(String alias,
                      Class<?> klass,
                      String methodName,
                      Class<?>[] argumentTypes)
```
    Description copied from interface: ExtendedInterpreter
    Register a BASIC function as Java method. Java methods may be overloaded but BASIC functions can not. When a BASIC program wants to use a Java method it has to declare it as
```
 use class from package as basicClassReference
 
```
    for example
```
 use Math from java.lang as m
 
```
    when the method sin is used, foe example
```
 a = m.sin(1.0)
 
```
    the BASIC interpreter has to find the method java.lang.Math.sin(Double x). The problem is that the method does not exist because the argument is not Double but rather double.
    To help with this situation the BASIC program should declare the Java signature of the method using the BASIC command METHOD. For example:
```
 method sin from java.lang.Math is (double) use as sinus
 
```
    (Note that the part use as ... is optional.)
    After this command is executed the interpreter will use the defined signature to locate the method. You can write in the BASIC program
```
 a = m.sinus(1.0)
 
```
    registerJavaMethod() registers the basic function alias, class, java method name and the argument types so that later call to ExtendedInterpreter.getJavaMethod(Class, String) can find the appropriate method.
    Specified by:
    
    registerJavaMethod in interface ExtendedInterpreter
  - push
```
public void push(Command command)
```
    Description copied from interface: ExtendedInterpreter
    
    Push a command to the stack. This is called before a subroutine call is executed. Even though the actual stack is NOT maintained here but rather in the JVM call stack, since function call is implemented using recursive calls to the interpreter the call to this push and pop is vital to keep track the stack trace for debugging purposes and to have a mean to limit the stack size.
    Calling this method also starts a new local variable frame, thus evaluation of the actual argument values in a function call has to be executed before calling this method.
    
    Specified by:
    
    push in interface ExtendedInterpreter
    
    Parameters:
    command - the command from which a subroutine call was executed.
  - push
```
public void push()
```
    Description copied from interface: ExtendedInterpreter
    
    Same as ExtendedInterpreter.push(Command) and pushes the currently executing command on the stack.
    
    Specified by:
    
    push in interface ExtendedInterpreter
  - pop
```
public Command pop()
```
    Description copied from interface: ExtendedInterpreter
    
    Pop the command from the top of the stack and also drop the last local variables frame.
    
    Specified by:
    
    pop in interface ExtendedInterpreter
  - setReturnValue
```
public void setReturnValue(RightValue returnValue)
```
    Description copied from interface: ExtendedInterpreter
    
    Register the return value. This method is called from a subroutine.
    
    Specified by:
    
    setReturnValue in interface ExtendedInterpreter
    
    Parameters:
    returnValue - the value that the subroutine will return
  - getReturnValue
```
public RightValue getReturnValue()
```
    Description copied from interface: ExtendedInterpreter
    
    Get the return value that was set by the execution of the subroutine.
    
    Specified by:
    
    getReturnValue in interface ExtendedInterpreter
    
    Returns:
  - getConfiguration
```
public Configuration getConfiguration()
```
    Specified by:
    
    getConfiguration in interface ExtendedInterpreter

Class BasicExtendedInterpreter

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BasicExtendedInterpreter

Method Detail

getHook

disableHook

enableHook

registerHook

getReader

setReader

getWriter

setWriter

getErrorWriter

setErrorWriter

setProgram

getVariables

getSubroutine

registerFunctions

execute

execute

setVariable

getVariable

call

getProgram

setNextCommand

getCurrentCommand

getMap

getFactory

setFactory

getUseMap

getJavaMethod

registerJavaMethod

push

push

pop

setReturnValue

getReturnValue

getConfiguration