[mirror_edk2.git] / AppPkg / Applications / Python / Python-2.7.2 / Lib / distutils / text_file.py

"""text_file\r
\r
provides the TextFile class, which gives an interface to text files\r
that (optionally) takes care of stripping comments, ignoring blank\r
lines, and joining lines with backslashes."""\r
\r
__revision__ = "$Id$"\r
\r
import sys\r
\r
\r
class TextFile:\r
\r
    """Provides a file-like object that takes care of all the things you\r
       commonly want to do when processing a text file that has some\r
       line-by-line syntax: strip comments (as long as "#" is your\r
       comment character), skip blank lines, join adjacent lines by\r
       escaping the newline (ie. backslash at end of line), strip\r
       leading and/or trailing whitespace.  All of these are optional\r
       and independently controllable.\r
\r
       Provides a 'warn()' method so you can generate warning messages that\r
       report physical line number, even if the logical line in question\r
       spans multiple physical lines.  Also provides 'unreadline()' for\r
       implementing line-at-a-time lookahead.\r
\r
       Constructor is called as:\r
\r
           TextFile (filename=None, file=None, **options)\r
\r
       It bombs (RuntimeError) if both 'filename' and 'file' are None;\r
       'filename' should be a string, and 'file' a file object (or\r
       something that provides 'readline()' and 'close()' methods).  It is\r
       recommended that you supply at least 'filename', so that TextFile\r
       can include it in warning messages.  If 'file' is not supplied,\r
       TextFile creates its own using the 'open()' builtin.\r
\r
       The options are all boolean, and affect the value returned by\r
       'readline()':\r
         strip_comments [default: true]\r
           strip from "#" to end-of-line, as well as any whitespace\r
           leading up to the "#" -- unless it is escaped by a backslash\r
         lstrip_ws [default: false]\r
           strip leading whitespace from each line before returning it\r
         rstrip_ws [default: true]\r
           strip trailing whitespace (including line terminator!) from\r
           each line before returning it\r
         skip_blanks [default: true}\r
           skip lines that are empty *after* stripping comments and\r
           whitespace.  (If both lstrip_ws and rstrip_ws are false,\r
           then some lines may consist of solely whitespace: these will\r
           *not* be skipped, even if 'skip_blanks' is true.)\r
         join_lines [default: false]\r
           if a backslash is the last non-newline character on a line\r
           after stripping comments and whitespace, join the following line\r
           to it to form one "logical line"; if N consecutive lines end\r
           with a backslash, then N+1 physical lines will be joined to\r
           form one logical line.\r
         collapse_join [default: false]\r
           strip leading whitespace from lines that are joined to their\r
           predecessor; only matters if (join_lines and not lstrip_ws)\r
\r
       Note that since 'rstrip_ws' can strip the trailing newline, the\r
       semantics of 'readline()' must differ from those of the builtin file\r
       object's 'readline()' method!  In particular, 'readline()' returns\r
       None for end-of-file: an empty string might just be a blank line (or\r
       an all-whitespace line), if 'rstrip_ws' is true but 'skip_blanks' is\r
       not."""\r
\r
    default_options = { 'strip_comments': 1,\r
                        'skip_blanks':    1,\r
                        'lstrip_ws':      0,\r
                        'rstrip_ws':      1,\r
                        'join_lines':     0,\r
                        'collapse_join':  0,\r
                      }\r
\r
    def __init__ (self, filename=None, file=None, **options):\r
        """Construct a new TextFile object.  At least one of 'filename'\r
           (a string) and 'file' (a file-like object) must be supplied.\r
           They keyword argument options are described above and affect\r
           the values returned by 'readline()'."""\r
\r
        if filename is None and file is None:\r
            raise RuntimeError, \\r
                  "you must supply either or both of 'filename' and 'file'"\r
\r
        # set values for all options -- either from client option hash\r
        # or fallback to default_options\r
        for opt in self.default_options.keys():\r
            if opt in options:\r
                setattr (self, opt, options[opt])\r
