3 provides the TextFile class, which gives an interface to text files
4 that (optionally) takes care of stripping comments, ignoring blank
5 lines, and joining lines with backslashes."""
14 """Provides a file-like object that takes care of all the things you
15 commonly want to do when processing a text file that has some
16 line-by-line syntax: strip comments (as long as "#" is your
17 comment character), skip blank lines, join adjacent lines by
18 escaping the newline (ie. backslash at end of line), strip
19 leading and/or trailing whitespace. All of these are optional
20 and independently controllable.
22 Provides a 'warn()' method so you can generate warning messages that
23 report physical line number, even if the logical line in question
24 spans multiple physical lines. Also provides 'unreadline()' for
25 implementing line-at-a-time lookahead.
27 Constructor is called as:
29 TextFile (filename=None, file=None, **options)
31 It bombs (RuntimeError) if both 'filename' and 'file' are None;
32 'filename' should be a string, and 'file' a file object (or
33 something that provides 'readline()' and 'close()' methods). It is
34 recommended that you supply at least 'filename', so that TextFile
35 can include it in warning messages. If 'file' is not supplied,
36 TextFile creates its own using the 'open()' builtin.
38 The options are all boolean, and affect the value returned by
40 strip_comments [default: true]
41 strip from "#" to end-of-line, as well as any whitespace
42 leading up to the "#" -- unless it is escaped by a backslash
43 lstrip_ws [default: false]
44 strip leading whitespace from each line before returning it
45 rstrip_ws [default: true]
46 strip trailing whitespace (including line terminator!) from
47 each line before returning it
48 skip_blanks [default: true}
49 skip lines that are empty *after* stripping comments and
50 whitespace. (If both lstrip_ws and rstrip_ws are false,
51 then some lines may consist of solely whitespace: these will
52 *not* be skipped, even if 'skip_blanks' is true.)
53 join_lines [default: false]
54 if a backslash is the last non-newline character on a line
55 after stripping comments and whitespace, join the following line
56 to it to form one "logical line"; if N consecutive lines end
57 with a backslash, then N+1 physical lines will be joined to
58 form one logical line.
59 collapse_join [default: false]
60 strip leading whitespace from lines that are joined to their
61 predecessor; only matters if (join_lines and not lstrip_ws)
63 Note that since 'rstrip_ws' can strip the trailing newline, the
64 semantics of 'readline()' must differ from those of the builtin file
65 object's 'readline()' method! In particular, 'readline()' returns
66 None for end-of-file: an empty string might just be a blank line (or
67 an all-whitespace line), if 'rstrip_ws' is true but 'skip_blanks' is
70 default_options
= { 'strip_comments': 1,
78 def __init__ (self
, filename
=None, file=None, **options
):
79 """Construct a new TextFile object. At least one of 'filename'
80 (a string) and 'file' (a file-like object) must be supplied.
81 They keyword argument options are described above and affect
82 the values returned by 'readline()'."""
84 if filename
is None and file is None:
86 "you must supply either or both of 'filename' and 'file'"
88 # set values for all options -- either from client option hash
89 # or fallback to default_options
90 for opt
in self
.default_options
.keys():
92 setattr (self
, opt
, options
[opt
])
95 setattr (self
, opt
, self
.default_options
[opt
])
97 # sanity check client option hash
98 for opt
in options
.keys():
99 if opt
not in self
.default_options
:
100 raise KeyError, "invalid TextFile option '%s'" % opt
105 self
.filename
= filename
107 self
.current_line
= 0 # assuming that file is at BOF!
109 # 'linebuf' is a stack of lines that will be emptied before we
110 # actually read from the file; it's only populated by an
111 # 'unreadline()' operation
115 def open (self
, filename
):
116 """Open a new file named 'filename'. This overrides both the
117 'filename' and 'file' arguments to the constructor."""
119 self
.filename
= filename
120 self
.file = open (self
.filename
, 'r')
121 self
.current_line
= 0
125 """Close the current file and forget everything we know about it
126 (filename, current line number)."""
131 self
.current_line
= None
134 def gen_error (self
, msg
, line
=None):
137 line
= self
.current_line
138 outmsg
.append(self
.filename
+ ", ")
139 if isinstance(line
, (list, tuple)):
140 outmsg
.append("lines %d-%d: " % tuple (line
))
142 outmsg
.append("line %d: " % line
)
143 outmsg
.append(str(msg
))
144 return ''.join(outmsg
)
147 def error (self
, msg
, line
=None):
148 raise ValueError, "error: " + self
.gen_error(msg
, line
)
150 def warn (self
, msg
, line
=None):
151 """Print (to stderr) a warning message tied to the current logical
152 line in the current file. If the current logical line in the
153 file spans multiple physical lines, the warning refers to the
154 whole range, eg. "lines 3-5". If 'line' supplied, it overrides
155 the current line number; it may be a list or tuple to indicate a
156 range of physical lines, or an integer for a single physical
158 sys
.stderr
.write("warning: " + self
.gen_error(msg
, line
) + "\n")
162 """Read and return a single logical line from the current file (or
163 from an internal buffer if lines have previously been "unread"
164 with 'unreadline()'). If the 'join_lines' option is true, this
165 may involve reading multiple physical lines concatenated into a
166 single string. Updates the current line number, so calling
167 'warn()' after 'readline()' emits a warning about the physical
168 line(s) just read. Returns None on end-of-file, since the empty
169 string can occur if 'rstrip_ws' is true but 'strip_blanks' is
172 # If any "unread" lines waiting in 'linebuf', return the top
173 # one. (We don't actually buffer read-ahead data -- lines only
174 # get put in 'linebuf' if the client explicitly does an
177 line
= self
.linebuf
[-1]
184 # read the line, make it None if EOF
185 line
= self
.file.readline()
186 if line
== '': line
= None
188 if self
.strip_comments
and line
:
190 # Look for the first "#" in the line. If none, never
191 # mind. If we find one and it's the first character, or
192 # is not preceded by "\", then it starts a comment --
193 # strip the comment, strip whitespace before it, and
194 # carry on. Otherwise, it's just an escaped "#", so
195 # unescape it (and any other escaped "#"'s that might be
196 # lurking in there) and otherwise leave the line alone.
199 if pos
== -1: # no "#" -- no comments
202 # It's definitely a comment -- either "#" is the first
203 # character, or it's elsewhere and unescaped.
204 elif pos
== 0 or line
[pos
-1] != "\\":
205 # Have to preserve the trailing newline, because it's
206 # the job of a later step (rstrip_ws) to remove it --
207 # and if rstrip_ws is false, we'd better preserve it!
208 # (NB. this means that if the final line is all comment
209 # and has no trailing newline, we will think that it's
210 # EOF; I think that's OK.)
211 eol
= (line
[-1] == '\n') and '\n' or ''
212 line
= line
[0:pos
] + eol
214 # If all that's left is whitespace, then skip line
215 # *now*, before we try to join it to 'buildup_line' --
216 # that way constructs like
218 # # comment that should be ignored
220 # result in "hello there".
221 if line
.strip() == "":
224 else: # it's an escaped "#"
225 line
= line
.replace("\\#", "#")
228 # did previous line end with a backslash? then accumulate
229 if self
.join_lines
and buildup_line
:
232 self
.warn ("continuation line immediately precedes "
236 if self
.collapse_join
:
238 line
= buildup_line
+ line
240 # careful: pay attention to line number when incrementing it
241 if isinstance(self
.current_line
, list):
242 self
.current_line
[1] = self
.current_line
[1] + 1
244 self
.current_line
= [self
.current_line
,
246 # just an ordinary line, read it as usual
248 if line
is None: # eof
251 # still have to be careful about incrementing the line number!
252 if isinstance(self
.current_line
, list):
253 self
.current_line
= self
.current_line
[1] + 1
255 self
.current_line
= self
.current_line
+ 1
258 # strip whitespace however the client wants (leading and
259 # trailing, or one or the other, or neither)
260 if self
.lstrip_ws
and self
.rstrip_ws
:
267 # blank line (whether we rstrip'ed or not)? skip to next line
269 if (line
== '' or line
== '\n') and self
.skip_blanks
:
274 buildup_line
= line
[:-1]
277 if line
[-2:] == '\\\n':
278 buildup_line
= line
[0:-2] + '\n'
281 # well, I guess there's some actual content there: return it
287 def readlines (self
):
288 """Read and return the list of all logical lines remaining in the
293 line
= self
.readline()
299 def unreadline (self
, line
):
300 """Push 'line' (a string) onto an internal buffer that will be
301 checked by future 'readline()' calls. Handy for implementing
302 a parser with line-at-a-time lookahead."""
304 self
.linebuf
.append (line
)