Added documentation for the xreadlines module & related changes. The

documentation was written by Jeff Epler (thanks!).

Doc/ACKS

@@ -38,6 +38,7 @@ Andrew Dalke
 Ben Darnell
 Robert Donohue
 Fred L. Drake, Jr.
+Jeff Epler
 Michael Ernst
 Blame Andy Eskilsson
 Martijn Faassen

Doc/Makefile.deps

@@ -190,6 +190,7 @@ LIBFILES= $(MANSTYLES) $(COMMONTEX) \
 	../lib/libuu.tex \
 	../lib/libsunaudio.tex \
 	../lib/libfileinput.tex \
+	../lib/libxreadlines.tex \
 	../lib/libimaplib.tex \
 	../lib/libpoplib.tex \
 	../lib/libcalendar.tex \

Doc/lib/lib.tex

@@ -121,6 +121,7 @@ and how to embed it in other applications.
 \input{libarray}
 \input{libcfgparser}
 \input{libfileinput}
+\input{libxreadlines}
 \input{libcalendar}
 \input{libcmd}
 \input{libshlex}

Doc/lib/libstdtypes.tex

@@ -1101,15 +1101,21 @@ Files have the following methods:
 \end{methoddesc}
 
 \begin{methoddesc}[file]{write}{str}
-Write a string to the file.  There is no return value.  Note: Due to
-buffering, the string may not actually show up in the file until
-the \method{flush()} or \method{close()} method is called.
+  Write a string to the file.  There is no return value.  Note: Due to
+  buffering, the string may not actually show up in the file until
+  the \method{flush()} or \method{close()} method is called.
 \end{methoddesc}
 
 \begin{methoddesc}[file]{writelines}{list}
-Write a list of strings to the file.  There is no return value.
-(The name is intended to match \method{readlines()};
-\method{writelines()} does not add line separators.)
+  Write a list of strings to the file.  There is no return value.
+  (The name is intended to match \method{readlines()};
+  \method{writelines()} does not add line separators.)
+\end{methoddesc}
+
+\begin{methoddesc}[file]{xreadlines}{}
+  Equivalent to
+  \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
+  (See the \refmodule{xreadlines} module for more information.)
 \end{methoddesc}
 
 

Doc/lib/libxreadlines.tex

@@ -0,0 +1,52 @@
+\section{\module{xreadlines} ---
+         Efficient iteration over a file}
+
+\declaremodule{extension}{xreadlines}
+\modulesynopsis{Efficient iteration over the lines of a file.}
+
+This module defines a new object type which can efficiently iterate
+over the lines of a file.  An xreadlines object is a sequence type
+which implements simple in-order indexing beginning at \code{0}, as
+required by \keyword{for} statement or the
+\function{filter()} function.
+
+Thus, the code
+
+\begin{verbatim}
+import xreadlines, sys
+
+for line in xreadlines.xreadlines(sys.stdin):
+    pass
+\end{verbatim}
+
+has approximately the same speed and memory consumption as
+
+\begin{verbatim}
+while 1:
+    lines = sys.stdin.readlines(8*1024)
+    if not lines: break
+    for line in lines:
+        pass
+\end{verbatim}
+
+except the clarity of the \keyword{for} statement is retained in the
+former case.
+
+\begin{funcdesc}{xreadlines}{fileobj}
+  Return a new xreadlines object which will iterate over the contents
+  of \var{fileobj}.  \var{fileobj} must have a \method{readlines()}
+  method that supports the \var{sizehint} parameter.
+\end{funcdesc}
+
+An xreadlines object \var{s} supports the following sequence
+operation:
+
+\begin{tableii}{c|l}{code}{Operation}{Result}
+ \lineii{\var{s}[\var{i}]}{\var{i}'th line of \var{s}}
+\end{tableii}
+
+If successive values of \var{i} are not sequential starting from
+\code{0}, this code will raise \exception{RuntimeError}.
+
+After the last line of the file is read, this code will raise an
+\exception{IndexError}.