129 lines
5.0 KiB
TeX
129 lines
5.0 KiB
TeX
\section{\module{fileinput} ---
|
|
Iterate over lines from multiple input streams}
|
|
\declaremodule{standard}{fileinput}
|
|
\moduleauthor{Guido van Rossum}{guido@python.org}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
\modulesynopsis{Perl-like iteration over lines from multiple input
|
|
streams, with ``save in place'' capability.}
|
|
|
|
|
|
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.
|