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

    • Field Detail

      • fileHandlingFunctionsClass

        static final java.lang.Class<FileHandlingFunctions> fileHandlingFunctionsClass

    • Method Detail

      • 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

      • getInput

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

      • setInput

        @Deprecated
void setInput​(java.io.Reader input)
        Deprecated.
        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

        @Deprecated
void setOutput​(java.io.Writer output)
        Deprecated.
        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

        @Deprecated
void setErrorOutput​(java.io.Writer error)
        Deprecated.
        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.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

      • 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.