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 Detail

Engine

public Engine()

Method Detail

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.