\r
            else:\r
                setattr (self, opt, self.default_options[opt])\r
\r
        # sanity check client option hash\r
        for opt in options.keys():\r
            if opt not in self.default_options:\r
                raise KeyError, "invalid TextFile option '%s'" % opt\r
\r
        if file is None:\r
            self.open (filename)\r
        else:\r
            self.filename = filename\r
            self.file = file\r
            self.current_line = 0       # assuming that file is at BOF!\r
\r
        # 'linebuf' is a stack of lines that will be emptied before we\r
        # actually read from the file; it's only populated by an\r
        # 'unreadline()' operation\r
        self.linebuf = []\r
\r
\r
    def open (self, filename):\r
        """Open a new file named 'filename'.  This overrides both the\r
           'filename' and 'file' arguments to the constructor."""\r
\r
        self.filename = filename\r
        self.file = open (self.filename, 'r')\r
        self.current_line = 0\r
\r
\r
    def close (self):\r
        """Close the current file and forget everything we know about it\r
           (filename, current line number)."""\r
\r
        self.file.close ()\r
        self.file = None\r
        self.filename = None\r
        self.current_line = None\r
\r
\r
    def gen_error (self, msg, line=None):\r
        outmsg = []\r
        if line is None:\r
            line = self.current_line\r
        outmsg.append(self.filename + ", ")\r
        if isinstance(line, (list, tuple)):\r
            outmsg.append("lines %d-%d: " % tuple (line))\r
        else:\r
            outmsg.append("line %d: " % line)\r
        outmsg.append(str(msg))\r
        return ''.join(outmsg)\r
\r
\r
    def error (self, msg, line=None):\r
        raise ValueError, "error: " + self.gen_error(msg, line)\r
\r
    def warn (self, msg, line=None):\r
        """Print (to stderr) a warning message tied to the current logical\r
           line in the current file.  If the current logical line in the\r
           file spans multiple physical lines, the warning refers to the\r
           whole range, eg. "lines 3-5".  If 'line' supplied, it overrides\r
           the current line number; it may be a list or tuple to indicate a\r
           range of physical lines, or an integer for a single physical\r
           line."""\r
        sys.stderr.write("warning: " + self.gen_error(msg, line) + "\n")\r
\r
\r
    def readline (self):\r
        """Read and return a single logical line from the current file (or\r
           from an internal buffer if lines have previously been "unread"\r
           with 'unreadline()').  If the 'join_lines' option is true, this\r
           may involve reading multiple physical lines concatenated into a\r
           single string.  Updates the current line number, so calling\r
           'warn()' after 'readline()' emits a warning about the physical\r
           line(s) just read.  Returns None on end-of-file, since the empty\r
           string can occur if 'rstrip_ws' is true but 'strip_blanks' is\r
           not."""\r
\r
        # If any "unread" lines waiting in 'linebuf', return the top\r
        # one.  (We don't actually buffer read-ahead data -- lines only\r
        # get put in 'linebuf' if the client explicitly does an\r
        # 'unreadline()'.\r
        if self.linebuf:\r
            line = self.linebuf[-1]\r
            del self.linebuf[-1]\r
            return line\r
\r
        buildup_line = ''\r
\r
        while 1:\r
            # read the line, make it None if EOF\r
            line = self.file.readline()\r
            if line == '': line = None\r
\r
            if self.strip_comments and line:\r
\r
                # Look for the first "#" in the line.  If none, never\r
                # mind.  If we find one and it's the first character, or\r
                # is not preceded by "\", then it starts a comment --\r
                # strip the comment, strip whitespace before it, and\r
                # carry on.  Otherwise, it's just an escaped "#", so\r
                # unescape it (and any other escaped "#"'s that might be\r
                # lurking in there) and otherwise leave the line alone.\r
\r
                pos = line.find("#")\r
                if pos == -1:           # no "#" -- no comments\r
                    pass\r
