Package com.scriptbasic

Class Engine

java.lang.Object
com.scriptbasic.Engine
All Implemented Interfaces:
ScriptBasic
public class Engine
extends java.lang.Object
implements ScriptBasic

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    class  Engine.Sub<R>  

    Nested classes/interfaces inherited from interface com.scriptbasic.api.ScriptBasic

    ScriptBasic.FunctionBuilder, ScriptBasic.VariableBuilder

  • Field Summary

    Fields inherited from interface com.scriptbasic.api.ScriptBasic

    fileHandlingFunctionsClass

  • Constructor Summary

    Constructors 
    Constructor Description
    Engine()  

  • Method Summary

    Modifier and Type Method Description
    ScriptBasic eval​(java.io.File sourceFile)
    Evaluate the content of a file.
    ScriptBasic eval​(java.io.Reader reader)
    Read the content of a stream provided by the reader and interpret this as a BASIC program.
    ScriptBasic eval​(java.lang.String sourceCode)
    Evaluate a string as a BASIC program.
    ScriptBasic eval​(java.lang.String sourceFileName, SourcePath path)
    Read the content of the file and execute it.
    ScriptBasic eval​(java.lang.String sourceName, SourceProvider provider)
    Read the content of the source from the file, db...
    ScriptBasic eval​(java.lang.String sourceFileName, java.lang.String... path)
    Read the content of the file and execute it.
    ScriptBasic execute()
    Execute a previously loaded code.
    Configuration getConfiguration()  
    java.io.Writer getErrorOutput()
    Get the output writer used to write the error output of the BASIC program.
    java.io.Reader getInput()
    Get the reader from where the BASIC program reads the standard input characters.
    java.io.Writer getOutput()
    Get the output writer used to write the standard output of the BASIC program.
    java.lang.Object getVariable​(java.lang.String name)
    Get the value of a global variable after the BASIC program was executed.
    java.lang.Iterable<java.lang.String> getVariablesIterator()
    Same as ScriptBasic.variables().
    ScriptBasic load​(java.io.File sourceFile)
    Evaluate the content of a file.
    ScriptBasic load​(java.io.Reader reader)
    Read the content of a stream provided by the reader and interpret this as a BASIC program.
    ScriptBasic load​(java.lang.String sourceCode)
    Load a string as a BASIC program.
    ScriptBasic load​(java.lang.String sourceFileName, SourcePath path)
    Read the content of the file and execute it.
    ScriptBasic load​(java.lang.String sourceName, SourceProvider provider)
    Read the content of the source from the file, db...
    ScriptBasic load​(java.lang.String sourceFileName, java.lang.String... path)
    Read the content of the file and execute it.
    ScriptBasic registerExtension​(java.lang.Class<?> klass)
    Register the static methods of the class as BASIC functions.
    void registerFunction​(java.lang.String alias, java.lang.Class<?> klass, java.lang.String methodName, java.lang.Class<?>... argumentTypes)  
    ScriptBasic registerHook​(InterpreterHook hook)
    Register an interpreter hook class.
    void setErrorOutput​(java.io.Writer error)
    Set the output writer used to write the error output of the BASIC program.
    void setInput​(java.io.Reader input)
    Set the reader from where the BASIC program reads the standard input characters.
    void setOutput​(java.io.Writer output)
    Set the output writer used to write the standard output of the BASIC program.
    void setVariable​(java.lang.String name, java.lang.Object value)
    Set the value of a global variable of the BASIC program.
    <R> Subroutine<R> subroutine​(java.lang.Class<R> type, java.lang.String name)
    Get the subroutine object of a named subroutine.
    <R> Subroutine<R> subroutine​(java.lang.String name)
    Convenience method with the same result as calling ScriptBasic.subroutine(Class, String) with Object.class as first argument.
    java.lang.Iterable<Subroutine> subroutines()
    Get all the subroutine objects in an iterator.
    <T> T variable​(java.lang.Class<T> type, java.lang.String name)
    Get the value of a global variable after the BASIC program was executed.
    java.lang.Iterable<java.lang.String> variables()
    Get an iterator that iterates through the names of the global variables.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.scriptbasic.api.ScriptBasic

    error, function, input, output, variable

  • Constructor Details

  • Method Details

    • getInput

      public java.io.Reader getInput()
      Description copied from interface: ScriptBasic
      Get the reader from where the BASIC program reads the standard input characters.
      Specified by:
      getInput in interface ScriptBasic
      Returns:
      return value

    • setInput

      public void setInput​(java.io.Reader input)
      Description copied from interface: ScriptBasic
      Set the reader from where the BASIC program reads the standard input characters.
      Specified by:
      setInput in interface ScriptBasic
      Parameters:
      input - the input to set

    • getOutput

      public java.io.Writer getOutput()
      Description copied from interface: ScriptBasic
      Get the output writer used to write the standard output of the BASIC program.
      Specified by:
      getOutput in interface ScriptBasic
      Returns:
      the output

    • setOutput

      public void setOutput​(java.io.Writer output)
      Description copied from interface: ScriptBasic
      Set the output writer used to write the standard output of the BASIC program.
      Specified by:
      setOutput in interface ScriptBasic
      Parameters:
      output - parameter

    • getErrorOutput

      public java.io.Writer getErrorOutput()
      Description copied from interface: ScriptBasic
      Get the output writer used to write the error output of the BASIC program.
      Specified by:
      getErrorOutput in interface ScriptBasic
      Returns:
      the error output writer

    • setErrorOutput

      public void setErrorOutput​(java.io.Writer error)
      Description copied from interface: ScriptBasic
      Set the output writer used to write the error output of the BASIC program.
      Specified by:
      setErrorOutput in interface ScriptBasic
      Parameters:
      error - the error output

    • execute

      public ScriptBasic execute() throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Execute a previously loaded code.
      Specified by:
      execute in interface ScriptBasic
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.lang.String sourceCode) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Load a string as a BASIC program.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      sourceCode - contains the source code as string
      Returns:
      this
      Throws:
      ScriptBasicException - when the code cannot be loaded

    • eval

      public ScriptBasic eval​(java.lang.String sourceCode) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Evaluate a string as a BASIC program.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      sourceCode - contains the source code as string
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.io.Reader reader) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of a stream provided by the reader and interpret this as a BASIC program. This method does not execute the code.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      reader - the reader to supply the BASIC program characters.
      Returns:
      this
      Throws:
      ScriptBasicException - when the code cannot be loaded

    • eval

      public ScriptBasic eval​(java.io.Reader reader) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of a stream provided by the reader and interpret this as a BASIC program.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      reader - the reader to supply the BASIC program characters.
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.io.File sourceFile) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Evaluate the content of a file. The file has to contain the BASIC program. This method does not execute the code.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      sourceFile - the file handler pointing to the file that the interpreter will read to get the source code.
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • eval

      public ScriptBasic eval​(java.io.File sourceFile) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Evaluate the content of a file. The file has to contain the BASIC program.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      sourceFile - the file handler pointing to the file that the interpreter will read to get the source code.
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.lang.String sourceFileName, java.lang.String... path) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the file and execute it. If there is any other script included then use the path to search for the file. This method does not execute the code.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      sourceFileName - the file that contains the script
      path - the array of path elements that are searched for included files
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • eval

      public ScriptBasic eval​(java.lang.String sourceFileName, java.lang.String... path) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the file and execute it. If there is any other script included then use the path to search for the file.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      sourceFileName - the file that contains the script
      path - the array of path elements that are searched for included files
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.lang.String sourceFileName, SourcePath path) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the file and execute it. If there is any other script included then use the path to search for the file. This method does not execute the code.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      sourceFileName - the file that contains the script
      path - the path where included files are located
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • eval

      public ScriptBasic eval​(java.lang.String sourceFileName, SourcePath path) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the file and execute it. If there is any other script included then use the path to search for the file.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      sourceFileName - the file that contains the script
      path - the path where included files are located
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • load

      public ScriptBasic load​(java.lang.String sourceName, SourceProvider provider) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the source from the file, db... whatever named by the argument sourceName using the provider. This method does not execute the code.
      Specified by:
      load in interface ScriptBasic
      Parameters:
      sourceName - the name of the source file where the source is. The syntax of the name depends on the provider.
      provider - the source provider that helps the reader to read the content
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • eval

      public ScriptBasic eval​(java.lang.String sourceName, SourceProvider provider) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Read the content of the source from the file, db... whatever named by the argument sourceName using the provider.
      Specified by:
      eval in interface ScriptBasic
      Parameters:
      sourceName - the name of the source file where the source is. The syntax of the name depends on the provider.
      provider - the source provider that helps the reader to read the content
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • setVariable

      public void setVariable​(java.lang.String name, java.lang.Object value) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Set the value of a global variable of the BASIC program.
      Specified by:
      setVariable in interface ScriptBasic
      Parameters:
      name - of the variable as it is used in the BASIC program
      value - the value of the variable. The value is converted automatically to be a BASIC value.
      Throws:
      ScriptBasicException - in case of exception

    • getVariable

      public java.lang.Object getVariable​(java.lang.String name) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Get the value of a global variable after the BASIC program was executed.
      Specified by:
      getVariable in interface ScriptBasic
      Parameters:
      name - of the variable
      Returns:
      the value of the variable converted to Java. Thus there is no need to deal with ScriptBasic internal classes. If the variable contains an integer then this method will return a Long, if it is a string then it will be a String and so on.
      Throws:
      ScriptBasicException - in case of exception

    • variable

      public <T> T variable​(java.lang.Class<T> type, java.lang.String name) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Get the value of a global variable after the BASIC program was executed.
      Specified by:
      variable in interface ScriptBasic
      Type Parameters:
      T - the type the caller expects the variable to be. Type conversion is done by the method and in case the value can not be cast to the type then the ClassCastException will be embedded into a ScriptBasicException. This method will not magically convert between Java types, even though it will convert from BASIC types to Java types (see below). This parameter is used only to cast the result.
      Parameters:
      type - is the type class
      name - of the variable
      Returns:
      the value of the variable converted to Java. Thus there is no need to deal with ScriptBasic internal classes. If the variable contains an integer then this method will return a Long, if it is a string then it will be a String and so on.
      Throws:
      ScriptBasicException - when the variable cannot be retrieved, or has a type that can not be converted to T.

    • getVariablesIterator

      public java.lang.Iterable<java.lang.String> getVariablesIterator() throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Same as ScriptBasic.variables().
      Specified by:
      getVariablesIterator in interface ScriptBasic
      Returns:
      same as
      Throws:
      ScriptBasicException - in case of exception

    • variables

      public java.lang.Iterable<java.lang.String> variables() throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Get an iterator that iterates through the names of the global variables.
      Specified by:
      variables in interface ScriptBasic
      Returns:
      the iterator to fetch the names of the global variables one by one.
      Throws:
      ScriptBasicException - in case of exception

    • subroutines

      public java.lang.Iterable<Subroutine> subroutines() throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Get all the subroutine objects in an iterator.
      Specified by:
      subroutines in interface ScriptBasic
      Returns:
      an iterator that can be used to access all subroutine objects.
      Throws:
      ScriptBasicException - in case of exception

    • subroutine

      public <R> Subroutine<R> subroutine​(java.lang.String name) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Convenience method with the same result as calling ScriptBasic.subroutine(Class, String) with Object.class as first argument.
      Specified by:
      subroutine in interface ScriptBasic
      Type Parameters:
      R - defaults to Object.class
      Parameters:
      name - the name of the subroutine
      Returns:
      the subroutine object
      Throws:
      ScriptBasicException - in case of exception

    • subroutine

      public <R> Subroutine<R> subroutine​(java.lang.Class<R> type, java.lang.String name) throws ScriptBasicException
      Description copied from interface: ScriptBasic
      Get the subroutine object of a named subroutine. This object can later be used to call the subroutine after the code was executed.
      Specified by:
      subroutine in interface ScriptBasic
      Type Parameters:
      R - the type
      Parameters:
      type - is the expected return value of the subroutine. If the subroutine does not return any value then specify Void.class. If it may return just any value, or may not return any value and the caller does not care then specify Object.class or just null. Note that this is an error if a subroutine returns a value when invoking Subroutine.call() but the subroutine object was created with Void.class argument.
      name - the name of the subroutine for which the object is to be fetched.
      Returns:
      the subroutine object.
      Throws:
      ScriptBasicException - in case of exception

    • registerFunction

      public void registerFunction​(java.lang.String alias, java.lang.Class<?> klass, java.lang.String methodName, java.lang.Class<?>... argumentTypes) throws ScriptBasicException
      Specified by:
      registerFunction in interface ScriptBasic
      Parameters:
      alias - the name of the method as it can be used in the BASIC program
      klass - the class that contains the method
      methodName - the name of the method
      argumentTypes - the types of the arguments
      Throws:
      ScriptBasicException - when a function is double defined and not an identical manner

    • registerExtension

      public ScriptBasic registerExtension​(java.lang.Class<?> klass)
      Description copied from interface: ScriptBasic
      Register the static methods of the class as BASIC functions. After the registration, the methods can be called from BASIC just as if they were built-in functions in the language or just like if they were defined as BASIC subroutines.

      The registration process uses only the methods that are annotated as BasicFunction and only if their BasicFunction.classification() parameter is not configured in the configuration as forbidden.

      Even though the static methods are called via reflection they have to be callable from the BASIC interpreter. Simply saying they have to be public and their packages exported to the BASIC interpreter.

      Specified by:
      registerExtension in interface ScriptBasic
      Parameters:
      klass - the class to parse.
      Returns:
      this

    • registerHook

      public ScriptBasic registerHook​(InterpreterHook hook)
      Description copied from interface: ScriptBasic
      Register an interpreter hook class.
      Specified by:
      registerHook in interface ScriptBasic
      Parameters:
      hook - the hook instance to register
      Returns:
      this

    • getConfiguration

      public Configuration getConfiguration()
      Specified by:
      getConfiguration in interface ScriptBasic
      Returns:
      the configuration object of the BASIC interpreter.