blob: 0c0e81bac24a2999aec8f4ff9660fbacaa7986ff [file] [log] [blame]
Fred Drake35ca0d61998-04-04 04:20:51 +00001% Documentation heavily adapted from module docstring.
2
3\section{Standard Module \module{fileinput}}
4\stmodindex{fileinput}
5\label{module-fileinput}
6
7This module implements a helper class and functions to quickly write a
8loop over standard input or a list of files.
9
10The typical use is:
11
12\begin{verbatim}
13import fileinput
14for line in fileinput.input():
15 process(line)
16\end{verbatim}
17
18This iterates over the lines of all files listed in
19\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
20empty. If a filename is \code{'-'}, it is also replaced by
21\code{sys.stdin}. To specify an alternative list of filenames, pass
22it as the first argument to \function{input()}. A single file name is
23also allowed.
24
25All files are opened in text mode. If an I/O error occurs during
26opening or reading a file, \exception{IOError} is raised.
27
28If \code{sys.stdin} is used more than once, the second and further use
29will return no lines, except perhaps for interactive use, or if it has
30been explicitly reset (e.g. using \code{sys.stdin.seek(0)}).
31
32Empty files are opened and immediately closed; the only time their
33presence in the list of filenames is noticeable at all is when the
34last file opened is empty.
35
36It is possible that the last line of a file does not end in a newline
37character; lines are returned including the trailing newline when it
38is present.
39
40The following function is the primary interface of this module:
41
42\begin{funcdesc}{input}{\optional{files\optional{,
43 inplace\optional{, backup}}}}
44 Create an instance of the \class{FileInput} class. The instance
45 will be used as global state for the functions of this module, and
46 is also returned to use during iteration.
47\end{funcdesc}
48
49
50The following functions use the global state created by
51\function{input()}; if there is no active state,
52\exception{RuntimeError} is raised.
53
54\begin{funcdesc}{filename}{}
55 Return the name of the file currently being read. Before the first
56 line has been read, returns \code{None}.
57\end{funcdesc}
58
59\begin{funcdesc}{lineno}{}
60 Return the cumulative line number of the line that has just been
61 read. Before the first line has been read, returns \code{0}. After
62 the last line of the last file has been read, returns the line
63 number of that line.
64\end{funcdesc}
65
66\begin{funcdesc}{filelineno}{}
67 Return the line number in the current file. Before the first line
68 has been read, returns \code{0}. After the last line of the last
69 file has been read, returns the line number of that line within the
70 file.
71\end{funcdesc}
72
73\begin{funcdesc}{isfirstline}{}
74 Return true iff the line just read is the first line of its file.
75\end{funcdesc}
76
77\begin{funcdesc}{isstdin}{}
78 Returns true iff the last line was read from \code{sys.stdin}.
79\end{funcdesc}
80
81\begin{funcdesc}{nextfile}{}
82 Close the current file so that the next iteration will read the
83 first line from the next file (if any); lines not read from the file
84 will not count towards the cumulative line count. The filename is
85 not changed until after the first line of the next file has been
86 read. Before the first line has been read, this function has no
87 effect; it cannot be used to skip the first file. After the last
88 line of the last file has been read, this function has no effect.
89\end{funcdesc}
90
91\begin{funcdesc}{close}{}
92 Close the sequence.
93\end{funcdesc}
94
95
96The class which implements the sequence behavior provided by the
97module is available for subclassing as well:
98
99\begin{classdesc}{FileInput}{\optional{files\optional{,
100 inplace\optional{, backup}}}}
101 Class \class{FileInput} is the implementation; its methods
102 \method{filename()}, \method{lineno()}, \method{fileline()},
103 \method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and
104 \method{close()} correspond to the functions of the same name in the
105 module. In addition it has a \method{readline()} method which
106 returns the next input line, and a \method{__getitem__()} method
107 which implements the sequence behavior. The sequence must be
108 accessed in strictly sequential order; random access and
109 \method{readline()} cannot be mixed.
110\end{classdesc}
111
112\strong{Optional in-place filtering:} if the keyword argument
113\code{\var{inplace}=1} is passed to \function{input()} or to the
114\class{FileInput} constructor, the file is moved to a backup file and
115standard output is directed to the input file.
116This makes it possible to write a filter that rewrites its input file
117in place. If the keyword argument \code{\var{backup}='.<some
118extension>'} is also given, it specifies the extension for the backup
119file, and the backup file remains around; by default, the extension is
120\code{'.bak'} and it is deleted when the output file is closed. In-place
121filtering is disabled when standard input is read.
122
123\strong{Caveat:} The current implementation does not work for MS-DOS
1248+3 filesystems.