\r
                # It's definitely a comment -- either "#" is the first\r
                # character, or it's elsewhere and unescaped.\r
                elif pos == 0 or line[pos-1] != "\\":\r
                    # Have to preserve the trailing newline, because it's\r
                    # the job of a later step (rstrip_ws) to remove it --\r
                    # and if rstrip_ws is false, we'd better preserve it!\r
                    # (NB. this means that if the final line is all comment\r
                    # and has no trailing newline, we will think that it's\r
                    # EOF; I think that's OK.)\r
                    eol = (line[-1] == '\n') and '\n' or ''\r
                    line = line[0:pos] + eol\r
\r
                    # If all that's left is whitespace, then skip line\r
                    # *now*, before we try to join it to 'buildup_line' --\r
                    # that way constructs like\r
                    #   hello \\\r
                    #   # comment that should be ignored\r
                    #   there\r
                    # result in "hello there".\r
                    if line.strip() == "":\r
                        continue\r
\r
                else:                   # it's an escaped "#"\r
                    line = line.replace("\\#", "#")\r
\r
\r
            # did previous line end with a backslash? then accumulate\r
            if self.join_lines and buildup_line:\r
                # oops: end of file\r
                if line is None:\r
                    self.warn ("continuation line immediately precedes "\r
                               "end-of-file")\r
                    return buildup_line\r
\r
                if self.collapse_join:\r
                    line = line.lstrip()\r
                line = buildup_line + line\r
\r
                # careful: pay attention to line number when incrementing it\r
                if isinstance(self.current_line, list):\r
                    self.current_line[1] = self.current_line[1] + 1\r
                else:\r
                    self.current_line = [self.current_line,\r
                                         self.current_line+1]\r
            # just an ordinary line, read it as usual\r
            else:\r
                if line is None:        # eof\r
                    return None\r
\r
                # still have to be careful about incrementing the line number!\r
                if isinstance(self.current_line, list):\r
                    self.current_line = self.current_line[1] + 1\r
                else:\r
                    self.current_line = self.current_line + 1\r
\r
\r
            # strip whitespace however the client wants (leading and\r
            # trailing, or one or the other, or neither)\r
            if self.lstrip_ws and self.rstrip_ws:\r
                line = line.strip()\r
            elif self.lstrip_ws:\r
                line = line.lstrip()\r
            elif self.rstrip_ws:\r
                line = line.rstrip()\r
\r
            # blank line (whether we rstrip'ed or not)? skip to next line\r
            # if appropriate\r
            if (line == '' or line == '\n') and self.skip_blanks:\r
                continue\r
\r
            if self.join_lines:\r
                if line[-1] == '\\':\r
                    buildup_line = line[:-1]\r
                    continue\r
\r
                if line[-2:] == '\\\n':\r
                    buildup_line = line[0:-2] + '\n'\r
                    continue\r
\r
            # well, I guess there's some actual content there: return it\r
            return line\r
\r
    # readline ()\r
\r
\r
    def readlines (self):\r
        """Read and return the list of all logical lines remaining in the\r
           current file."""\r
\r
        lines = []\r
        while 1:\r
            line = self.readline()\r
            if line is None:\r
                return lines\r
            lines.append (line)\r
\r
\r
    def unreadline (self, line):\r
        """Push 'line' (a string) onto an internal buffer that will be\r
           checked by future 'readline()' calls.  Handy for implementing\r
           a parser with line-at-a-time lookahead."""\r
\r
        self.linebuf.append (line)\r
