Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / dist / module-distutils.textfile.html
CommitLineData
920dae64
AT
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="dist.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="dist.html" title='Distributing Python Modules' />
8<link rel='index' href='genindex.html' title='Index' />
9<link rel='last' href='about.html' title='About this document...' />
10<link rel='help' href='about.html' title='About this document...' />
11<link rel="next" href="module-distutils.version.html" />
12<link rel="prev" href="module-distutils.sysconfig.html" />
13<link rel="parent" href="api-reference.html" />
14<link rel="next" href="module-distutils.version.html" />
15<meta name='aesop' content='information' />
16<title>10.23 distutils.text_file -- The TextFile class</title>
17</head>
18<body>
19<DIV CLASS="navigation">
20<div id='top-navigation-panel' xml:id='top-navigation-panel'>
21<table align="center" width="100%" cellpadding="0" cellspacing="2">
22<tr>
23<td class='online-navigation'><a rel="prev" title="10.22 distutils.sysconfig "
24 href="module-distutils.sysconfig.html"><img src='../icons/previous.png'
25 border='0' height='32' alt='Previous Page' width='32' /></A></td>
26<td class='online-navigation'><a rel="parent" title="10. API Reference"
27 href="api-reference.html"><img src='../icons/up.png'
28 border='0' height='32' alt='Up One Level' width='32' /></A></td>
29<td class='online-navigation'><a rel="next" title="10.24 distutils.version "
30 href="module-distutils.version.html"><img src='../icons/next.png'
31 border='0' height='32' alt='Next Page' width='32' /></A></td>
32<td align="center" width="100%">Distributing Python Modules</td>
33<td class='online-navigation'><img src='../icons/blank.png'
34 border='0' height='32' alt='' width='32' /></td>
35<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
36 border='0' height='32' alt='Module Index' width='32' /></a></td>
37<td class='online-navigation'><a rel="index" title="Index"
38 href="genindex.html"><img src='../icons/index.png'
39 border='0' height='32' alt='Index' width='32' /></A></td>
40</tr></table>
41<div class='online-navigation'>
42<b class="navlabel">Previous:</b>
43<a class="sectref" rel="prev" href="module-distutils.sysconfig.html">10.22 distutils.sysconfig </A>
44<b class="navlabel">Up:</b>
45<a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A>
46<b class="navlabel">Next:</b>
47<a class="sectref" rel="next" href="module-distutils.version.html">10.24 distutils.version </A>
48</div>
49<hr /></div>
50</DIV>
51<!--End of Navigation Panel-->
52
53<H1><A NAME="SECTION00102300000000000000000">
5410.23 <tt class="module">distutils.text_file</tt> -- The TextFile class</A>
55</H1>
56<A NAME="module-distutils.textfile"></A>
57
58<P>
59This module provides the <tt class="class">TextFile</tt> class, which gives an interface
60to text files that (optionally) takes care of stripping comments, ignoring
61blank lines, and joining lines with backslashes.
62
63<P>
64<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
65 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-118' xml:id='l2h-118' class="class">TextFile</tt></b>(</nobr></td>
66 <td><var></var><big>[</big><var>filename=<code>None</code>, file=<code>None</code>, **options</var><big>]</big><var></var>)</td></tr></table></dt>
67<dd>
68This class provides a file-like object that takes care of all
69the things you commonly want to do when processing a text file
70that has some line-by-line syntax: strip comments (as long as <code>#</code>
71is your comment character), skip blank lines, join adjacent lines by
72escaping the newline (ie. backslash at end of line), strip
73leading and/or trailing whitespace. All of these are optional
74and independently controllable.
75
76<P>
77The class provides a <tt class="method">warn()</tt> method so you can generate
78warning messages that report physical line number, even if the
79logical line in question spans multiple physical lines. Also
80provides <tt class="method">unreadline()</tt> for implementing line-at-a-time lookahead.
81
82<P>
83<tt class="class">TextFile</tt> instances are create with either <var>filename</var>, <var>file</var>,
84or both. <tt class="exception">RuntimeError</tt> is raised if both are <code>None</code>.
85<var>filename</var> should be a string, and <var>file</var> a file object (or
86something that provides <tt class="method">readline()</tt> and <tt class="method">close()</tt>
87methods). It is recommended that you supply at least <var>filename</var>,
88so that <tt class="class">TextFile</tt> can include it in warning messages. If
89<var>file</var> is not supplied, <tt class="class">TextFile</tt> creates its own using the
90<tt class="function">open()</tt> built-in function.
91
92<P>
93The options are all boolean, and affect the values returned by
94<tt class="method">readline()</tt>
95
96<P>
97<div class="center"><table class="realtable">
98 <thead>
99 <tr>
100 <th class="center">option name</th>
101 <th class="left" >description</th>
102 <th class="left" >default</th>
103 </tr>
104 </thead>
105 <tbody>
106 <tr><td class="center" valign="baseline"><option name>strip_comments</option></td>
107 <td class="left" >
108strip from "<tt class="character">#</tt>" to end-of-line, as well as any whitespace
109leading up to the "<tt class="character">#</tt>"--unless it is escaped by a backslash</td>
110 <td class="left" >true</td></tr>
111 <tr><td class="center" valign="baseline"><option name>lstrip_ws</option></td>
112 <td class="left" >
113strip leading whitespace from each line before returning it</td>
114 <td class="left" >false</td></tr>
115 <tr><td class="center" valign="baseline"><option name>rstrip_ws</option></td>
116 <td class="left" >
117strip trailing whitespace (including line terminator!) from
118each line before returning it.</td>
119 <td class="left" >true</td></tr>
120 <tr><td class="center" valign="baseline"><option name>skip_blanks</option></td>
121 <td class="left" >
122skip lines that are empty *after* stripping comments and
123whitespace. (If both lstrip_ws and rstrip_ws are false,
124then some lines may consist of solely whitespace: these will
125*not* be skipped, even if <var>skip_blanks</var> is true.)</td>
126 <td class="left" >true</td></tr>
127 <tr><td class="center" valign="baseline"><option name>join_lines</option></td>
128 <td class="left" >
129if a backslash is the last non-newline character on a line
130after stripping comments and whitespace, join the following line
131to it to form one logical line; if N consecutive lines end
132with a backslash, then N+1 physical lines will be joined to
133form one logical line.</td>
134 <td class="left" >false</td></tr>
135 <tr><td class="center" valign="baseline"><option name>collapse_join</option></td>
136 <td class="left" >
137strip leading whitespace from lines that are joined to their
138predecessor; only matters if "<tt class="samp">(join_lines and not lstrip_ws)</tt>"</td>
139 <td class="left" >false</td></tr></tbody>
140</table></div>
141
142<P>
143Note that since <var>rstrip_ws</var> can strip the trailing newline, the
144semantics of <tt class="method">readline()</tt> must differ from those of the builtin file
145object's <tt class="method">readline()</tt> method! In particular, <tt class="method">readline()</tt>
146returns <code>None</code> for end-of-file: an empty string might just be a
147blank line (or an all-whitespace line), if <var>rstrip_ws</var> is true
148but <var>skip_blanks</var> is not.
149
150<P>
151<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
152 <td><nobr><b><tt id='l2h-119' xml:id='l2h-119' class="method">open</tt></b>(</nobr></td>
153 <td><var>filename</var>)</td></tr></table></dt>
154<dd>
155Open a new file <var>filename</var>. This overrides any <var>file</var> or
156<var>filename</var> constructor arguments.
157</dl>
158
159<P>
160<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
161 <td><nobr><b><tt id='l2h-120' xml:id='l2h-120' class="method">close</tt></b>(</nobr></td>
162 <td><var></var>)</td></tr></table></dt>
163<dd>
164Close the current file and forget everything we know about it (including
165the filename and the current line number).
166</dl>
167
168<P>
169<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
170 <td><nobr><b><tt id='l2h-121' xml:id='l2h-121' class="method">warn</tt></b>(</nobr></td>
171 <td><var>msg</var><big>[</big><var>,line=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt>
172<dd>
173Print (to stderr) a warning message tied to the current logical
174line in the current file. If the current logical line in the
175file spans multiple physical lines, the warning refers to the
176whole range, such as "<tt class="samp">"lines 3-5"</tt>". If <var>line</var> is supplied,
177it overrides the current line number; it may be a list or tuple
178to indicate a range of physical lines, or an integer for a
179single physical line.
180</dl>
181
182<P>
183<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
184 <td><nobr><b><tt id='l2h-122' xml:id='l2h-122' class="method">readline</tt></b>(</nobr></td>
185 <td><var></var>)</td></tr></table></dt>
186<dd>
187Read and return a single logical line from the current file (or
188from an internal buffer if lines have previously been ``unread''
189with <tt class="method">unreadline()</tt>). If the <var>join_lines</var> option
190is true, this may involve reading multiple physical lines
191concatenated into a single string. Updates the current line number,
192so calling <tt class="method">warn()</tt> after <tt class="method">readline()</tt> emits a warning
193about the physical line(s) just read. Returns <code>None</code> on end-of-file,
194since the empty string can occur if <var>rstrip_ws</var> is true but
195<var>strip_blanks</var> is not.
196</dl>
197<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
198 <td><nobr><b><tt id='l2h-123' xml:id='l2h-123' class="method">readlines</tt></b>(</nobr></td>
199 <td><var></var>)</td></tr></table></dt>
200<dd>
201Read and return the list of all logical lines remaining in the current file.
202This updates the current line number to the last line of the file.
203</dl>
204<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
205 <td><nobr><b><tt id='l2h-124' xml:id='l2h-124' class="method">unreadline</tt></b>(</nobr></td>
206 <td><var>line</var>)</td></tr></table></dt>
207<dd>
208Push <var>line</var> (a string) onto an internal buffer that will be
209checked by future <tt class="method">readline()</tt> calls. Handy for implementing
210a parser with line-at-a-time lookahead. Note that lines that are ``unread''
211with <tt class="method">unreadline</tt> are not subsequently re-cleansed (whitespace
212stripped, or whatever) when read with <tt class="method">readline</tt>. If multiple
213calls are made to <tt class="method">unreadline</tt> before a call to <tt class="method">readline</tt>,
214the lines will be returned most in most recent first order.
215</dl>
216
217<P>
218</dl>
219
220<P>
221
222<DIV CLASS="navigation">
223<div class='online-navigation'>
224<p></p><hr />
225<table align="center" width="100%" cellpadding="0" cellspacing="2">
226<tr>
227<td class='online-navigation'><a rel="prev" title="10.22 distutils.sysconfig "
228 href="module-distutils.sysconfig.html"><img src='../icons/previous.png'
229 border='0' height='32' alt='Previous Page' width='32' /></A></td>
230<td class='online-navigation'><a rel="parent" title="10. API Reference"
231 href="api-reference.html"><img src='../icons/up.png'
232 border='0' height='32' alt='Up One Level' width='32' /></A></td>
233<td class='online-navigation'><a rel="next" title="10.24 distutils.version "
234 href="module-distutils.version.html"><img src='../icons/next.png'
235 border='0' height='32' alt='Next Page' width='32' /></A></td>
236<td align="center" width="100%">Distributing Python Modules</td>
237<td class='online-navigation'><img src='../icons/blank.png'
238 border='0' height='32' alt='' width='32' /></td>
239<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
240 border='0' height='32' alt='Module Index' width='32' /></a></td>
241<td class='online-navigation'><a rel="index" title="Index"
242 href="genindex.html"><img src='../icons/index.png'
243 border='0' height='32' alt='Index' width='32' /></A></td>
244</tr></table>
245<div class='online-navigation'>
246<b class="navlabel">Previous:</b>
247<a class="sectref" rel="prev" href="module-distutils.sysconfig.html">10.22 distutils.sysconfig </A>
248<b class="navlabel">Up:</b>
249<a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A>
250<b class="navlabel">Next:</b>
251<a class="sectref" rel="next" href="module-distutils.version.html">10.24 distutils.version </A>
252</div>
253</div>
254<hr />
255<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
256</DIV>
257<!--End of Navigation Panel-->
258<ADDRESS>
259See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
260</ADDRESS>
261</BODY>
262</HTML>