documentation on file extension

Author: verhas

src/site/apt/basic/file.apt

@@ -66,13 +66,92 @@ line = readLine(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
+ 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. There are
+ utility functions that allow you to access the individual elements of a byte buffer. (See below!)
+
 * 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
+ implements 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.
+ 
+ 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.
+
+** 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.
+
+** 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 ans strings.)
+
+---
+l = length(Object)
+---
+
+
 * Other File Operations
 
 ** Deleting a File
@@ -88,9 +167,112 @@ deleteFile fileName
 ** 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.
+
+** 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
+parentDirectory(fileName)
+
+** Renaming a File
+
+ To rename a file you have to call the function
+ 
+---
+renameFile(fileName, newFileName)
+---
+