com.scriptbasic.interfaces

Interface EngineApi

All Known Implementing Classes:

Engine

public interface EngineApi

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.

Author:

Peter Verhas

Method Summary

Methods

Modifier and Type	Method and Description
Object	call(String subroutineName, Object... args) Deprecated.
void	eval(File sourceFile) Evaluate the content of a file.
void	eval(Reader reader) Read the content of a stream provided by the reader and interpret this as a BASIC program.
void	eval(String sourceCode) Evaluate a string as a BASIC program.
void	eval(String sourceFileName, SourcePath path) Read the content of the file and execute it.
void	eval(String sourceName, SourceProvider provider) Read the content of the source from the file, db...
void	eval(String sourceFileName, String... path) Read the content of the file and execute it.
void	execute() Execute a previously loaded code.
Factory	getBasicFactory() Get the factory used to create the different parts of the execution environment for this engine.
Writer	getError() Get the output writer used to write the error output of the BASIC program.
Reader	getInput() Get the reader from where the BASIC program reads the standard input characters.
int	getNumberOfArguments(String subroutineName) Deprecated.
Writer	getOutput() Get the output writer used to write the standard output of the BASIC program.
Subroutine	getSubroutine(String subroutineName) Get the subroutine object of a named subroutine.
Iterable<String>	getSubroutineNames() Get the names of all subroutines.
Iterable<Subroutine>	getSubroutines() Get all the subroutine objects in an iterator.
Object	getVariable(String name) Get the value of a global variable after the BASIC program was executed.
Iterable<String>	getVariablesIterator() Get an iterator that iterates through the names of the global variables.
void	load(File sourceFile) Evaluate the content of a file.
void	load(Reader reader) Read the content of a stream provided by the reader and interpret this as a BASIC program.
void	load(String sourceCode) Load a string as a BASIC program.
void	load(String sourceFileName, SourcePath path) Read the content of the file and execute it.
void	load(String sourceName, SourceProvider provider) Read the content of the source from the file, db...
void	load(String sourceFileName, String... path) Read the content of the file and execute it.
void	registerExtension(Class<?> klass) Register the static methods of the class as BASIC functions.
void	setError(Writer error) Set the output writer used to write the error output of the BASIC program.
void	setInput(Reader input) Set the reader from where the BASIC program reads the standard input characters.
void	setOutput(Writer output) Set the output writer used to write the standard output of the BASIC program.
void	setVariable(String name, Object value) Set the value of a global variable of the BASIC program.

Method Detail

getBasicFactory

Factory getBasicFactory()

Get the factory used to create the different parts of the execution environment for this engine. The factory can be requested to return the reader, lexical analyzer and other objects that are used internally to manage the execution of the program. To use the ScriptBasic Engine there is no need for this method This method provides a way to access the objects that are below this facade and is available for advanced programmers who are not satisfied with the features provided with this facade.

If ever you need to use this method, do use it at your own risk, and inform the developers of your need so that they may consider extending this facade to accommodate your needs.

Returns:

the factory instance

getInput

Reader getInput()

Get the reader from where the BASIC program reads the standard input characters.

Returns:

setInput

void setInput(Reader input)

Set the reader from where the BASIC program reads the standard input characters.

Parameters:

input -

getOutput

Writer getOutput()

Get the output writer used to write the standard output of the BASIC program.

Returns:

setOutput

void setOutput(Writer output)

Set the output writer used to write the standard output of the BASIC program.

Parameters:

output -

getError

Writer getError()

Get the output writer used to write the error output of the BASIC program.

Returns:

setError

void setError(Writer error)

Set the output writer used to write the error output of the BASIC program.

Parameters:

error -

load

void load(String sourceCode)
          throws ScriptBasicException

Load a string as a BASIC program.

Parameters:

sourceCode - contains the source code as string

Throws:

ScriptBasicException

load

void load(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.

Throws:

ScriptBasicException

load

void load(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.

Throws:

ScriptBasicException

load

void load(String sourceFileName,
        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

Throws:

ScriptBasicException

load

void load(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

Throws:

ScriptBasicException

load

void load(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

Throws:

ScriptBasicException

eval

void eval(String sourceCode)
          throws ScriptBasicException

Evaluate a string as a BASIC program.

Parameters:

sourceCode - contains the source code as string

Throws:

ScriptBasicException

eval

void eval(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.

Throws:

ScriptBasicException

eval

void eval(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.

Throws:

ScriptBasicException

eval

void eval(String sourceFileName,
        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

Throws:

ScriptBasicException

eval

void eval(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

Throws:

ScriptBasicException

eval

void eval(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

Throws:

ScriptBasicException

execute

void execute()
             throws ScriptBasicException

Execute a previously loaded code.

Throws:

ScriptBasicException

setVariable

void setVariable(String name,
               Object value)
                 throws ScriptBasicException

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

getVariable

Object getVariable(String name)
                   throws ScriptBasicException

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

getVariablesIterator

Iterable<String> getVariablesIterator()

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.

getSubroutine

Subroutine getSubroutine(String subroutineName)
                         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.

Parameters:

subroutineName - the name of the subroutine for which the object is to be fetched.

Returns:

the subroutine object.

Throws:

ScriptBasicException

getSubroutines

Iterable<Subroutine> getSubroutines()

Get all the subroutine objects in an iterator.

Returns:

an iterator that can be used to access all subroutine objects.

call

Object call(String subroutineName,
          Object... args)
            throws ScriptBasicException

Deprecated.

Call the named subroutine with the arguments.

It is recommended to call subroutines via a Subroutine object.

Parameters:

subroutineName - the name of the subroutine to be called.

args - the arguments to be passed to the subroutine. Note that there has to be that many arguments passed as many arguments are needed by the subroutine. If there are less number of actual arguments the rest of the arguments will be undefined. If you pass more actual arguments than the subroutine expects you will get an exception.

Returns:

the value returned by the subroutine. Note that this value is already converted to Java object and not a raw ScriptBasic RightValue but rather a Long, Double, String or similar.

Throws:

ScriptBasicException

getSubroutineNames

Iterable<String> getSubroutineNames()

Get the names of all subroutines.

Returns:

the iterator that can be used to iterate through the names of all the subroutines defined in the program.

getNumberOfArguments

int getNumberOfArguments(String subroutineName)
                         throws ScriptBasicException

Deprecated.

Get the number of expected argument of the named subroutine.

It is recommended to call subroutines via a Subroutine object.

Parameters:

subroutineName - the name of the subroutine.

Returns:

the number of arguments the subroutine expects.

Throws:

ScriptBasicException

registerExtension

void registerExtension(Class<?> klass)
                       throws ScriptBasicException

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 Function and only if their Function.classification() parameter is not configured in the configuration file 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.

Parameters:

klass - the class to parse.

Throws:

ScriptBasicException