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 $ret. In (syntax) version 8 and later, the variable $ret.off is set to the file offset of the start of the corresponding ($ret) line, and $ret.size is set to the line's byte size (including unreturned EOL characters, if any). If $file is "-" (a single dash), the standard input is read instead. For each line read, the statements inside the <READLN> block are executed.

As in <SQL>, the special variables $loop and $next are set inside and at the end the <READLN> loop (if the looping syntax is used).

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.

Note that in version 8 and later syntax - i.e. when the syntaxversion pragma (here) is 8 or more - return values never accumulate in $ret in looping statements. Thus the corresponding ROW flag is unneeded, and not accepted.

Options that may be given are:

• OFFSET=$offset

  Read the file starting at offset $offset. Negative offsets are relative to end of file. The default (or if empty-string or no value given) is start of file if reading forward, end of file if reverse. Note that pipes (e.g. for standard input) may not be seekable and may result in an error or unexpected results if used with a non-empty OFFSET. Offsets before start of file or beyond EOF are treated as start of file and EOF, respectively. Added in (syntax) version 8.

• 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 (until MAXLINES reached) 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

  Note that in version 8 and later syntax - i.e. when the syntaxversion pragma (here) is 8 or more - return values never accumulate in $ret in looping statements. Thus the corresponding ROW flag is unneeded, and not accepted. It is only valid in version 7 and earlier syntax.

  As in <SQL>, do not accumulate 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 behavior is in effect.

EXAMPLE

Last 100 lines of the web server log:
<READLN REV 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.

The syntaxversion pragma (here) affects the syntax of this statement: the ROW flag is not accepted in version 8 and later.

SEE ALSO
read, spew, WRITE