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