Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libfileinput.tex @ 16413:8819867f14ef legacy-trunk
Patch derived from Trent's 101162: a Python/C API testing framework.
STILL NEEDS UNIX BUILD CHANGES.
| author | Tim Peters <tim.peters@gmail.com> |
|---|---|
| date | Fri, 02 Feb 2001 05:57:15 +0000 |
| parents | e82e82b3b9ad |
| children | 6493d5e941c2 |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{fileinput} --- |
|
11076
4a1d6c7b0950
Minor wording change in section title.
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
2 Iterate over lines from multiple input streams} |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
3 \declaremodule{standard}{fileinput} |
| 8918 | 4 \moduleauthor{Guido van Rossum}{guido@python.org} |
| 5 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
6 |
| 8918 | 7 \modulesynopsis{Perl-like iteration over lines from multiple input |
| 8 streams, with ``save in place'' capability.} | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
9 |
| 7860 | 10 |
| 11 This module implements a helper class and functions to quickly write a | |
| 12 loop over standard input or a list of files. | |
| 13 | |
| 14 The typical use is: | |
| 15 | |
| 16 \begin{verbatim} | |
| 17 import fileinput | |
| 18 for line in fileinput.input(): | |
| 19 process(line) | |
| 20 \end{verbatim} | |
| 21 | |
| 22 This iterates over the lines of all files listed in | |
| 23 \code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is | |
| 24 empty. If a filename is \code{'-'}, it is also replaced by | |
| 25 \code{sys.stdin}. To specify an alternative list of filenames, pass | |
| 26 it as the first argument to \function{input()}. A single file name is | |
| 27 also allowed. | |
| 28 | |
| 29 All files are opened in text mode. If an I/O error occurs during | |
| 30 opening or reading a file, \exception{IOError} is raised. | |
| 31 | |
| 32 If \code{sys.stdin} is used more than once, the second and further use | |
| 33 will return no lines, except perhaps for interactive use, or if it has | |
| 34 been explicitly reset (e.g. using \code{sys.stdin.seek(0)}). | |
| 35 | |
| 36 Empty files are opened and immediately closed; the only time their | |
| 37 presence in the list of filenames is noticeable at all is when the | |
| 38 last file opened is empty. | |
| 39 | |
| 40 It is possible that the last line of a file does not end in a newline | |
| 41 character; lines are returned including the trailing newline when it | |
| 42 is present. | |
| 43 | |
| 44 The following function is the primary interface of this module: | |
| 45 | |
| 46 \begin{funcdesc}{input}{\optional{files\optional{, | |
| 47 inplace\optional{, backup}}}} | |
| 48 Create an instance of the \class{FileInput} class. The instance | |
| 49 will be used as global state for the functions of this module, and | |
| 50 is also returned to use during iteration. | |
| 51 \end{funcdesc} | |
| 52 | |
| 53 | |
| 54 The following functions use the global state created by | |
| 55 \function{input()}; if there is no active state, | |
| 56 \exception{RuntimeError} is raised. | |
| 57 | |
| 58 \begin{funcdesc}{filename}{} | |
| 59 Return the name of the file currently being read. Before the first | |
| 60 line has been read, returns \code{None}. | |
| 61 \end{funcdesc} | |
| 62 | |
| 63 \begin{funcdesc}{lineno}{} | |
| 64 Return the cumulative line number of the line that has just been | |
| 65 read. Before the first line has been read, returns \code{0}. After | |
| 66 the last line of the last file has been read, returns the line | |
| 67 number of that line. | |
| 68 \end{funcdesc} | |
| 69 | |
| 70 \begin{funcdesc}{filelineno}{} | |
| 71 Return the line number in the current file. Before the first line | |
| 72 has been read, returns \code{0}. After the last line of the last | |
| 73 file has been read, returns the line number of that line within the | |
| 74 file. | |
| 75 \end{funcdesc} | |
| 76 | |
| 77 \begin{funcdesc}{isfirstline}{} | |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
78 Returns true the line just read is the first line of its file, |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
79 otherwise returns false. |
| 7860 | 80 \end{funcdesc} |
| 81 | |
| 82 \begin{funcdesc}{isstdin}{} | |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
83 Returns true if the last line was read from \code{sys.stdin}, |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
84 otherwise returns false. |
| 7860 | 85 \end{funcdesc} |
| 86 | |
| 87 \begin{funcdesc}{nextfile}{} | |
| 88 Close the current file so that the next iteration will read the | |
| 89 first line from the next file (if any); lines not read from the file | |
| 90 will not count towards the cumulative line count. The filename is | |
| 91 not changed until after the first line of the next file has been | |
| 92 read. Before the first line has been read, this function has no | |
| 93 effect; it cannot be used to skip the first file. After the last | |
| 94 line of the last file has been read, this function has no effect. | |
| 95 \end{funcdesc} | |
| 96 | |
| 97 \begin{funcdesc}{close}{} | |
| 98 Close the sequence. | |
| 99 \end{funcdesc} | |
| 100 | |
| 101 | |
| 102 The class which implements the sequence behavior provided by the | |
| 103 module is available for subclassing as well: | |
| 104 | |
| 105 \begin{classdesc}{FileInput}{\optional{files\optional{, | |
| 106 inplace\optional{, backup}}}} | |
| 107 Class \class{FileInput} is the implementation; its methods | |
| 108 \method{filename()}, \method{lineno()}, \method{fileline()}, | |
| 109 \method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and | |
| 110 \method{close()} correspond to the functions of the same name in the | |
| 111 module. In addition it has a \method{readline()} method which | |
| 112 returns the next input line, and a \method{__getitem__()} method | |
| 113 which implements the sequence behavior. The sequence must be | |
| 114 accessed in strictly sequential order; random access and | |
| 115 \method{readline()} cannot be mixed. | |
| 116 \end{classdesc} | |
| 117 | |
| 118 \strong{Optional in-place filtering:} if the keyword argument | |
| 119 \code{\var{inplace}=1} is passed to \function{input()} or to the | |
| 120 \class{FileInput} constructor, the file is moved to a backup file and | |
| 121 standard output is directed to the input file. | |
| 122 This makes it possible to write a filter that rewrites its input file | |
| 123 in place. If the keyword argument \code{\var{backup}='.<some | |
| 124 extension>'} is also given, it specifies the extension for the backup | |
| 125 file, and the backup file remains around; by default, the extension is | |
| 126 \code{'.bak'} and it is deleted when the output file is closed. In-place | |
| 127 filtering is disabled when standard input is read. | |
| 128 | |
| 129 \strong{Caveat:} The current implementation does not work for MS-DOS | |
| 130 8+3 filesystems. |