Document fileinput.
This commit is contained in:
parent
a8e262b0b2
commit
35ca0d69e1
|
@ -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.
|
|
@ -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.
|
Loading…
Reference in New Issue