READLN - read file a line at a time

SYNOPSIS

<READLN [options] $file[ /]>
  ... statements ...
[</READLN>]

DESCRIPTION
The READLN statement reads the given $file one line at a time, returning the line(s) in successive values of $ret. If $file is "-" (a single dash), the standard input is read instead. For each line read, the statements inside the READLN block are executed, and $ret is looped over, much like a SQL statement.

As in SQL, the special variables $loop and $next are set inside the READLN loop. At the end of the READLN statement, $loop is the number of iterations completed (e.g. the number of lines returned); $next is that number plus the initial SKIP if any.

A BREAK statement, if encountered, will exit the loop.

Options that may be given are:

• REV Read the file in reverse order, and start from the end. This is extremely useful in analyzing the latest information appended to a constantly-growing file, such as a web server log, without attempting to read the entire file (often impossible). Note that the START and END expressions are matched in line-read order, which means that with REV the END line will occur at or before the START line in the file itself.

• START=$expr Start returning lines with the first one that matches the REX expression $expr. By default lines are returned starting with the first in the file (or last if REV).

• END=$expr Stop returning lines when one matches the REX expression $expr; it will be the last line. By default the rest of the file or MAXLINES lines, whichever is first, will be returned.

• MAX=$n Return at most $n lines, e.g. loop at most $n times. Note that this is not necessarily the number of lines actually read from the file: returned lines (and hence MAX) are counted after the application of the START expression and MAXLINES. If unspecified, empty or negative, no limit is imposed.

• MAXLINES=$lines Read at most $lines from the file. Note that this is not necessarily the number of lines returned (looped over); it is a limit to read before the START and END expressions are matched. E.g. if the START expression matches line 50, the END expression matches line 100, and MAXLINES is 75, only 26 lines will be returned: lines 50 through 75. MAXLINES is a "safety limit" in case the START or END expressions are not found: otherwise a huge file might be read in its entirety looking for a START expression that does not exist, before any line(s) are returned at all. If unspecified, empty or negative, no limit is imposed.

• ROW As in SQL, don't append lines into a list in $ret, but replace previous value each time. Saves memory if a copious file is being read and the lines need be examined only once. Also enables functions called inside the block to return multiple values for $ret, since $ret is then not a loop variable.

• SKIP=$n As in SQL, skip the first $n returned lines. Note that this is counted after START.

DIAGNOSTICS
READLN returns a list of the lines read from the file (without newlines), or the last line read if ROW is set.

EXAMPLE

Last 100 lines of the web server log:
<READLN REV ROW MAXLINES=100 /usr/local/httpd/logs/transfer.log>
  $ret <BR>
</READLN>

CAVEATS
The READLN statement was added in version 2.1.901200000 19980723. MAX and $next were added in version 2.6.938650000 19990929.

Note the distinction between MAX and MAXLINES: MAX applies to returned lines (i.e. loop iterations), whereas MAXLINES applies to read lines, some of which may not be returned (e.g. before the START expression).

Support for standard input was added in version 2.6.939250000 19991006. If the REV attribute is applied when reading from a non-file standard input, READLN can consume a lot of memory, as the entire file must be read in first. It is not recommended to read standard input in a CGI environment, as it may have been already read for POST form variables.

SEE ALSO
read, spew, WRITE