Package com.scriptbasic.spi

Interface Interpreter

All Superinterfaces:
InternalInterpreter
All Known Implementing Classes:
BasicInterpreter
public interface Interpreter extends InternalInterpreter
An interpreter instance executes a program.
Author:
Peter Verhas

  • Method Details

    • registerHook

      void registerHook(InterpreterHook hook)

    • execute

      void execute() throws ScriptBasicException
      Execute the program.
      Throws:
      ScriptBasicException - in case of exception

    • setVariable

      void setVariable(String name, Object value) throws ScriptBasicException
      Set the value of the variable. If the program is in a local scope and there is a variable with the given name in the local scope then the value of that variable is set, even if there is a global variable with that name.
      Parameters:
      name - the name of the global variable
      value - the value to be set
      Throws:
      ScriptBasicException - in case of exception

    • getVariable

      Object getVariable(String name) throws ScriptBasicException
      Get the value of a 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 will return a Double.
      Parameters:
      name - the name of the variable
      Returns:
      the value of the variable
      Throws:
      ScriptBasicException - in case of exception

    • call

      Object call(String functionName, Object[] arguments) throws ScriptBasicException
      Call a function defined by the program passing the objects as arguments.
      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
      Throws:
      ScriptBasicException - in case of exception

    • registerFunctions

      void registerFunctions(Class<?> klass)
      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 @BasicFunction
      Parameters:
      klass - the class the defines the functions.

    • getConfiguration

      Configuration getConfiguration()

    • execute

      void execute(Command startCommand) throws ScriptBasicException
      Execute the program starting at the command startCommand
      Parameters:
      startCommand - where the execution has to start
      Throws:
      ScriptBasicException - in case of exception during the execution

    • 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

    • getReturnValue

      RightValue getReturnValue()
      Get the return value that was set by the execution of the subroutine.
      Returns:
      return value

    • 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

    • getVariables

      HierarchicalVariableMap getVariables()
      Get the global variables of the program.
      Returns:
      the variables.

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

      Parameters:
      alias - the alias how the function will be named in basic
      klass - the class where the static method is
      methodName - the java name of the method
      argumentTypes - the types of the arguments to be used to help to identify overloaded methods
      Throws:
      BasicRuntimeException - in case of exception

    • getInput

      Reader getInput()

    • setInput

      void setInput(Reader reader)
      Parameters:
      reader - parameter
      See Also:

    • getOutput

      Writer getOutput()

    • setOutput

      void setOutput(Writer writer)
      Parameters:
      writer - parameter
      See Also:

    • getErrorOutput

      Writer getErrorOutput()
      ScriptContext.getReader()
      Returns:
      return value

    • setErrorOutput

      void setErrorOutput(Writer writer)
      Parameters:
      writer - parameter
      See Also:

    • 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:
      return value