link bufread
March 11,1995; Charles A. Shartsis
This file is in the public domain.
Synopsis:
bufopen(s) Open a file name s for buffered read and lookahead
bufread(f) Read the next line from file f
bufnext(f, n) Return the next nth record from file f
without changing the next record to be read by
bufread
bufclose(f) Close file f
____________________________________________________________
These procedures provide a mechanism for looking ahead an
arbitrary number of records in an open file while still
keeping track of the logical current record and end-of-file.
Although similar in intent to the procedures in buffer.icn, these
procedures are used differently. The procedures bufopen,
bufread, and bufclose were designed to closely mirror the
built-in open, read, and close.
A code segment like
file := open("name", "r") | stop("open failed")
while line := read(file) do {
...process current line...
}
close(file)
can be changed to the following with no difference in behavior:
file := bufopen("name", "r") | stop("open failed")
while line := bufread(file) do {
...process current line...
}
bufclose(file)
However in addition to processing the current line, one may
also process subsequent lines BEFORE they are logically
read:
file := bufopen("name", "r") | stop("open failed")
while line := bufread(file) do {
...process current line...
line := bufnext(file,1) # return next line
...process next line...
line := bufnext(file,2) # return 2nd next line
...process 2nd next line...
...etc...
}
bufclose(file)
In the code above, calls to bufnext do not affect the results of
subsequent bufread's. The bufread procedure always steps through
the input file a line at a time without skipping lines whether or
not bufnext is called.
____________________________________________________________
Here is a more detailed description of the procedures:
bufopen(s)
==========
Produces a file resulting from opening s for reading ("r" option),
but fails if the file cannot be opened. if s is missing or
the value of s is &null, then standard input is opened and
&input is returned. Unlike the Icon open function, bufopen()
can and must be called prior to any call to bufread or bufnext
involving standard input. Unlike named files, only one buffered
standard input may be open at any given time.
Default:
s &null (indicates &input should be opened for buffered
reading)
Errors (from open):
103 s not string
Errors (new):
Attempt to open standard input when currently open
bufread(f)
==========
Produces a string consisting of the next line from f, but fails on
end of file. Calls to bufnext do not affect the results of
subsequent bufread's. The procedure bufread always steps
through a file a line at a time without skipping lines. The
procedure bufread fails when a logical end of file is
reached, i.e., when the physical end of file has
been reached AND the internal buffer is empty.
Default:
f &input
Errors:
f is not a file
f not opened for buffered reads (includes &input)
bufnext(f, n)
=============
Produces a string consisting of the nth next line from f after
the current line. It fails when the physical end of file
has been reached.
Default:
f &input
n 1 (the next line after the current one)
Errors:
f is not a file
f not opened for buffered reads (includes &input)
n not convertible to integer
n not positive
bufclose(f)
===========
Produces f after closing it. Standard input must
be closed before it can be reopened using bufopen.
If standard input is closed, all lines read using bufnext
are lost when it is reopened. In general, there is no
practical reason to bufclose and then bufopen standard input.
One may want to bufclose standard input to release its
internal buffer for garbage collection.
Default:
f &input
Errors (from close):
105 f not file