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
. 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 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 (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
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
.
DIAGNOSTICSREADLN
returns a list of the lines read from the file
(without newlines), or the last line read if ROW
behavior is in effect.
EXAMPLELast 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.