File Handling allows you to manipulate files on disk using seperate, simple operations. This allows for efficiency.
/fopen [-nox] <name> <filename>
/fopen opens the filename and use the specified name to reference it.
The command fail by default if the file does not exist, the -n switch creates the file if it does not exist, but fails if it exists. The -o switch creates a new file if it does not exist but overwrites the file if it exists. The -x switch opens the file for exclusive access, others processus cannot access that file
Note: if /fopen fails, it does not halt processing, you must check $ferr to see if any error occured, see below.
After you opened a file with /fopen, you have a pointer of the content of the file, it starts at 0. This pointer is the starting position to read/write from.
/fseek -lnwr <name> <position>
/fseek sets the read/write pointer to the specified <position> in the file, unless you use a switch:
- -l - sets the pointer to the beginning of the Nth line, use <position> to specify the Nth line
- -n - sets the pointer to the beginning of the next line (from the current position of the read/write pointer), this does not take a parameter
- -w - sets the pointer to the beginning of the line matching the wildcard expression, use <position> to specify the wildcard expression
- -r - sets the pointer to the beginning of the line matching the regular expression, use <position> to specify the regular expression
If /fseek fails, it sets the pointer to the end of the file, you must check $fopen().eof or $feof to know if /fseek failed.
/fwrite [-bn] <name> <text | &binvar>
/fwrite allows you to write to the file at the current pointer position, -b specify a binary variable, -n adds a $crlf at the end of the line.
/fclose <name | wildcard>
/flist just lists all the current handles.
$fopen(name | N)
$fopen Returns the name of that handle if it exists, or the Nth handle.
- .fname - returns the complete filename opened for that handle
- .pos - returns the current position of the read/write pointer
- .eof - returns $true if the end of the file has been reached
- .err - returns $true if an error occured on the file
Note: Since file access errors will not halt a script, the eof and err properties or identifiers must be checked after each file access command.
$fread(name | N)
This form of $fread returns the next $crlf delimited line, useful to read line by line
$fread(name | N, M, &binvar)
This form of $fread returns the number of bytes read (from the file pointed by name or the Nth handle) into the specified binary variable, where M is the number of bytes to read.
$fgetc(name | N)
$fgetc returns the next character.
When to use File handling
Let's take a look at /write, /write is a powerful tool which allows you to write to a file according to severals predefined options.
A simple "/write filename.txt line" involves the following file handling operations:
- /fopen - opens the file
- /fseek - goes to the end of the file
- /fwrite - writes to the file
- /fclose - closes the file
So, executing /write twice involves 8 file handling operations; the more you have to write, the more operations you create. If you do /write three times, the 12 operations can be reduced to 5:
; assuming text.txt is empty write test.txt line 1 write test.txt line 2 write test.txt line 3 ; is better written as fopen test test.txt fwrite -n line 1 fwrite -n line 2 fwrite -n line 3 fclose test
The same thing applies to reading, $read opens the file, try to match and close the file, so any consecutive call to $read means the file is opened/closed each time. If you are looking for a particular line, you can avoid multiple $read calls by searching with /fseek.
Whenever you are going to use /write or $read in a loop to write/read a lot of things, if the loop isn't small and if the file isn't small, it might get slow very quickly, and you should consider using file handling.