  ----------------------------------
  jScriptBasic Project Documentation
  ----------------------------------
  Peter Verhas
  ----------------------------------
  2012-08-11
  ----------------------------------

Installing ScriptBasic for Java

 There are two different uses of ScriptBasic for Java. The simpler one when you
 just want to start some BASIC program from the command line. The binary package
 of ScriptBasic is a Java JAR file that contains an appropriately configured
 main class that can be executed. The other use is when you want to invoke BASIC
 scripts from some application and you want to use ScriptBasic for Java as an embedded
 script language interpreter.
 
* Command line use

** SHORT

 Just start the jar file using java.

** LONG

 Check that the Java runtime environment (JRE) is installed on your system.
 To do that you can execute the command
 
---
java -version
---

 and you should get some output like
 
---
java version "1.7.0_04"
Java(TM) SE Runtime Environment (build 1.7.0_04-b21)
Java HotSpot(TM) 64-Bit Server VM (build 23.0-b21, mixed mode)
---

 The version of the build number may be different but make sure that the java version you use is
 1.7 or later. SB4J requires java 7.
 
 Locate the SB4J JAR file and the BASIC program you want to execute. Make sure that the BASIC program
 is in a file that has the extension <<<sb>>> or <<<bas>>>. Execute the following command line
 
---
java -jar jscriptbasic-x.y.z.jar myProgram.sb
--- 

 where <<<x.y.z>>> is the version of the interpreter and is part of the file name of the jar file in the
 distribution. For the hello world example on the development server I execute
 
---
java -jar target/jscriptbasic-1.0.0-SNAPSHOT.jar src/test/basic/hello.sb
--- 

 which will print <<<hello>>>.


* Embedded use

** SHORT

 Place the JAR file on the classpath and use the JSR-223 standard interface to invoke ScriptBasic.

** LONG
 
 SB4J is compliant with the {{{http://www.jcp.org/en/jsr/detail?id=223}JSR-223}} standard. If you use this
 interface to integrate ScriptBasic into your application you need know know anything that is specific to
 jScriptBasic. All you have to do it copy the JAR file to a location so that the Java class loader will
 find it. After that start up your application and the JRE will load ScriptBasic automatically using the
 standard {{{http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html}ServiceLoader}} interface.
 
 To get a fast track to integrate jScriptBasic into an application you can have a look at the source code
 that implements the command line version of the interpreter and embeds the interpreter into a 'main' class.
 
 The code is in the package <<<com.scriptbasic.main>>> and the class is <<<CommandLine>>>. The important
 part is:
 
%{snippet|id=x|file=src/main/java/com/scriptbasic/main/CommandLine.java}
 
 The code creates a new <<<javax.script.ScriptEngineManager>>> that manages the loading and the location
 of the interpreter. The command line version of ScriptBasic for Java asks the script engine manager to create
 an interpreter based on the file name extension. As a side effect you can also execute JavaScript programs from
 the command line using the jScriptBasic JAR. The JavaScript interpreter is included in the JRE since the version
 1.7
 
 The following few lines set the standard and error input and output for the program and finally the script
 is executed. At the end the output is flushed and closed so that the characters that were printed by the BASIC
 program are sent out to the console.
 
 To have the interpreter on the command line you can manually copy the JAR file to the classpath, or you can
 add the JAR file to the build process. If you use maven use the following dependency:
 
---
<dependency>
	<groupId>com.scriptbasic</groupId>
	<artifactId>jscriptbasic</artifactId>
	<version>1.0.0</version>
</dependency>
--- 
 
 At the moment the latest release is <<<1.0.0-SNAPSHOT>>>. For the actual state of the different releases
 have a look at the page {{{./releases.html}releases}}.



 Starting on the {{{./advanced/jsr223tutorial.html}page}} you will find a detailed tutorial on how to embed ScriptBasic for Java using the
 JSR223 standard interface.
 
* Advanced
 
 The advanced use of ScriptBasic for Java invoking the special functionalities that are not available through
 the JSR223 standard interface are detailed in a series of separate {{{./advanced/index.html}pages here}}.
