com.scriptbasic

Class Engine

java.lang.Object

com.scriptbasic.Engine

All Implemented Interfaces:

EngineApi

public class Engine
extends Object
implements EngineApi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Engine.Sub

Constructor Summary

Constructors

Constructor and Description
Engine()

Method Summary

Methods

Modifier and Type	Method and Description
Object	call(String subroutineName, Object... args) Call the named subroutine with the arguments.
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) Get the number of expected argument of the named subroutine.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

Engine

public Engine()

Method Detail

getBasicFactory

public Factory getBasicFactory()

Description copied from interface: EngineApi

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.

Specified by:

getBasicFactory in interface EngineApi

Returns:

the factory instance

getInput

public Reader getInput()

Description copied from interface: EngineApi

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

Specified by:

getInput in interface EngineApi

Returns:

setInput

public void setInput(Reader input)

Description copied from interface: EngineApi

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

Specified by:

setInput in interface EngineApi

getOutput

public Writer getOutput()

Description copied from interface: EngineApi

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

Specified by:

getOutput in interface EngineApi

Returns:

setOutput

public void setOutput(Writer output)

Description copied from interface: EngineApi

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

Specified by:

setOutput in interface EngineApi

getError

public Writer getError()

Description copied from interface: EngineApi

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

Specified by:

getError in interface EngineApi

Returns:

setError

public void setError(Writer error)

Description copied from interface: EngineApi

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

Specified by:

setError in interface EngineApi

execute

public void execute()
             throws ScriptBasicException

Description copied from interface: EngineApi

Execute a previously loaded code.

Specified by:

execute in interface EngineApi

Throws:

ScriptBasicException

load

public void load(String sourceCode)
          throws ScriptBasicException

Description copied from interface: EngineApi

Load a string as a BASIC program.

Specified by:

load in interface EngineApi

Parameters:

sourceCode - contains the source code as string

Throws:

ScriptBasicException

eval

public void eval(String sourceCode)
          throws ScriptBasicException

Description copied from interface: EngineApi

Evaluate a string as a BASIC program.

Specified by:

eval in interface EngineApi

Parameters:

sourceCode - contains the source code as string

Throws:

ScriptBasicException

load

public void load(Reader reader)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

reader - the reader to supply the BASIC program characters.

Throws:

ScriptBasicException

eval

public void eval(Reader reader)
          throws ScriptBasicException

Description copied from interface: EngineApi

Read the content of a stream provided by the reader and interpret this as a BASIC program.

Specified by:

eval in interface EngineApi

Parameters:

reader - the reader to supply the BASIC program characters.

Throws:

ScriptBasicException

load

public void load(File sourceFile)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

sourceFile - the file handler pointing to the file that the interpreter will read to get the source code.

Throws:

ScriptBasicException

eval

public void eval(File sourceFile)
          throws ScriptBasicException

Description copied from interface: EngineApi

Evaluate the content of a file. The file has to contain the BASIC program.

Specified by:

eval in interface EngineApi

Parameters:

sourceFile - the file handler pointing to the file that the interpreter will read to get the source code.

Throws:

ScriptBasicException

load

public void load(String sourceFileName,
        String... path)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

sourceFileName - the file that contains the script

path - the array of path elements that are searched for included files

Throws:

ScriptBasicException

eval

public void eval(String sourceFileName,
        String... path)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

sourceFileName - the file that contains the script

path - the array of path elements that are searched for included files

Throws:

ScriptBasicException

load

public void load(String sourceFileName,
        SourcePath path)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

sourceFileName - the file that contains the script

path - the path where included files are located

Throws:

ScriptBasicException

eval

public void eval(String sourceFileName,
        SourcePath path)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

Parameters:

sourceFileName - the file that contains the script

path - the path where included files are located

Throws:

ScriptBasicException

load

public void load(String sourceName,
        SourceProvider provider)
          throws ScriptBasicException

Description copied from interface: EngineApi

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 EngineApi

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

public void eval(String sourceName,
        SourceProvider provider)
          throws ScriptBasicException

Description copied from interface: EngineApi

Read the content of the source from the file, db... whatever named by the argument sourceName using the provider.

Specified by:

eval in interface EngineApi

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

setVariable

public void setVariable(String name,
               Object value)
                 throws ScriptBasicException

Description copied from interface: EngineApi

Set the value of a global variable of the BASIC program.

Specified by:

setVariable in interface EngineApi

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

public Object getVariable(String name)
                   throws ScriptBasicException

Description copied from interface: EngineApi

Get the value of a global variable after the BASIC program was executed.

Specified by:

getVariable in interface EngineApi

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

public Iterable<String> getVariablesIterator()

Description copied from interface: EngineApi

Get an iterator that iterates through the names of the global variables.

Specified by:

getVariablesIterator in interface EngineApi

Returns:

the iterator to fetch the names of the global variables one by one.

call

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

Description copied from interface: EngineApi

Call the named subroutine with the arguments.

It is recommended to call subroutines via a Subroutine object.

Specified by:

call in interface EngineApi

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

public Iterable<String> getSubroutineNames()

Description copied from interface: EngineApi

Get the names of all subroutines.

Specified by:

getSubroutineNames in interface EngineApi

Returns:

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

getSubroutines

public Iterable<Subroutine> getSubroutines()

Description copied from interface: EngineApi

Get all the subroutine objects in an iterator.

Specified by:

getSubroutines in interface EngineApi

Returns:

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

getNumberOfArguments

public int getNumberOfArguments(String subroutineName)
                         throws ScriptBasicException

Description copied from interface: EngineApi

Get the number of expected argument of the named subroutine.

It is recommended to call subroutines via a Subroutine object.

Specified by:

getNumberOfArguments in interface EngineApi

Parameters:

subroutineName - the name of the subroutine.

Returns:

the number of arguments the subroutine expects.

Throws:

ScriptBasicException

getSubroutine

public Subroutine getSubroutine(String subroutineName)
                         throws ScriptBasicException

Description copied from interface: EngineApi

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:

getSubroutine in interface EngineApi

Parameters:

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

Returns:

the subroutine object.

Throws:

ScriptBasicException

registerExtension

public void registerExtension(Class<?> klass)
                       throws ScriptBasicException

Description copied from interface: EngineApi

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.

Specified by:

registerExtension in interface EngineApi

Parameters:

klass - the class to parse.

Throws:

ScriptBasicException