Revision as of 10:02, 19 September 2014

File Handling allows you to manipulate files on disk using seperate, simple operations. This allows for efficiency.

To understand how it works, you must be familiar with text file operations such as /write and $read.

/fopen

/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 exists, the -n switch create the file if it does not exist, fails if it exists. The -o switch create a new file if it does not exist but overwrite 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

/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.

/fwrite

/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

/fclose <name | wildcard>

/fclose closes all the matching name (wildcard expression allowed)

/flist

/flist just lists all the current handles.

$fopen(name | N)

Returns the name of that handle if it exists, or the Nth handle.

Properties:

• .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

In a script, $ferr = $fopen(handle).err and $feof = $fopen(handle).eof, always returns the state of last involved handle in a file handing command.

Note: the .eof and .err properties must be checked after each file access command or identifier, since file access errors will not halt a script.

$fread(name | N)

Returns the next $crlf delimited line, useful to read line by line

$fread(name | N, M, &binvar)

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)

Returns the next character.

Example

Let's take a looke 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 have, considers 3 /write, 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. You can apply all $read search options with /fseek.