com.scriptbasic.interfaces

Interface ExtendedInterpreter

All Superinterfaces:

FactoryManaged, Interpreter

All Known Implementing Classes:

BasicExtendedInterpreter

public interface ExtendedInterpreter
extends Interpreter

The extended interpreter is the interface that extends the functions of the Interpreter with the methods that are needed by the command implementations but are not needed by the program that embeds the interpreter.

Author:

Peter Verhas

Method Summary

Methods

Modifier and Type	Method and Description
void	disableHook() Temporarily disable the hooks.
void	enableHook() Enable the hook calls.
void	execute(Command startCommand) Execute the program starting at the command startCommand
Configuration	getConfiguration()
Command	getCurrentCommand() Get the command that is currently executing.
Writer	getErrorWriter() ScriptContext.getReader()
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.
HierarchicalVariableMap	getVariables() Get the global 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 push(Command) and pushes the currently executing command on the stack.
void	push(Command command) Push a command to the stack.
void	registerJavaMethod(String alias, Class<?> klass, String methodName, Class<?>[] argumentTypes) Register a BASIC function as Java method.
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	setReturnValue(RightValue returnValue) Register the return value.

Methods inherited from interface com.scriptbasic.interfaces.Interpreter

call, execute, getVariable, registerFunctions, registerHook, setErrorWriter, setProgram, setReader, setVariable, setWriter

Methods inherited from interface com.scriptbasic.interfaces.FactoryManaged

setFactory

Method Detail

getConfiguration

Configuration getConfiguration()

getProgram

BuildableProgram getProgram()

Returns:

the program that the interpreter is executing.

execute

void execute(Command startCommand)
             throws ExecutionException

Execute the program starting at the command startCommand

Throws:

ExecutionException

getSubroutine

CommandSub getSubroutine(String name)

Get a subroutine by its name.

Parameters:

name - the name of the subroutine

Returns:

the "SUB" command that starts the subroutine

setReturnValue

void setReturnValue(RightValue returnValue)

Register the return value. This method is called from a subroutine.

Parameters:

returnValue - the value that the subroutine will return

getReturnValue

RightValue getReturnValue()

Get the return value that was set by the execution of the subroutine.

Returns:

push

void push(Command command)

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.

Parameters:

command - the command from which a subroutine call was executed.

push

void push()

Same as push(Command) and pushes the currently executing command on the stack.

pop

Command pop()

Pop the command from the top of the stack and also drop the last local variables frame.

setNextCommand

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.

Parameters:

nextCommand - is the next command to execute after the current command

getCurrentCommand

Command getCurrentCommand()

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.

Returns:

the currently executing command

getVariables

HierarchicalVariableMap getVariables()

Get the global variables of the program.

Returns:

the variables.

getMap

Map<String,Object> getMap()

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.

Returns:

the map

getUseMap

Map<String,Class<?>> getUseMap()

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.

Returns:

the use map itself.

registerJavaMethod

void registerJavaMethod(String alias,
                      Class<?> klass,
                      String methodName,
                      Class<?>[] argumentTypes)
                        throws BasicRuntimeException

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 getJavaMethod(Class, String) can find the appropriate method.

Parameters:

klass -

methodName -

argumentTypes -

Throws:

BasicRuntimeException

getJavaMethod

Method getJavaMethod(Class<?> klass,
                   String methodName)
                     throws ExecutionException

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

Parameters:

klass -

mehodName -

Returns:

Throws:

ExecutionException

getReader

Reader getReader()

ScriptContext.getReader()

getWriter

Writer getWriter()

ScriptContext.getWriter()

getErrorWriter

Writer getErrorWriter()

ScriptContext.getReader()

Returns:

disableHook

void disableHook()

Temporarily disable the hooks. Following this call the hooks will not be called until the 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 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.

enableHook

void enableHook()

Enable the hook calls. This method has to be called after the call to disableHook() to enable again the calling mechanism.

getHook

InterpreterHook getHook()

Get the hook object the interpreter has.

Returns: