file

ScriptBasic for Java File Handling

ScriptBasic contains full fledged file handling support. Since most of the BASIC scripts running in a Java application are not allowed to access directly files on the application machine the file handling support is not switched on by default.

The file handling is supported by 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

import com.scriptbasic.utility.functions.file.FileHandlingFunctions;
  ...
            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.

The rest of the page describes the BASIC functions that are implemented by this extension class and are available for the BASIC programs when the extension class is registered in the interpreter.

Opening and Closing a File

To open a file the function open can be used as follows:

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 behavior is operating system dependent, therefore it is safer to use printfln file, string than printf file, string +"\n".

Reading Binary File

When a file is opened in binary mode you can read bytes from the file. To do that you have to call the function

byteBuffer = read(fileHandler, length)

fileHandler is the value returned by the function open, and length has to be an integer value, specifying the number of bytes that you want to read from the file.

The function will return a newly allocated byte buffer. Byte buffer is not accessible directly from BASIC, the language itself does not support byte buffers. There are utility functions that allow you to access the individual elements of a byte buffer. (See below!) These utility functions are always available for the BASIC programs, not only when the file handling extension is registered.

Writing Binary File

To write a binary file you have to call the function

write(fileHandler, byteBuffer)

fileHandler is the value returned by the function open, and the byteBuffer has to be a byte buffer that contains the bytes to be written into the file. For more information how to handle byte buffers read the next section.

Byte Buffer Handling

Managing binary data you need byte buffers. Since byte and byte array is not part of the language the sb4j interpreter implemented extension functions are necessary to create, read and write a byte buffer. This section describes the functions that are available to manage byte buffers. Note that these functions are not part of the file handling extension and as such are registered by the interpreter by default not only in the command line version.

To get a new byte buffer you need to call the function

buffer = byteBuffer(length)

The function argument length has to be an integer value and should specify the number of bytes the buffer should contain. The file handling method read() also returns a byte buffer.

To get a byte from the buffer you can use the function

byte = getByte(byteBuffer, Long)

that will return an integer value. To set a value in the array you have to call

setByte(byteBuffer, index, value)

The argument byteBuffer is the buffer, index is the index value that should be between zero and the length of the buffer minus one. The value parameter has to be an integer value between -127 and 255. The value will be converted to a byte value. Values from 0 to 255 will be converted to the byte values 0x00 to 0xFF. The values from -127 to -1 will be converted to 0x80 to 0xFF.

Conversion Between Byte Buffer and String

To get the bytes of a string in utf-8 encoding you have to call

byteBuffer = getStringBytes(string)

The argument string has to be some string value and the function will return the byte buffer that contains the byte array representation of the parameter string in UTF-8 character encoding. The reverse function is

string = stringifyBuffer(byteBuffer)

that will convert the bytes stored in the byteBuffer to string using UTF-8 character encoding.

There is no support for other character class. Usually BASIC scripts do not deal with byte buffers at all and in case there is need for special character code handling then a new utility class can easily be created based on the implementation of byte buffers in UtilityFunctions.java.

determine the Length of a Byte Buffer

The function length() can be used to determine the length of a byte buffer. (Note that the same function works for arrays and strings.)

l = length(Object)

Technically bcause the data type for a BASIC byte buffer is byte[] the function length() works exactly the same as it works for any array that may be passed to the BASIC program from Java.

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.

Getting the Absolute File Name

To get the absolute name of the file containing the full path to the file you can call the function:

string = absoluteFileName(String)

Checking File Permissions

There are numerous functions that you can use to check file permissions and other features. These functions return boolean value:

fileExists(fileName)
fileCanExecute(fileName)
fileIsExecutable(fileName)
fileIsReadable(fileName)
fileIsWritable(fileName)
isDirectory(fileName)
isFile(fileName)
isHidden(fileName)

Setting File Permissions

In addition to checking file permissions youc an also set file permissions.

setExecutable(fileName, permission, ownerOnly)
setReadable(fileName, permission, ownerOnly)
setWritable(fileName, permission, ownerOnly)

sets the executable/readable/writable permission for the file named fileName. If the boolean value permission is true then the permissions will be set otherwise reset. The parameter ownerOwnly controls if the permission will only be set for the owner of the file or anybody else.

setRedOnly(fileName)

sets the file to be read only.

Getting the Length of a File

length = fileLength(fileName)

returns the length of the file in terms of bytes. Note that in this case the function length() could not be used because that returns the number of characters in the name of the file.

Getting the Free Space on a Drive

bytes = freeSpace(partitionName)

returns the number of free bytes on the named partition.

Getting and Setting the Time a File was Modified

The function

setLastModified(fileName, time)

sets the last modified time of the file to the specified time stamp specified by teh integer value time. To fetch the time the file was modified last time you can call the function:

time = lastModified(fileName)

Creating Directory

To create a directory call the function

success = mkdir(directoryName)

the parameter directoryName should name the directory to be created. The return value is true if the directory was created and false if some error happened.

Getting the Parent Directory of a File or Directory