File

The file access model is closely based on the standard C library stdio.h. An opened file is a value and can be assigned to a variable. The file value has a number of attributes that make it possible for the program to check the file status and read from/write to the file.

A file object is not the same as the file stored on the computer. It exists only after the physical file is opened as an I/O stream associated with the interpreter program. Once it is closed, the file value ceases to exist in the perspective of the Shang interpreter (until the file is reopened).

A file is created using the built-in function fopen

f = fopen("file_name", "mode");
where file_name is the path of the file that is absolute or relative to the current working directory, and mode is the string that contains the options. The valid modes are
r: open text file for reading
w: create text file for writing; discard previous contents if any
a: append; open or create text file for writing at end of file
r+: open text file for update (i.e., reading and writing)
w+: create text file for update; discard previous contents if any
a+: append; open or create text file for update, writing at end
The mode may contain an additional character b, such as w+b, which indicates a binary file.

If fopen is called successfully, the returning value is a file, which has the following attributes (assuming that f = fopen(fname, mode) has been executed):

f.name: a string that contains the absolute path of the file name
f.mode: the mode of the file
f.status: 1 if the file is open, or 0 if it's closed.
f.readline(): reads a line from the file. If end of file is reached, null is returned.
f.writeline(str): writes a line of text string str to the file.
f.close(): closes the file.
f.open(): open the file (if it's closed).
f.eof: 1 if the current position of the file is at end, 0 otherwise.
f.read(n): read n bytes from the file. Return value is a vector of bytes.
f.write(x): write data x (a character string, a scalar, or a vector) to the file.

f.rewind(): set the current position to the beginning of the file.

f.flush(): causes any buffered but unwritten data to be written. the output buffer of the file.

f.getpos(): get the current position (an integer) of file.

f.setpos(n): set the current position of a file to a given value.

f.tell(): get the current position (an integer) of file.

f.seek(whence, offset): set the file position of the stream to a given offset. whence can be "beginning", "current", or "end".
Example: the following makes a copy of a file.
f1 = fopen("pinks.txt", "r");
f2 = fopen("dianthus.txt", "w");
if f1 && f2
     line = f1.readline();
     while line != null
          f2.writeline(line);
          line = f1.readline();
     end
end
f1.close();
f2.close();

Note that file values behave like pointers or references. If you pass a file to a function, the function can write to the same physical file on the disk, instead of a copy of the file (the caller and the called function have the same file instead of two independent copies). If f is a file, after g = f, g will refer to the same physical file. This is unlike any other type of value. But this is not a contradiction to the everything is a value not a reference principle, since the actual files are not part of the system.

oz 2009-12-22