apt files are deleted

EngineApi renamed to ScriptBasic
AuxTest now runs
documentation

Author: verhas

site/advanced/extend.md

@@ -6,7 +6,7 @@
  some methods that will be available to the BASIC program without `use` or `method` declarations.
 
  To register a method into the BASIC runtime and thus make it available for the BASIC program to call,
- ScriptBasic for Java provides a method `registerExtension(Class<?> klass)` in the `EngineApi` interface. Using
+ ScriptBasic for Java provides a method `registerExtension(Class<?> klass)` in the `ScriptBasic` interface. Using
  this method the embedding application can register static methods from a class. The embedding application has to
  issue a single call and it will register all the methods that are appropriately annotated.
 
@@ -34,7 +34,7 @@
  The declared function can be called after that from BASIC the following way:
 
 ```
-		EngineApi engine = EngineApi.getEngine();
+		ScriptBasic engine = ScriptBasic.getEngine();
 		engine.registerExtension(TestExtensionClass.class);
 		engine.load("Sub aPie\nreturn javaFunction()\nEndSub\n");
 		engine.execute();

site/advanced/nativeapi.md

@@ -81,18 +81,18 @@ arguments and getting return values.
  The simplest ever use of the ScriptBasic for Java native API is to execute a script that is available in a string:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("print \"hello world\"");
 ``` 
 
 
  This code creates a new `Engine` object, then calls the method `eval` with the string that contains the
- program code. Note that `EngineApi` is an interface and `Engine` is the implementation.
+ program code. Note that `ScriptBasic` is an interface and `Engine` is the implementation.
  If you want to have the output of the program in a `String` you can create a `StringWriter`
  and redirect the standard output of the program to there:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         engine.eval("print \"hello world\"");
@@ -105,7 +105,7 @@ arguments and getting return values.
  program from a `java.io.Reader`:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         StringReader sr = new StringReader("print \"hello world\"");
@@ -117,7 +117,7 @@ arguments and getting return values.
  or from a `java.io.File`:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         File file = new File(getClass().getResource("hello.bas").getFile());
@@ -155,7 +155,7 @@ arguments and getting return values.
  To specify the directories where the files are use the following piece of code:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         String path = new File(getClass().getResource("hello.bas").getFile())
