| \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. |