Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libfileinput.tex @ 25838:8540887bcec6 2.2
Backport of 2.183:
Fix memory leak in add_subclass() found by NealN with valgrind.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Fri, 18 Oct 2002 13:42:21 +0000 |
| parents | 6493d5e941c2 |
| children | 2ed36833853a |
| 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 | |
|
17714
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
50 is also returned to use during iteration. The parameters to this |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
51 function will be passed along to the constructor of the |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
52 \class{FileInput} class. |
| 7860 | 53 \end{funcdesc} |
| 54 | |
| 55 | |
| 56 The following functions use the global state created by | |
| 57 \function{input()}; if there is no active state, | |
| 58 \exception{RuntimeError} is raised. | |
| 59 | |
| 60 \begin{funcdesc}{filename}{} | |
| 61 Return the name of the file currently being read. Before the first | |
| 62 line has been read, returns \code{None}. | |
| 63 \end{funcdesc} | |
| 64 | |
| 65 \begin{funcdesc}{lineno}{} | |
| 66 Return the cumulative line number of the line that has just been | |
| 67 read. Before the first line has been read, returns \code{0}. After | |
| 68 the last line of the last file has been read, returns the line | |
| 69 number of that line. | |
| 70 \end{funcdesc} | |
| 71 | |
| 72 \begin{funcdesc}{filelineno}{} | |
| 73 Return the line number in the current file. Before the first line | |
| 74 has been read, returns \code{0}. After the last line of the last | |
| 75 file has been read, returns the line number of that line within the | |
| 76 file. | |
| 77 \end{funcdesc} | |
| 78 | |
| 79 \begin{funcdesc}{isfirstline}{} | |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
80 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
|
81 otherwise returns false. |
| 7860 | 82 \end{funcdesc} |
| 83 | |
| 84 \begin{funcdesc}{isstdin}{} | |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
85 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
|
86 otherwise returns false. |
| 7860 | 87 \end{funcdesc} |
| 88 | |
| 89 \begin{funcdesc}{nextfile}{} | |
| 90 Close the current file so that the next iteration will read the | |
| 91 first line from the next file (if any); lines not read from the file | |
| 92 will not count towards the cumulative line count. The filename is | |
| 93 not changed until after the first line of the next file has been | |
| 94 read. Before the first line has been read, this function has no | |
| 95 effect; it cannot be used to skip the first file. After the last | |
| 96 line of the last file has been read, this function has no effect. | |
| 97 \end{funcdesc} | |
| 98 | |
| 99 \begin{funcdesc}{close}{} | |
| 100 Close the sequence. | |
| 101 \end{funcdesc} | |
| 102 | |
| 103 | |
| 104 The class which implements the sequence behavior provided by the | |
| 105 module is available for subclassing as well: | |
| 106 | |
| 107 \begin{classdesc}{FileInput}{\optional{files\optional{, | |
| 108 inplace\optional{, backup}}}} | |
| 109 Class \class{FileInput} is the implementation; its methods | |
| 110 \method{filename()}, \method{lineno()}, \method{fileline()}, | |
| 111 \method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and | |
| 112 \method{close()} correspond to the functions of the same name in the | |
| 113 module. In addition it has a \method{readline()} method which | |
| 114 returns the next input line, and a \method{__getitem__()} method | |
| 115 which implements the sequence behavior. The sequence must be | |
| 116 accessed in strictly sequential order; random access and | |
| 117 \method{readline()} cannot be mixed. | |
| 118 \end{classdesc} | |
| 119 | |
| 120 \strong{Optional in-place filtering:} if the keyword argument | |
| 121 \code{\var{inplace}=1} is passed to \function{input()} or to the | |
| 122 \class{FileInput} constructor, the file is moved to a backup file and | |
|
17714
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
123 standard output is directed to the input file (if a file of the same |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
124 name as the backup file already exists, it will be replaced silently). |
| 7860 | 125 This makes it possible to write a filter that rewrites its input file |
| 126 in place. If the keyword argument \code{\var{backup}='.<some | |
| 127 extension>'} is also given, it specifies the extension for the backup | |
| 128 file, and the backup file remains around; by default, the extension is | |
| 129 \code{'.bak'} and it is deleted when the output file is closed. In-place | |
| 130 filtering is disabled when standard input is read. | |
| 131 | |
| 132 \strong{Caveat:} The current implementation does not work for MS-DOS | |
| 133 8+3 filesystems. |