Commit	Line	Data
4710c53d	1	"""text_file\r
	2	\r
	3	provides the TextFile class, which gives an interface to text files\r
	4	that (optionally) takes care of stripping comments, ignoring blank\r
	5	lines, and joining lines with backslashes."""\r
	6	\r
	7	__revision__ = "$Id$"\r
	8	\r
	9	import sys\r
	10	\r
	11	\r
	12	class TextFile:\r
	13	\r
	14	"""Provides a file-like object that takes care of all the things you\r
	15	commonly want to do when processing a text file that has some\r
	16	line-by-line syntax: strip comments (as long as "#" is your\r
	17	comment character), skip blank lines, join adjacent lines by\r
	18	escaping the newline (ie. backslash at end of line), strip\r
	19	leading and/or trailing whitespace. All of these are optional\r
	20	and independently controllable.\r
	21	\r
	22	Provides a 'warn()' method so you can generate warning messages that\r
	23	report physical line number, even if the logical line in question\r
	24	spans multiple physical lines. Also provides 'unreadline()' for\r
	25	implementing line-at-a-time lookahead.\r
	26	\r
	27	Constructor is called as:\r
	28	\r
	29	TextFile (filename=None, file=None, **options)\r
	30	\r
	31	It bombs (RuntimeError) if both 'filename' and 'file' are None;\r
	32	'filename' should be a string, and 'file' a file object (or\r
	33	something that provides 'readline()' and 'close()' methods). It is\r
	34	recommended that you supply at least 'filename', so that TextFile\r
	35	can include it in warning messages. If 'file' is not supplied,\r
	36	TextFile creates its own using the 'open()' builtin.\r
	37	\r
	38	The options are all boolean, and affect the value returned by\r
	39	'readline()':\r
	40	strip_comments [default: true]\r
	41	strip from "#" to end-of-line, as well as any whitespace\r
	42	leading up to the "#" -- unless it is escaped by a backslash\r
	43	lstrip_ws [default: false]\r
	44	strip leading whitespace from each line before returning it\r
	45	rstrip_ws [default: true]\r
	46	strip trailing whitespace (including line terminator!) from\r
	47	each line before returning it\r
	48	skip_blanks [default: true}\r
	49	skip lines that are empty after stripping comments and\r
	50	whitespace. (If both lstrip_ws and rstrip_ws are false,\r
	51	then some lines may consist of solely whitespace: these will\r
	52	not be skipped, even if 'skip_blanks' is true.)\r
	53	join_lines [default: false]\r
	54	if a backslash is the last non-newline character on a line\r
	55	after stripping comments and whitespace, join the following line\r
	56	to it to form one "logical line"; if N consecutive lines end\r
	57	with a backslash, then N+1 physical lines will be joined to\r
	58	form one logical line.\r
	59	collapse_join [default: false]\r
	60	strip leading whitespace from lines that are joined to their\r
	61	predecessor; only matters if (join_lines and not lstrip_ws)\r
	62	\r
	63	Note that since 'rstrip_ws' can strip the trailing newline, the\r
	64	semantics of 'readline()' must differ from those of the builtin file\r
65	object's 'readline()' method! In particular, 'readline()' returns\r
66	None for end-of-file: an empty string might just be a blank line (or\r
67	an all-whitespace line), if 'rstrip_ws' is true but 'skip_blanks' is\r
68	not."""\r
69	\r
70	default_options = { 'strip_comments': 1,\r
71	'skip_blanks': 1,\r
72	'lstrip_ws': 0,\r
73	'rstrip_ws': 1,\r
74	'join_lines': 0,\r
75	'collapse_join': 0,\r
76	}\r
77	\r
78	def __init__ (self, filename=None, file=None, **options):\r
79	"""Construct a new TextFile object. At least one of 'filename'\r
80	(a string) and 'file' (a file-like object) must be supplied.\r
81	They keyword argument options are described above and affect\r
82	the values returned by 'readline()'."""\r
83	\r
84	if filename is None and file is None:\r
85	raise RuntimeError, \\r
86	"you must supply either or both of 'filename' and 'file'"\r
87	\r
88	# set values for all options -- either from client option hash\r
89	# or fallback to default_options\r
90	for opt in self.default_options.keys():\r
91	if opt in options:\r
92	setattr (self, opt, options[opt])\r
93	\r
94	else:\r
95	setattr (self, opt, self.default_options[opt])\r
96	\r
97	# sanity check client option hash\r
98	for opt in options.keys():\r
99	if opt not in self.default_options:\r
100	raise KeyError, "invalid TextFile option '%s'" % opt\r
101	\r
102	if file is None:\r
103	self.open (filename)\r
104	else:\r
105	self.filename = filename\r
106	self.file = file\r
107	self.current_line = 0 # assuming that file is at BOF!\r
108	\r
109	# 'linebuf' is a stack of lines that will be emptied before we\r
110	# actually read from the file; it's only populated by an\r
111	# 'unreadline()' operation\r
112	self.linebuf = []\r
113	\r
114	\r
115	def open (self, filename):\r
116	"""Open a new file named 'filename'. This overrides both the\r
117	'filename' and 'file' arguments to the constructor."""\r
118	\r
119	self.filename = filename\r
120	self.file = open (self.filename, 'r')\r
121	self.current_line = 0\r
122	\r
123	\r
124	def close (self):\r
125	"""Close the current file and forget everything we know about it\r
126	(filename, current line number)."""\r
127	\r
128	self.file.close ()\r
129	self.file = None\r
130	self.filename = None\r
131	self.current_line = None\r
132	\r
133	\r
134	def gen_error (self, msg, line=None):\r
135	outmsg = []\r
136	if line is None:\r
137	line = self.current_line\r
138	outmsg.append(self.filename + ", ")\r
139	if isinstance(line, (list, tuple)):\r
140	outmsg.append("lines %d-%d: " % tuple (line))\r
141	else:\r
142	outmsg.append("line %d: " % line)\r
143	outmsg.append(str(msg))\r
144	return ''.join(outmsg)\r
145	\r
146	\r
147	def error (self, msg, line=None):\r
148	raise ValueError, "error: " + self.gen_error(msg, line)\r
149	\r
150	def warn (self, msg, line=None):\r
151	"""Print (to stderr) a warning message tied to the current logical\r
152	line in the current file. If the current logical line in the\r
153	file spans multiple physical lines, the warning refers to the\r
154	whole range, eg. "lines 3-5". If 'line' supplied, it overrides\r
155	the current line number; it may be a list or tuple to indicate a\r
156	range of physical lines, or an integer for a single physical\r
157	line."""\r
158	sys.stderr.write("warning: " + self.gen_error(msg, line) + "\n")\r
159	\r
160	\r
161	def readline (self):\r
162	"""Read and return a single logical line from the current file (or\r
163	from an internal buffer if lines have previously been "unread"\r
164	with 'unreadline()'). If the 'join_lines' option is true, this\r
165	may involve reading multiple physical lines concatenated into a\r
166	single string. Updates the current line number, so calling\r
167	'warn()' after 'readline()' emits a warning about the physical\r
168	line(s) just read. Returns None on end-of-file, since the empty\r
169	string can occur if 'rstrip_ws' is true but 'strip_blanks' is\r
170	not."""\r
171	\r
172	# If any "unread" lines waiting in 'linebuf', return the top\r
173	# one. (We don't actually buffer read-ahead data -- lines only\r
174	# get put in 'linebuf' if the client explicitly does an\r
175	# 'unreadline()'.\r
176	if self.linebuf:\r
177	line = self.linebuf[-1]\r
178	del self.linebuf[-1]\r
179	return line\r
180	\r
181	buildup_line = ''\r
182	\r
183	while 1:\r
184	# read the line, make it None if EOF\r
185	line = self.file.readline()\r
186	if line == '': line = None\r
187	\r
188	if self.strip_comments and line:\r
189	\r
190	# Look for the first "#" in the line. If none, never\r
191	# mind. If we find one and it's the first character, or\r
192	# is not preceded by "\", then it starts a comment --\r
193	# strip the comment, strip whitespace before it, and\r
194	# carry on. Otherwise, it's just an escaped "#", so\r
195	# unescape it (and any other escaped "#"'s that might be\r
196	# lurking in there) and otherwise leave the line alone.\r
197	\r
198	pos = line.find("#")\r
199	if pos == -1: # no "#" -- no comments\r
200	pass\r
201	\r
202	# It's definitely a comment -- either "#" is the first\r
203	# character, or it's elsewhere and unescaped.\r
204	elif pos == 0 or line[pos-1] != "\\":\r
205	# Have to preserve the trailing newline, because it's\r
206	# the job of a later step (rstrip_ws) to remove it --\r
207	# and if rstrip_ws is false, we'd better preserve it!\r
208	# (NB. this means that if the final line is all comment\r
209	# and has no trailing newline, we will think that it's\r
210	# EOF; I think that's OK.)\r
211	eol = (line[-1] == '\n') and '\n' or ''\r
212	line = line[0:pos] + eol\r
213	\r
214	# If all that's left is whitespace, then skip line\r
215	# now, before we try to join it to 'buildup_line' --\r
216	# that way constructs like\r
217	# hello \\\r
218	# # comment that should be ignored\r
219	# there\r
220	# result in "hello there".\r
221	if line.strip() == "":\r
222	continue\r
223	\r
224	else: # it's an escaped "#"\r
225	line = line.replace("\\#", "#")\r
226	\r
227	\r
228	# did previous line end with a backslash? then accumulate\r
229	if self.join_lines and buildup_line:\r
230	# oops: end of file\r
231	if line is None:\r
232	self.warn ("continuation line immediately precedes "\r
233	"end-of-file")\r
234	return buildup_line\r
235	\r
236	if self.collapse_join:\r
237	line = line.lstrip()\r
238	line = buildup_line + line\r
239	\r
240	# careful: pay attention to line number when incrementing it\r
241	if isinstance(self.current_line, list):\r
242	self.current_line[1] = self.current_line[1] + 1\r
243	else:\r
244	self.current_line = [self.current_line,\r
245	self.current_line+1]\r
246	# just an ordinary line, read it as usual\r
247	else:\r
248	if line is None: # eof\r
249	return None\r
250	\r
251	# still have to be careful about incrementing the line number!\r
252	if isinstance(self.current_line, list):\r
253	self.current_line = self.current_line[1] + 1\r
254	else:\r
255	self.current_line = self.current_line + 1\r
256	\r
257	\r
258	# strip whitespace however the client wants (leading and\r
259	# trailing, or one or the other, or neither)\r
260	if self.lstrip_ws and self.rstrip_ws:\r
261	line = line.strip()\r
262	elif self.lstrip_ws:\r
263	line = line.lstrip()\r
264	elif self.rstrip_ws:\r
265	line = line.rstrip()\r
266	\r
267	# blank line (whether we rstrip'ed or not)? skip to next line\r
268	# if appropriate\r
269	if (line == '' or line == '\n') and self.skip_blanks:\r
270	continue\r
271	\r
272	if self.join_lines:\r
273	if line[-1] == '\\':\r
274	buildup_line = line[:-1]\r
275	continue\r
276	\r
277	if line[-2:] == '\\\n':\r
278	buildup_line = line[0:-2] + '\n'\r
279	continue\r
280	\r
281	# well, I guess there's some actual content there: return it\r
282	return line\r
283	\r
284	# readline ()\r
285	\r
286	\r
287	def readlines (self):\r
288	"""Read and return the list of all logical lines remaining in the\r
289	current file."""\r
290	\r
291	lines = []\r
292	while 1:\r
293	line = self.readline()\r
294	if line is None:\r
295	return lines\r
296	lines.append (line)\r
297	\r
298	\r
299	def unreadline (self, line):\r
300	"""Push 'line' (a string) onto an internal buffer that will be\r
301	checked by future 'readline()' calls. Handy for implementing\r
302	a parser with line-at-a-time lookahead."""\r
303	\r
304	self.linebuf.append (line)\r