loop: new records clause.

1 files changed, 35 insertions, 0 deletions

diff --git a/cppawk-iter.1 b/cppawk-iter.1
index 490c9cb..b45cd30 100644
--- a/cppawk-iter.1
+++ b/cppawk-iter.1
@@ -77,6 +77,7 @@ iter \- powerful, user-extensible iteration language for Awk
   list (\fIiter\fP, \fIvar\fP, \fIlist\fP)
   fields (\fIvar\fP)
   keys (\fIkey\fP, \fIarray\fP)
+  records (\fIfile\fP)
 
   \fI// collect items into lists\fP
   collect (\fIvar\fP, \fIexpr\fP)
@@ -684,6 +685,40 @@ parameter. The
 variable is set to each index in turn. The keys are not visited in
 any specific, required order.
 
+.SS Loop clause \fIrecords\fP
+.bk
+.B Syntax:
+
+.ft B
+  records (\fIfile\fP)
+.ft R
+
+.B Description:
+
+The
+.B records
+clause is based on the Awk
+.B getline
+operator. The
+.I file
+expression is evaluated once, prior to the loop, and its value is
+remembered. Then prior to each iteration of the loop, a record is
+read from the file using
+.B getline
+which has the effect of setting the record parameter
+.B $0
+and the positional parameters
+.BR $1 ,
+.BR $2 ", ..."
+in the manner documented of the
+.B getline
+operator.
+
+When the loop terminates normally, the file is closed, unless
+it is the string
+.B \(dq-\(dq
+denoting standard input.
+
 .SH LOOP CLAUSES: COLLECTION INTO LISTS
 .bk
 .SS Loop clauses \fIcollect\fP and \fIcollect_plus\fP