println renamed to printfln and more documentation on file handling

Author: verhas

src/main/java/com/scriptbasic/main/CommandLineExtended.java

@@ -62,6 +62,7 @@ public static void main(final String[] args) throws Exception {
 		lexicalAnalyzer.set(reader);
 		final ExtendedInterpreter interpreter = FactoryUtility
 				.getExtendedInterpreter(factory);
+		interpreter.registerFunctions(FileHandlingFunctions.class);
 		final String classes = System.getProperty("sb4j.extensionclasses");
 		if (classes != null && classes.length() > 0) {
 			String[] classNames = classes.split(",");

src/main/java/com/scriptbasic/utility/functions/file/FileHandlingFunctions.java

@@ -213,7 +213,7 @@ public static void printf(FileHandler fh, String line)
 	}
 
 	@Function(classification = { com.scriptbasic.classification.File.class })
-	public static void println(FileHandler fh, String line)
+	public static void printfln(FileHandler fh, String line)
 			throws IOException, BasicRuntimeException {
 		printf(fh, line);
 		((TextFileWriter) fh).newLine();

src/site/apt/basic.apt

@@ -60,4 +60,7 @@ The BASIC language interpreted by ScriptBasic for Java
  BASIC defined subroutines.
 
  {{{./basic/arrays.html}Arrays}} can be accessed using the <<<[>>> and <<<]>>> brackets. Multidimensional array indices are separated by <<<,>>> comma. There is
- no array of arrays. 
+ no array of arrays.
+ 
+ {{{./basic/file.html}File handling}} is available via an extension class. This extension class is not loaded by default. The
+ embedding application should register this extension class. The command line version does register this class.

src/site/apt/basic/file.apt

@@ -0,0 +1,96 @@
+  ----------------------------------
+  jScriptBasic Project Documentation
+  ----------------------------------
+  Peter Verhas
+  ----------------------------------
+  2012-12-04
+  ----------------------------------
+  
+ScriptBasic for Java File Handling
+
+ ScriptBasic for Java contains an extension class that can be used from BASIC programs
+ to perform file operations. This extension class is <<NOT>> registered by default. The embedding
+ application has to register this class explicitly calling the method
+ 
+---
+interpreter.registerFunctions(FileHandlingFunctions.class);
+--- 
+
+ The command line version does register this class before executing a script, thus you need not specify
+ this class on the command line using the <<<-Dsb4j.extensionclasses>>> command line option.
+ 
+* Opening and Closing a File
+
+ To open a file the function <<<open>>> has to be used.
+ 
+---
+file = open(fileName,mode)
+---
+
+ A file can be opened in four different ways. They can be read or write and each can be text or binary. The default is
+ read and text. The parameter <<<fileName>>> should specify the name of the file and the parameter <<<mode>>> is a two letter
+ text: <<<"rt">>> to read in text mode, <<<"wt">>> write in text mode, <<<"rb">>> read in binary mode,
+ <<<"wb">>> write in binary mode. If the mode is read then this is enoug to specify <<<"t">>> to read in text mode, or
+ <<<"b">>> to read in binary mode. Furthermore if the mode is read in text mode then an empty string <<<"">>> can be used
+ as the <<<mode>>> parameter.
+ 
+ Currently there is no way to open a file in read/write mixed mode. Also the operations you can perform on a text file
+ are separated from the operations available for binary file handling.
+ 
+ The return value of the function <<<open>>> is a file handler that the BASIC program should not use in any other
+ way than passing to other extension functions that are prepared to accept a file handler as argument. This simplest
+ example is he <<<close>>> function:
+ 
+---
+close file
+---
+
+ This function closes the file handle.
+ 
+* Reading a text file
+
+ Reading a text file is available line by line. The function to read a line from a text file is <<<readLine>>>:
+ 
+---
+line = readLine(file)
+---
+
+ The argument to this function has to be the handle returned by the function <<<open>>>. The function reads a line 
+ from the file and returns the line as a string without the line termination character or characters. 
+ 
+ If there is no more line to read the function returns undefined value that you can check calling the functions
+ <<<isDefined>>> or <<<isUndef>>>.
+ 
+* Writing to text file
+
+ Writing to text file is possible using two functions: <<<printfln>>> and <<<printf>>>. Both of the functions
+ accept a file handle and s single string argument. The function <<<printf>>> writes the argument string to the
+ file. The function <<<printfln>>> writes the argument string to the file and also a line ending. This may
+ not be a simple line-feed or carriage return character. The behaviour is operating system dependent, therefore
+ it is safer to use <<<printfln file, string>>> than <<<printf file, string +"\n">>>.
+ 
+* Reading Binary File
+
+* Writing Binary File
+
+* Other File Operations
+
+** Deleting a File
+
+ To delete a file you can use the function
+ 
+---
+deleteFile fileName
+---
+ 
+ The argument to the function is the name of the file.
+ 
+** Listing the Files in a Directory
+
+ To get the names of the files that are in a directory you have to use the function
+---
+fileList = listFiles(directoryName)
+---
+
+ The argument to the function is the name of the directory. The return value is an array of string values
+ containing the names of the files that are in the named directory.

src/site/apt/intro.apt.vm

@@ -66,6 +66,16 @@ java -jar jscriptbasic-${project.version}.jar basicProgram.sb
  ${project.version} which may not be the latest released version. If it finishes with the postfix <<<-SNAPSHOT>>>
  then the version is a development version. Instead use the name of the JAR file you downloaded.)
 
+ Starting with the version 1.0.4 it is possible to specify extension classes for the command line version of the
+ interpreter. To do that you have to use the command line option
+ 
+---
+-Dextensionclasses=comma separated list of fully qualified java extension class names
+--- 
+ 
+ When you specify an extension class you wrote you also have to use the standard Java command line option
+ <<<-cp>>> to specify the location of the classes.
+ 
 * License is Open Source
 
  ScriptBasic for Java is licensed with the GPLv3 license. If you need commercial license contact the developers.

src/test/resources/com/scriptbasic/testprograms/TestFile.bas

@@ -1,11 +1,14 @@
 
 file = open("test.txt","w")
-println file,"hello"
+printfln file,"hello"
 close file
 
 file = open("test.txt","r")
 line = readLine(file)
+eof = readLine(file)
 close file
+assert "eof is not undef",isUndef(eof)
+
 assert "file read was not the same as written", line = "hello"
 deleteFile "test.txt"
 
@@ -37,7 +40,7 @@ for i = 0 to length(fileList)-1
 next i
 
 file = open("file.list.txt","w")
-println file,files
+printfln file,files
 close file
 deleteFile "file.list.txt"