Package com.scriptbasic.api

Interface ScriptBasic

All Known Implementing Classes:
Engine
public interface ScriptBasic
ScriptBasic for Java embedding interface.

This interface defines the native methods that can be used to embed ScriptBasic into applications. Using the methods of this API you can load, execute BASIC programs, define how the interpreter can get access to other sources that are included by the script, set and get global variables and call subroutines.

Deprecated methods are replaced by fluent api methods that return "this". The deprecated method are not for removal. They are not to be used by callers but they are to be implemented by implementing classes. These methods are invoked from the fluent API method default implementations in this interface. That way the builder pattern like fluent api does not need to be implemented by each class that implements the interface.

Author:
Peter Verhas

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Interface Description
    static class  ScriptBasic.FunctionBuilder  
    static class  ScriptBasic.VariableBuilder  

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static java.lang.Class<FileHandlingFunctions> fileHandlingFunctionsClass  

  • Method Summary

    Modifier and Type Method Description
    static ScriptBasic engine()  
    default ScriptBasic error​(java.io.Writer error)  
    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.
    default ScriptBasic.FunctionBuilder function​(java.lang.String methodName)
    Use this method to register a Java function so that it can be called from the BASIC program.
    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)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use the version that has a second argument specifying the required type.
    java.lang.Iterable<java.lang.String> getVariablesIterator()
    Deprecated, for removal: This API element is subject to removal in a future version.
    default ScriptBasic input​(java.io.Reader input)  
    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.
    default ScriptBasic output​(java.io.Writer output)  
    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)
    Deprecated.
    use variable(String), not for removal.
    <T> Subroutine<T> subroutine​(java.lang.Class<T> type, java.lang.String name)
    Get the subroutine object of a named subroutine.
    <T> Subroutine<T> subroutine​(java.lang.String name)
    Convenience method with the same result as calling 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.
    default ScriptBasic.VariableBuilder variable​(java.lang.String name)
    define a
    java.lang.Iterable<java.lang.String> variables()
    Get an iterator that iterates through the names of the global variables.

  • Field Details

  • Method Details

    • engine

      static ScriptBasic engine()

    • registerFunction

      void registerFunction​(java.lang.String alias, java.lang.Class<?> klass, java.lang.String methodName, java.lang.Class<?>... argumentTypes) throws ScriptBasicException
      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

    • function

      default ScriptBasic.FunctionBuilder function​(java.lang.String methodName)
      Use this method to register a Java function so that it can be called from the BASIC program. For example: 
           engine.function("myMethod")
           .alias("BASICNAME")
           .klass(WhereItIsImplemented.class)
           .arguments(String.class);

      In the fluent API this method call should be followed/chained by calls to ScriptBasic.FunctionBuilder.klass(Class), optionally by ScriptBasic.FunctionBuilder.FunctionBuilder2.alias(String) and finally the chain must be closed with ScriptBasic.FunctionBuilder.FunctionBuilder2.arguments(Class[]). The method #function(String) as well as ScriptBasic.FunctionBuilder.klass(Class),and ScriptBasic.FunctionBuilder.FunctionBuilder2.alias(String) return a ScriptBasic.FunctionBuilder instance used only for the method chaining and the last call in the chain ScriptBasic.FunctionBuilder.FunctionBuilder2.arguments(Class[]) returns to the top level ScriptBasic object.

      Parameters:
      methodName - the name of the method in the Java class. If the method ScriptBasic.FunctionBuilder.FunctionBuilder2.alias(String) is not invoked in this chain then the name specified here as argument will also be used as the name to be used in th BASIC program.
      Returns:
      a ScriptBasic.FunctionBuilder to use for further method chaining.

    • getInput

      java.io.Reader getInput()
      Get the reader from where the BASIC program reads the standard input characters.
      Returns:
      return value

    • setInput

      void setInput​(java.io.Reader input)
      Set the reader from where the BASIC program reads the standard input characters.
      Parameters:
      input - the input to set

    • input

      default ScriptBasic input​(java.io.Reader input)

    • getOutput

      java.io.Writer getOutput()
      Get the output writer used to write the standard output of the BASIC program.
      Returns:
      the output

    • setOutput

      void setOutput​(java.io.Writer output)
      Set the output writer used to write the standard output of the BASIC program.
      Parameters:
      output - parameter

    • output

      default ScriptBasic output​(java.io.Writer output)

    • getErrorOutput

      java.io.Writer getErrorOutput()
      Get the output writer used to write the error output of the BASIC program.
      Returns:
      the error output writer

    • setErrorOutput

      void setErrorOutput​(java.io.Writer error)
      Set the output writer used to write the error output of the BASIC program.
      Parameters:
      error - the error output

    • error

      default ScriptBasic error​(java.io.Writer error)

    • load

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

    • load

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

    • load

      ScriptBasic load​(java.io.File sourceFile) throws ScriptBasicException
      Evaluate the content of a file. The file has to contain the BASIC program. This method does not execute the code.
      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

      ScriptBasic load​(java.lang.String sourceFileName, java.lang.String... path) throws ScriptBasicException
      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.
      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

      ScriptBasic load​(java.lang.String sourceFileName, SourcePath path) throws ScriptBasicException
      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.
      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

      ScriptBasic load​(java.lang.String sourceName, SourceProvider provider) throws ScriptBasicException
      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.
      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

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

    • eval

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

    • eval

      ScriptBasic eval​(java.io.File sourceFile) throws ScriptBasicException
      Evaluate the content of a file. The file has to contain the BASIC program.
      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

      ScriptBasic eval​(java.lang.String sourceFileName, java.lang.String... path) throws ScriptBasicException
      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.
      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

      ScriptBasic eval​(java.lang.String sourceFileName, SourcePath path) throws ScriptBasicException
      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.
      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

      ScriptBasic eval​(java.lang.String sourceName, SourceProvider provider) throws ScriptBasicException
      Read the content of the source from the file, db... whatever named by the argument sourceName using the provider.
      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

    • execute

      ScriptBasic execute() throws ScriptBasicException
      Execute a previously loaded code.
      Returns:
      this
      Throws:
      ScriptBasicException - in case of exception

    • setVariable

      @Deprecated void setVariable​(java.lang.String name, java.lang.Object value) throws ScriptBasicException
      Deprecated.
      use variable(String), not for removal.
      Set the value of a global variable of the BASIC program.
      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

    • variable

      default ScriptBasic.VariableBuilder variable​(java.lang.String name)
      define a
      Parameters:
      name - parameter
      Returns:
      return value

    • getVariable

      @Deprecated(forRemoval=true) java.lang.Object getVariable​(java.lang.String name) throws ScriptBasicException
      Deprecated, for removal: This API element is subject to removal in a future version.
      use the version that has a second argument specifying the required type. Migration can be done in two steps: 1.) add an Object.class second argument and keep the cast, 2.) use it properly.
      Get the value of a global variable after the BASIC program was executed.
      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

      <T> T variable​(java.lang.Class<T> type, java.lang.String name) throws ScriptBasicException
      Get the value of a global variable after the BASIC program was executed.
      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

      @Deprecated(forRemoval=true) java.lang.Iterable<java.lang.String> getVariablesIterator() throws ScriptBasicException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Same as variables().
      Returns:
      same as
      Throws:
      ScriptBasicException - in case of exception

    • variables

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

    • subroutine

      <T> Subroutine<T> subroutine​(java.lang.Class<T> type, java.lang.String name) throws ScriptBasicException
      Get the subroutine object of a named subroutine. This object can later be used to call the subroutine after the code was executed.
      Type Parameters:
      T - 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

    • subroutine

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

    • subroutines

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

    • registerExtension

      ScriptBasic registerExtension​(java.lang.Class<?> klass)
      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.

      Parameters:
      klass - the class to parse.
      Returns:
      this

    • registerHook

      ScriptBasic registerHook​(InterpreterHook hook)
      Register an interpreter hook class.
      Parameters:
      hook - the hook instance to register
      Returns:
      this

    • getConfiguration

      Configuration getConfiguration()
      Returns:
      the configuration object of the BASIC interpreter.