@@ -169,15 +169,15 @@ arguments and getting return values.
  as many `String` parameters as you like:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("include.bas", ".", "..", "/usr/include/scriptbasic");
 ```
 
  The second possibility is to provide a `SourcePath` object. The following sample
  shows you a very simple use of this approach:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         String path = new File(getClass().getResource("hello.bas").getFile())
@@ -201,7 +201,7 @@ arguments and getting return values.
  this is the following:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         SourceProvider provider = new SourceProvider() {
@@ -252,7 +252,7 @@ arguments and getting return values.
  for the script exactly as it was set by some BASIC code. To do so the following sample can be used:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         StringWriter sw = new StringWriter(10);
         engine.setOutput(sw);
         engine.setVariable("a", 13);
@@ -272,7 +272,7 @@ arguments and getting return values.
  After the code was executed you are able to query the values of the global variables:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("a = \"hello world\"");
         String a = (String) engine.getVariable("a");
         assertEquals("hello world", a);
@@ -294,7 +294,7 @@ arguments and getting return values.
  the execution of the code programmatically:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("a = \"hello world\"\nb=13");
         String varnames = "";
         for (String varname : engine.getVariablesIterator()) {
@@ -327,7 +327,7 @@ arguments and getting return values.
  To call a subroutine you have to know the name of the subroutine and you should call the method `call()`:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("sub applePie\nglobal a\na = \"hello world\"\nEndSub");
         String a = (String) engine.getVariable("a");
         assertNull(a);
@@ -340,7 +340,7 @@ arguments and getting return values.
   The next example shows how to pass arguments and how to get the return value:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("sub applePie(b)\nglobal a\na = b\nreturn 6\nEndSub");
         String a = (String) engine.getVariable("a");
         assertNull(a);
@@ -357,7 +357,7 @@ arguments and getting return values.
  To get all the subroutines the BASIC program defines you should call the method `getSubroutineNames()`:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("sub applePie(b)\nEndSub\nsub anotherSubroutine\nEndSub\n");
         int i = 0;
         for (@SuppressWarnings("unused")
@@ -378,7 +378,7 @@ arguments and getting return values.
  instance you can call `call(Object ... args)`, `getName()` and `getNumberOfArguments()` methods.
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("sub applePie\nglobal a\na = \"hello world\"\nEndSub");
         String a = (String) engine.getVariable("a");
         assertNull(a);
@@ -392,7 +392,7 @@ arguments and getting return values.
   sample how to call a subroutine in OO way that returns some value:
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("sub applePie(b)\nglobal a\na = b\nreturn 6\nEndSub");
         String a = (String) engine.getVariable("a");
         assertNull(a);

site/advanced/requiredVersion.md

@@ -1,30 +1,51 @@
-  ```
-  jScriptBasic Project Documentation
-  ```
-  Peter Verhas
-  ```
-  2012-12-05
-  ```
-  
-ScriptBasic for Java Interface Versions
+# ScriptBasic for Java Interface Versions
 
-	ScriptBasic provides an interface for functions implemented in Java and callable from BASIC. The functions
-	implemented in Java need not implement any Java interface. The "interface" ScriptBasic provides is not a Java
-	interface. This term refers to the way ScriptBasic calls these methods.
-	
-	As ScriptBasic develops the way ScriptBasic handles these extension functions also develop and some new
-	features become available. If an extension relies such an advanced feature it will not work with earlier
-	version of ScriptBasic that implements an earlier version of the interface. Therefore ScriptBasic introduces
-	a simple `long` number that specifies the version of the interface.
-	
-	This document describes the differences between the different interface versions.  
+ScriptBasic provides an interface for functions implemented in Java and callable 
+from BASIC. The functions
+implemented in Java need not implement any Java interface. In this terminology the 
+"interface" ScriptBasic provides is not a Java
+interface. This term refers to the way ScriptBasic calls these methods.
+
+As ScriptBasic develops the way ScriptBasic handles these extension functions also develop and some new
+features become available. If an extension relies on such an advanced feature
+it will not work with earlier
+versions of ScriptBasic that implements an earlier version of the interface.
+Therefore ScriptBasic introduces
+a simple `long` number that specifies the version of the interface.
+
+This document describes the differences between the different interface versions.  
 
 * 1L
 
  This is the initial version.
 
 * 2L
 
- ScriptBasic 1.0.4 introduced the possibility for an extension to accept BASIC array as argument and also to
- return an array as value. If you need that feature you have to specify `requiredVersion=2L` in the
- annotation of the static method implementing the extension function. 
+ ScriptBasic 1.0.4 introduced the possibility for an extension to accept BASIC
+ array as argument and also to
+ return an array as value. If you need that feature you have to
+ specify `requiredVersion=2L` in the
+ annotation of the static method implementing the extension function.
+ 
+ For example the method `length()` implemented in the class `UtilityFunctions` as
+ 
+```
+     @BasicFunction(classification = Utility.class, requiredVersion = 2L)
+     public static Long length(Object arg) {
+         if (arg == null) {
+             return null;
+         } else if (arg instanceof BasicArrayValue) {
+             BasicArrayValue array = (BasicArrayValue) arg;
+             return array.getLength();
+         } else if (arg instanceof String) {
+             String string = (String) arg;
+             return (long) string.length();
+         } else if (arg.getClass().isArray()) {
+             return (long) Array.getLength(arg);
+         }
+         return null;
+     }
+```
+
+This is because this basic function would not work with versions of ScriptBasic prior to
+1.0.4

site/design.md

@@ -1,6 +1,4 @@
 # Design Considerations
-
- This document summarizes some of the design considerations that we followed developing ScriptBasic for Java.
 
  The main design goals of ScriptBasic for Java were to create an interpreted language that is
 
@@ -16,11 +14,9 @@
 
  * 4E: easy to embed, easy to extend
 
- * compile
- 
  * multi-thread
 
- ScriptBasic for Java was developed with similar design goals in mind. We wanted a BASIC interpreter in Java so that
- Java application can access a BASIC interpreter as a scripting extension to their application to be used by the
- business experts.
+We wanted a BASIC interpreter in Java so that
+Java application can access a BASIC interpreter as a scripting extension
+to their application to be used by the business experts.
 

site/index.md

@@ -1,6 +1,37 @@
 # ScriptBasic for Java Documentation
 
+## introduction
+
+These documents will help you to get acquainted with the application and how to use it.
+
+* [Introduction to the application](intro.md)
+
 * [The BASIC language implemented](basic.md) a simple and short language definition and not a BASIC
 programming tutorial
 
-* [How to install SB4J](install.md)... just put it on the classpath
+* [How to install SB4J](install.md) ... just put it on the classpath
+
+* [How to configure](configure.md) ... no need to
+
+* [Design considerations](design.md) ... there were none (just kidding)
+
+* [Name of the game](name.md)
+
+* [Releases](releases.md)
+
+## advanced
+
+These documents will give you more detail into the topics, like embedding the interpreter
+into a host application, writing hook classes that use the service programming interface
+of the interpreter and so on.
+
+* [Index of the advanced topics](advanced/index.md)
+
+* [How to extend ScriptBasic for Java with external Java Methods](advanced/extend.md)
+
+* [How to embed the interpreter as s standard scripting engine](advanced/jsr223tutorial.md)
+This should quite standard as defined by the standard JSR223, but here it is. The extra
+information, which is a bit more than a standard JSR223 tutorial is how the interpreter
+binds the global variables to the JSR defined contexts.
+
+* [How to embed the interpreter using the native ScriptBasic API](advanced/nativeapi.md) 

site/install.md

@@ -63,7 +63,7 @@ use the ScriptBasic for Java native interface.
 Place the JAR file on the classpath and use the native interface
 
 ```
