Document fileinput.

2 files changed, 248 insertions, 0 deletions

diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex
new file mode 100644
index 0000000..0c0e81b
--- /dev/null
+++ b/Doc/lib/libfileinput.tex
@@ -0,0 +1,124 @@
+% Documentation heavily adapted from module docstring.
+
+\section{Standard Module \module{fileinput}}
+\stmodindex{fileinput}
+\label{module-fileinput}
+
+This module implements a helper class and functions to quickly write a
+loop over standard input or a list of files.
+
+The typical use is:
+
+\begin{verbatim}
+import fileinput
+for line in fileinput.input():
+    process(line)
+\end{verbatim}
+
+This iterates over the lines of all files listed in
+\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
+empty.  If a filename is \code{'-'}, it is also replaced by
+\code{sys.stdin}.  To specify an alternative list of filenames, pass
+it as the first argument to \function{input()}.  A single file name is
+also allowed.
+
+All files are opened in text mode.  If an I/O error occurs during
+opening or reading a file, \exception{IOError} is raised.
+
+If \code{sys.stdin} is used more than once, the second and further use
+will return no lines, except perhaps for interactive use, or if it has
+been explicitly reset (e.g. using \code{sys.stdin.seek(0)}).
+
+Empty files are opened and immediately closed; the only time their
+presence in the list of filenames is noticeable at all is when the
+last file opened is empty.
+
+It is possible that the last line of a file does not end in a newline
+character; lines are returned including the trailing newline when it
+is present.
+
+The following function is the primary interface of this module:
+
+\begin{funcdesc}{input}{\optional{files\optional{,
+                       inplace\optional{, backup}}}}
+  Create an instance of the \class{FileInput} class.  The instance
+  will be used as global state for the functions of this module, and
+  is also returned to use during iteration.
+\end{funcdesc}
+
+
+The following functions use the global state created by
+\function{input()}; if there is no active state,
+\exception{RuntimeError} is raised.
+
+\begin{funcdesc}{filename}{}
+  Return the name of the file currently being read.  Before the first
+  line has been read, returns \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{lineno}{}
+  Return the cumulative line number of the line that has just been
+  read.  Before the first line has been read, returns \code{0}.  After
+  the last line of the last file has been read, returns the line
+  number of that line.
+\end{funcdesc}
+
+\begin{funcdesc}{filelineno}{}
+  Return the line number in the current file.  Before the first line
+  has been read, returns \code{0}.  After the last line of the last
+  file has been read, returns the line number of that line within the
+  file.
+\end{funcdesc}
+
+\begin{funcdesc}{isfirstline}{}
+  Return true iff the line just read is the first line of its file.
+\end{funcdesc}
+
+\begin{funcdesc}{isstdin}{}
+  Returns true iff the last line was read from \code{sys.stdin}.
+\end{funcdesc}
+
+\begin{funcdesc}{nextfile}{}
+  Close the current file so that the next iteration will read the
+  first line from the next file (if any); lines not read from the file
+  will not count towards the cumulative line count.  The filename is
+  not changed until after the first line of the next file has been
+  read.  Before the first line has been read, this function has no
+  effect; it cannot be used to skip the first file.  After the last
+  line of the last file has been read, this function has no effect.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+  Close the sequence.
+\end{funcdesc}
+
+
+The class which implements the sequence behavior provided by the
+module is available for subclassing as well:
+
+\begin{classdesc}{FileInput}{\optional{files\optional{,
+                             inplace\optional{, backup}}}}
+  Class \class{FileInput} is the implementation; its methods
+  \method{filename()}, \method{lineno()}, \method{fileline()},
+  \method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and
+  \method{close()} correspond to the functions of the same name in the
+  module.  In addition it has a \method{readline()} method which
+  returns the next input line, and a \method{__getitem__()} method
+  which implements the sequence behavior.  The sequence must be
+  accessed in strictly sequential order; random access and
+  \method{readline()} cannot be mixed.
+\end{classdesc}
+
+\strong{Optional in-place filtering:} if the keyword argument
+\code{\var{inplace}=1} is passed to \function{input()} or to the
+\class{FileInput} constructor, the file is moved to a backup file and
+standard output is directed to the input file.
+This makes it possible to write a filter that rewrites its input file
+in place.  If the keyword argument \code{\var{backup}='.<some
+extension>'} is also given, it specifies the extension for the backup
+file, and the backup file remains around; by default, the extension is
+\code{'.bak'} and it is deleted when the output file is closed.  In-place
+filtering is disabled when standard input is read.
+
+\strong{Caveat:} The current implementation does not work for MS-DOS
+8+3 filesystems.
diff --git a/Doc/libfileinput.tex b/Doc/libfileinput.tex
new file mode 100644
index 0000000..0c0e81b
--- /dev/null
+++ b/Doc/libfileinput.tex
@@ -0,0 +1,124 @@
+% Documentation heavily adapted from module docstring.
+
+\section{Standard Module \module{fileinput}}
+\stmodindex{fileinput}
+\label{module-fileinput}
+
+This module implements a helper class and functions to quickly write a
+loop over standard input or a list of files.
+
+The typical use is:
+
+\begin{verbatim}
+import fileinput
+for line in fileinput.input():
+    process(line)
+\end{verbatim}
+
+This iterates over the lines of all files listed in
+\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
+empty.  If a filename is \code{'-'}, it is also replaced by
+\code{sys.stdin}.  To specify an alternative list of filenames, pass
+it as the first argument to \function{input()}.  A single file name is
+also allowed.
+
+All files are opened in text mode.  If an I/O error occurs during
+opening or reading a file, \exception{IOError} is raised.
+
+If \code{sys.stdin} is used more than once, the second and further use
+will return no lines, except perhaps for interactive use, or if it has
+been explicitly reset (e.g. using \code{sys.stdin.seek(0)}).
+
+Empty files are opened and immediately closed; the only time their
+presence in the list of filenames is noticeable at all is when the
+last file opened is empty.
+
+It is possible that the last line of a file does not end in a newline
+character; lines are returned including the trailing newline when it
+is present.
+
+The following function is the primary interface of this module:
+
+\begin{funcdesc}{input}{\optional{files\optional{,
+                       inplace\optional{, backup}}}}
+  Create an instance of the \class{FileInput} class.  The instance
+  will be used as global state for the functions of this module, and
+  is also returned to use during iteration.
+\end{funcdesc}
+
+
+The following functions use the global state created by
+\function{input()}; if there is no active state,
+\exception{RuntimeError} is raised.
+
+\begin{funcdesc}{filename}{}
+  Return the name of the file currently being read.  Before the first
+  line has been read, returns \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{lineno}{}
+  Return the cumulative line number of the line that has just been
+  read.  Before the first line has been read, returns \code{0}.  After
+  the last line of the last file has been read, returns the line
+  number of that line.
+\end{funcdesc}
+
+\begin{funcdesc}{filelineno}{}
+  Return the line number in the current file.  Before the first line
+  has been read, returns \code{0}.  After the last line of the last
+  file has been read, returns the line number of that line within the
+  file.
+\end{funcdesc}
+
+\begin{funcdesc}{isfirstline}{}
+  Return true iff the line just read is the first line of its file.
+\end{funcdesc}
+
+\begin{funcdesc}{isstdin}{}
+  Returns true iff the last line was read from \code{sys.stdin}.
+\end{funcdesc}
+
+\begin{funcdesc}{nextfile}{}
+  Close the current file so that the next iteration will read the
+  first line from the next file (if any); lines not read from the file
+  will not count towards the cumulative line count.  The filename is
+  not changed until after the first line of the next file has been
+  read.  Before the first line has been read, this function has no
+  effect; it cannot be used to skip the first file.  After the last
+  line of the last file has been read, this function has no effect.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+  Close the sequence.
+\end{funcdesc}
+
+
+The class which implements the sequence behavior provided by the
+module is available for subclassing as well:
+
+\begin{classdesc}{FileInput}{\optional{files\optional{,
+                             inplace\optional{, backup}}}}
+  Class \class{FileInput} is the implementation; its methods
+  \method{filename()}, \method{lineno()}, \method{fileline()},
+  \method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and
+  \method{close()} correspond to the functions of the same name in the
+  module.  In addition it has a \method{readline()} method which
+  returns the next input line, and a \method{__getitem__()} method
+  which implements the sequence behavior.  The sequence must be
+  accessed in strictly sequential order; random access and
+  \method{readline()} cannot be mixed.
+\end{classdesc}
+
+\strong{Optional in-place filtering:} if the keyword argument
+\code{\var{inplace}=1} is passed to \function{input()} or to the
+\class{FileInput} constructor, the file is moved to a backup file and
+standard output is directed to the input file.
+This makes it possible to write a filter that rewrites its input file
+in place.  If the keyword argument \code{\var{backup}='.<some
+extension>'} is also given, it specifies the extension for the backup
+file, and the backup file remains around; by default, the extension is
+\code{'.bak'} and it is deleted when the output file is closed.  In-place
+filtering is disabled when standard input is read.
+
+\strong{Caveat:} The current implementation does not work for MS-DOS
+8+3 filesystems.