Standard Library
Back to library index.
Package std-fileio (in std.i) - generic file i/o
Index of documented functions or symbols:
DOCUMENT close, f
closes the I/O stream F (returned earlier by the open function).
If F is a simple variable reference (as opposed to an expression),
the close function will set F to nil. If F is the only reference
to the I/O stream, then "close, f" is equivalent to "f= []".
Otherwise, "close, f" will close the file (so that subsequent
I/O operations will fail) and print a warning message about the
outstanding ("stale") references.
SEE ALSO: open, read, write, rdline, bookmark, backup, save, restore, rename, remove
DOCUMENT f= create(filename) is a synonym for f= open(filename, "w") Creates a new text file FILENAME, destroying any existing file of that name. Use the write function to write into the file F.
DOCUMENT fflush, file flush the I/O buffers for the text file FILE. (Binary files are flushed at the proper times automatically.) You should only need this after a write, especially to a pipe.
DOCUMENT filepath(file); Return full path name of file(s). Argument FILE can be either an open binary/text file or an array of file names (in the latter case tilde expansion is performed and the result will have the same shape as the input).
DOCUMENT f= open(filename)
or f= open(filename, filemode)
or f= open(filename, filemode, errmode)
opens the file FILENAME according to FILEMODE (both are strings).
If ERRMODE is non-nil and non-zero, fail by returning nil F,
otherwise failure to open or create the file is a runtime error.
To use ERRMODE to check for the existence of a file:
if (open(filename,"r",1)) file_exists;
else file_does_not_exist;
The return value F is an IOStream (or just stream for short). When
the last reference to this return value is discarded, the file will
be closed. The file can also be explicitly closed with the close
function. The FILEMODE determines whether the file is to be
opened in read, write, or update mode, and whether writes are
restricted to the end-of-file (append mode). FILEMODE also
determines whether the file is opened as a text file or as a
binary file. FILEMODE can have the following values, which are
the same as for the ANSI standard fopen function:
"r" - read only
"w" - write only, random access, existing file overwritten
"a" - write only, forced to end-of-file,
existing file preserved
"r+" - read/write, random access, existing file preserved
"w+" - read/write, random access, existing file overwritten
"a+" - read/write, reads random access,
writes forced to end-of-file, existing file preserved
"rb" "wb" "ab" "r+b" "rb+" "w+b" "wb+" "a+b" "ab+"
without b means text file, with b means binary file
The default FILEMODE is "r" -- open an existing text file for
reading.
The read and write functions perform I/O on text files.
I/O to binary files may be performed explicitly using the save
and restore functions, or implicitly by using the stream variable
F as if it were a data structure instance (e.g.- f.x refers to
variable x in the binary file f).
SEE ALSO: create, close, read, write, rdline, bookmark, backup, popen, vopen, rename, remove, save, restore
DOCUMENT f= popen(command, mode) opens a pipe to COMMAND, which is executed as with the system function. If MODE is 0, the returned file handle is open for reading, and you are reading the stdout produced by COMMAND. If MODE is 1, f is opened for writing and you are writing to the stdin read by COMMAND.
SEE: rename
DOCUMENT contents = vclose(handle) closes a file handle opened with vopen, returning the contents as an array. As a side effect, the handle is set to nil [], as in close. For a read-only handle, the contents will be the same as the array passed to the vopen call which returned the handle. For a read-write handle, vclose is the only way to get back what you have written to the file; if you close such a file using the ordinary close function, you will lose what you have written.
DOCUMENT f = vopen(source)
or f = vopen(source, 1)
opens SOURCE, which can be a string or char array, as if it were a
file, returning a file handle. The file handle will be a text file
unless the optional second argument is non-nil and non-zero, as in
the second form. For the case of a binary file, SOURCE must be a
char array. Any dimensions of a char array are ignored in either
case. For a text file, if SOURCE is a string array, each array element
is treated as one line of text. For a text file char array, "\n",
"\r", "\r\n", or "\0" are all recognized as newline markers. These
are read only files.
If SOURCE is nil, the file handle will be read-write. After writing
the in-memory file, you can retrieve the finished array with the
vclose function. If the file is text, the array will be an array of
strings, one per line. If the file is binary, the array will be an
array of char.
DOCUMENT bytes = vpack(var1, var2, ...);
or vfile = vopen(,1);
vpack, vfile, var1, var2, ...;
vpack, vfile, var3, var4, ...;
...
bytes = vpack(vfile);
pack variables into a byte stream, preserving data types and dimensions.
If the first argument is an in-memory file created by vopen(,1), then
vpack appends the variables to the file; to close the file, supply
no new variables to pack. The VARi must be arrays, and may not be
pointers or struct instances. If you want to store pointers or struct
instances and preserve variable names, use vsave.
The returned byte stream contains the primitive data formats (as
returned by get_primitives), so it can be used on a platform other
than the one on which vpack was run.
DOCUMENT c = vsave(var1, var2, ...);
or c = vsave(var1, ..., string(namea), vara, ...);
or vfile = createb(char);
vsave, vfile, var1, var2, ...;
vsave, vfile, var3, var4, ...;
...
c = vsave(vfile);
save the array variables VAR1, VAR2, ..., in the char array that is
returned. Any of the variables may instead be a string expression
NAMEA followed by the value VARA of the variable. The NAMEA argument
is recognized as the name of the following argument by being an
expression; arguments that are to be stored in f must be simple
variable references. You can achieve this as shown by placing the
argument inside a call to string(), or by adding "", or simply by
passing a constant string value like "myvarname".
If you wish to build up a char array over several calls to vsave,
pass the first argument VFILE, which you create with createb(char).
A final call with no variables returns the char array and closes
VFILE.
You can pass the returned char array to openb, f=openb(c), to get
an in-memory file handle f like any other binary file handle,
allowing you to use the restore function, or the f.var1 syntax,
or the get_member function.
You can set the internal primitives using the prims= keyword; see
createb for details.
SEE ALSO: openb, vopen, vpack, restore, get_member, wrap_args
DOCUMENT eof = vunpack(bytes, var1, var2, ...);
or nextvar = vunpack(bytes,-);
or vunpack, bytes;
unpack variables VAR1, VAR2, ... from a byte stream BYTES created
with vpack. The vunpack call modifies BYTES to save the number of
variables which have already been unpacked, so you can perform the
unpack operation with multiple calls. Calling vunpack as a
subroutine with no VARi arguments resets this information, restoring
BYTES to its original value (that is, as vpack returned it).
Called as a function, vunpack returns 1 if more variables remain
to be unpacked, or 0 if no more variables remain.
For example, if BYTES contains 5 variables:
bytes = vpack(var1, var2, var3, var4, var5);
You can retrieve the variables by a single call to vunpack:
vunpack, bytes, var1, var2, var3, var4, var5;
Or by a sequence of calls to vunpack:
vunpack, bytes, var1, var2;
vunpack, bytes, var3, var4, var5;