-        EngineApi engine = EngineApi.getEngine();
+        ScriptBasic engine = ScriptBasic.getEngine();
         engine.eval("print \"hello world\"");
 ```
 

site/intro.md

@@ -18,7 +18,7 @@
 
  For the same reason the language implemented is very simple. It implements only a very limited set
  of commands and operators. Each command is implemented that is needed to create embedded scripts but nothing more.
- You can assign values to variables, loop, execute conditional code (IF statement), print to the standard output
+ You can assign values to variables, loop, execute conditional code (`IF` statement), print to the standard output
  and call subroutines. You can handle arrays. Anything else you need in a BASIC script? To communicate with the embedding application
  more than just printing to the output the program can call Java static methods or instance methods in case an
  object is stored in a BASIC variable. To do that the usual `object.method(params)` format can be used, or just

site/name.md

@@ -8,7 +8,7 @@ For example the default file name for the configuration file that ScriptBasic us
 ScriptBasic for Java does not need configuration generally though.)
 
 "ScriptBasic" without the starting `j` or without saying that this is for java denotes the
-classic version of ScriptBasic. The classic version was developed by the same authors from 1997 till 2006 and was and is still used
+classic version of ScriptBasic. The classic version was developed from 1997 till 2006 and was and is still used
 by many application as an embedded language. To name two: Sarian routers can be programmed using ScriptBasic and the company
 EZ-R Stats uses ScriptBasic to develop audit routines into their application.
 
@@ -24,4 +24,6 @@ language and interpreter in an article, blog or other human readable text.
 
 Use jScriptBasic only if the repetitive use of the long name would distract the reader.
 
-Use `sb4j` when the notation is used in software.
+Use `sb4j` when the notation is used in software.
+
+Anyway: you are free to use any name so long as long others understand what you mean.

site/releases.md

@@ -16,8 +16,11 @@ of a release is `M.m.b` where `M` is the major version, `m` is the minor version
 * `b` is increased if there is some bugfix but the features of the language and the interpreter did not change.
 
 
-## 1.0.0-SNAPSHOT
-The current development version. This is not a release version.
+## 1.0.0
+The first release in 2012
+
+## 1.0.4
+
 
 ## 1.0.5-SNAPSHOT
 Version that supports Java 9. 

src/main/java/com/scriptbasic/Engine.java

@@ -1,6 +1,6 @@
 package com.scriptbasic;
 
-import com.scriptbasic.api.EngineApi;
+import com.scriptbasic.api.ScriptBasic;
 import com.scriptbasic.api.ScriptBasicException;
 import com.scriptbasic.api.Subroutine;
 import com.scriptbasic.errors.BasicInterpreterInternalError;
@@ -16,7 +16,7 @@
 import java.util.HashMap;
 import java.util.Map;
 
-public class Engine implements EngineApi {
+public class Engine implements ScriptBasic {
 
     private final Map<String, Subroutine> subroutines = new HashMap<>();
     private Reader input;