Module scriptbasic

Package com.scriptbasic.api

Annotation Type BasicFunction

@Retention(RUNTIME)
public @interface BasicFunction

This annotation interface can be used in classes that define static methods to be called from BASIC code.

Each public static method that is supposed to be reachable from BASIC should have the annotation @BasicFunction. The implementation of the interface Interpreter provides method that registers all the such annotated methods of the class specified.

Author:

Peter Verhas date July 22, 2012

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
java.lang.String	alias	The alias name of the function to be used in the BASIC program.
java.lang.Class<?>[]	classification	The different methods can be classified and the configuration of the actual interpreter registers or denies the registration of certain methods based on the classification.
long	requiredVersion	The interface version of ScriptBasic for Java required for this method to properly function.
java.lang.Class<?>	substituteClass	It may happen that the you want to register methods that are not in your hands.
java.lang.String	substituteMethod	Using this parameter you can specify an alternative method instead of the annotated one.

Element Detail

alias

java.lang.String alias

The alias name of the function to be used in the BASIC program. If this is not defined then the name of the method will be used.

Default:

""

requiredVersion

long requiredVersion

The interface version of ScriptBasic for Java required for this method to properly function.

The different versions of ScriptBasic may provide different functionalities for the methods registered as functions. When a method needs a specific interface version the interpreter may alter its behavior.

If a method requires an interface version that is higher than the version of the executing interpreter then the interpreter can not work together with the extension and thus will signal error.

If a method requires a version that is smaller that the actual version of the executing interpreter then the interpreter may decide if it can work with the extension. There may be three different cases foreseen:

1. The interpreter can work seamless with an extension that was designed for an earlier version.
2. The interpreter can not support the outdated extension.
3. The interpreter mimics the interface of an older version of it provided towards the extension.

The version specified in this annotation is the version of the 'interface' the interpreter provides for the extensions. This 'interface' is not literally a Java interface, rather the collection of all the interfaces and behaviors that the interpreter exhibits towards the extensions.

If different versions of ScriptBasic for Java share the same behavior regarding the extensions and thus the two versions are 100% compatible regarding extension support and usage then the two different versions of the interpreter will have the same extension interface version. Therefore you should expect this interface version to change rather infrequent.

A later version of SB4J should not have a smaller interface version.

Note that the time I write this documentation the interpreter is in infancy and has a pre-version of 1.

The actual value of the actual version is defined as a constant: ExtensionInterfaceVersion.EXTENSION_INTERFACE_VERSION.

Default:

1L

classification

java.lang.Class<?>[] classification

The different methods can be classified and the configuration of the actual interpreter registers or denies the registration of certain methods based on the classification.

Default:

{com.scriptbasic.api.BasicFunction.class}

substituteClass

java.lang.Class<?> substituteClass

It may happen that the you want to register methods that are not in your hands. In such a case the method can not be instrumented using annotations. Using this annotation parameter you can specify an alternative class where the method you want to register instead of the annotated one is.

Default:

com.scriptbasic.api.BasicFunction.class

substituteMethod

java.lang.String substituteMethod

Using this parameter you can specify an alternative method instead of the annotated one. See the documentation of substituteClass().

Default:

""