| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.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="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="shlex-parsing-rules.html" /> |
| 13 | <link rel="prev" href="module-shlex.html" /> |
| 14 | <link rel="parent" href="module-shlex.html" /> |
| 15 | <link rel="next" href="shlex-parsing-rules.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>5.21.1 shlex Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="5.21 shlex " |
| 25 | href="module-shlex.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="5.21 shlex " |
| 28 | href="module-shlex.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="5.21.2 Parsing Rules" |
| 31 | href="shlex-parsing-rules.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="module-shlex.html">5.21 shlex </A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-shlex.html">5.21 shlex </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="shlex-parsing-rules.html">5.21.2 Parsing Rules</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION0072110000000000000000"></A><A NAME="shlex-objects"></A> |
| 56 | <BR> |
| 57 | 5.21.1 shlex Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | A <tt class="class">shlex</tt> instance has the following methods: |
| 62 | |
| 63 | <P> |
| 64 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 65 | <td><nobr><b><tt id='l2h-1482' xml:id='l2h-1482' class="method">get_token</tt></b>(</nobr></td> |
| 66 | <td><var></var>)</td></tr></table></dt> |
| 67 | <dd> |
| 68 | Return a token. If tokens have been stacked using |
| 69 | <tt class="method">push_token()</tt>, pop a token off the stack. Otherwise, read one |
| 70 | from the input stream. If reading encounters an immediate |
| 71 | end-of-file, <tt class="member">self.eof</tt> is returned (the empty string (<code>''</code>) |
| 72 | in non-POSIX mode, and <code>None</code> in POSIX mode). |
| 73 | </dl> |
| 74 | |
| 75 | <P> |
| 76 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 77 | <td><nobr><b><tt id='l2h-1483' xml:id='l2h-1483' class="method">push_token</tt></b>(</nobr></td> |
| 78 | <td><var>str</var>)</td></tr></table></dt> |
| 79 | <dd> |
| 80 | Push the argument onto the token stack. |
| 81 | </dl> |
| 82 | |
| 83 | <P> |
| 84 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 85 | <td><nobr><b><tt id='l2h-1484' xml:id='l2h-1484' class="method">read_token</tt></b>(</nobr></td> |
| 86 | <td><var></var>)</td></tr></table></dt> |
| 87 | <dd> |
| 88 | Read a raw token. Ignore the pushback stack, and do not interpret source |
| 89 | requests. (This is not ordinarily a useful entry point, and is |
| 90 | documented here only for the sake of completeness.) |
| 91 | </dl> |
| 92 | |
| 93 | <P> |
| 94 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 95 | <td><nobr><b><tt id='l2h-1485' xml:id='l2h-1485' class="method">sourcehook</tt></b>(</nobr></td> |
| 96 | <td><var>filename</var>)</td></tr></table></dt> |
| 97 | <dd> |
| 98 | When <tt class="class">shlex</tt> detects a source request (see |
| 99 | <tt class="member">source</tt> below) this method is given the following token as |
| 100 | argument, and expected to return a tuple consisting of a filename and |
| 101 | an open file-like object. |
| 102 | |
| 103 | <P> |
| 104 | Normally, this method first strips any quotes off the argument. If |
| 105 | the result is an absolute pathname, or there was no previous source |
| 106 | request in effect, or the previous source was a stream |
| 107 | (such as <code>sys.stdin</code>), the result is left alone. Otherwise, if the |
| 108 | result is a relative pathname, the directory part of the name of the |
| 109 | file immediately before it on the source inclusion stack is prepended |
| 110 | (this behavior is like the way the C preprocessor handles |
| 111 | <code>#include "file.h"</code>). |
| 112 | |
| 113 | <P> |
| 114 | The result of the manipulations is treated as a filename, and returned |
| 115 | as the first component of the tuple, with |
| 116 | <tt class="function">open()</tt> called on it to yield the second component. (Note: |
| 117 | this is the reverse of the order of arguments in instance initialization!) |
| 118 | |
| 119 | <P> |
| 120 | This hook is exposed so that you can use it to implement directory |
| 121 | search paths, addition of file extensions, and other namespace hacks. |
| 122 | There is no corresponding `close' hook, but a shlex instance will call |
| 123 | the <tt class="method">close()</tt> method of the sourced input stream when it |
| 124 | returns EOF. |
| 125 | |
| 126 | <P> |
| 127 | For more explicit control of source stacking, use the |
| 128 | <tt class="method">push_source()</tt> and <tt class="method">pop_source()</tt> methods. |
| 129 | </dl> |
| 130 | |
| 131 | <P> |
| 132 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 133 | <td><nobr><b><tt id='l2h-1486' xml:id='l2h-1486' class="method">push_source</tt></b>(</nobr></td> |
| 134 | <td><var>stream</var><big>[</big><var>, filename</var><big>]</big><var></var>)</td></tr></table></dt> |
| 135 | <dd> |
| 136 | Push an input source stream onto the input stack. If the filename |
| 137 | argument is specified it will later be available for use in error |
| 138 | messages. This is the same method used internally by the |
| 139 | <tt class="method">sourcehook</tt> method. |
| 140 | |
| 141 | <span class="versionnote">New in version 2.1.</span> |
| 142 | |
| 143 | </dl> |
| 144 | |
| 145 | <P> |
| 146 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 147 | <td><nobr><b><tt id='l2h-1487' xml:id='l2h-1487' class="method">pop_source</tt></b>(</nobr></td> |
| 148 | <td><var></var>)</td></tr></table></dt> |
| 149 | <dd> |
| 150 | Pop the last-pushed input source from the input stack. |
| 151 | This is the same method used internally when the lexer reaches |
| 152 | EOF on a stacked input stream. |
| 153 | |
| 154 | <span class="versionnote">New in version 2.1.</span> |
| 155 | |
| 156 | </dl> |
| 157 | |
| 158 | <P> |
| 159 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 160 | <td><nobr><b><tt id='l2h-1488' xml:id='l2h-1488' class="method">error_leader</tt></b>(</nobr></td> |
| 161 | <td><var></var><big>[</big><var>file</var><big>[</big><var>, line</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 162 | <dd> |
| 163 | This method generates an error message leader in the format of a |
| 164 | <span class="Unix">Unix</span> C compiler error label; the format is <code>'"%s", line %d: '</code>, |
| 165 | where the "<tt class="samp">%s</tt>" is replaced with the name of the current source |
| 166 | file and the "<tt class="samp">%d</tt>" with the current input line number (the |
| 167 | optional arguments can be used to override these). |
| 168 | |
| 169 | <P> |
| 170 | This convenience is provided to encourage <tt class="module">shlex</tt> users to |
| 171 | generate error messages in the standard, parseable format understood |
| 172 | by Emacs and other <span class="Unix">Unix</span> tools. |
| 173 | </dl> |
| 174 | |
| 175 | <P> |
| 176 | Instances of <tt class="class">shlex</tt> subclasses have some public instance |
| 177 | variables which either control lexical analysis or can be used for |
| 178 | debugging: |
| 179 | |
| 180 | <P> |
| 181 | <dl><dt><b><tt id='l2h-1489' xml:id='l2h-1489' class="member">commenters</tt></b></dt> |
| 182 | <dd> |
| 183 | The string of characters that are recognized as comment beginners. |
| 184 | All characters from the comment beginner to end of line are ignored. |
| 185 | Includes just "<tt class="character">#</tt>" by default. |
| 186 | </dl> |
| 187 | |
| 188 | <P> |
| 189 | <dl><dt><b><tt id='l2h-1490' xml:id='l2h-1490' class="member">wordchars</tt></b></dt> |
| 190 | <dd> |
| 191 | The string of characters that will accumulate into multi-character |
| 192 | tokens. By default, includes all ASCII alphanumerics and |
| 193 | underscore. |
| 194 | </dl> |
| 195 | |
| 196 | <P> |
| 197 | <dl><dt><b><tt id='l2h-1491' xml:id='l2h-1491' class="member">whitespace</tt></b></dt> |
| 198 | <dd> |
| 199 | Characters that will be considered whitespace and skipped. Whitespace |
| 200 | bounds tokens. By default, includes space, tab, linefeed and |
| 201 | carriage-return. |
| 202 | </dl> |
| 203 | |
| 204 | <P> |
| 205 | <dl><dt><b><tt id='l2h-1492' xml:id='l2h-1492' class="member">escape</tt></b></dt> |
| 206 | <dd> |
| 207 | Characters that will be considered as escape. This will be only used |
| 208 | in POSIX mode, and includes just "<tt class="character">\</tt>" by default. |
| 209 | |
| 210 | <span class="versionnote">New in version 2.3.</span> |
| 211 | |
| 212 | </dl> |
| 213 | |
| 214 | <P> |
| 215 | <dl><dt><b><tt id='l2h-1493' xml:id='l2h-1493' class="member">quotes</tt></b></dt> |
| 216 | <dd> |
| 217 | Characters that will be considered string quotes. The token |
| 218 | accumulates until the same quote is encountered again (thus, different |
| 219 | quote types protect each other as in the shell.) By default, includes |
| 220 | ASCII single and double quotes. |
| 221 | </dl> |
| 222 | |
| 223 | <P> |
| 224 | <dl><dt><b><tt id='l2h-1494' xml:id='l2h-1494' class="member">escapedquotes</tt></b></dt> |
| 225 | <dd> |
| 226 | Characters in <tt class="member">quotes</tt> that will interpret escape characters |
| 227 | defined in <tt class="member">escape</tt>. This is only used in POSIX mode, and |
| 228 | includes just "<tt class="character">"</tt>" by default. |
| 229 | |
| 230 | <span class="versionnote">New in version 2.3.</span> |
| 231 | |
| 232 | </dl> |
| 233 | |
| 234 | <P> |
| 235 | <dl><dt><b><tt id='l2h-1495' xml:id='l2h-1495' class="member">whitespace_split</tt></b></dt> |
| 236 | <dd> |
| 237 | If <code>True</code>, tokens will only be split in whitespaces. This is useful, for |
| 238 | example, for parsing command lines with <tt class="class">shlex</tt>, getting tokens |
| 239 | in a similar way to shell arguments. |
| 240 | |
| 241 | <span class="versionnote">New in version 2.3.</span> |
| 242 | |
| 243 | </dl> |
| 244 | |
| 245 | <P> |
| 246 | <dl><dt><b><tt id='l2h-1496' xml:id='l2h-1496' class="member">infile</tt></b></dt> |
| 247 | <dd> |
| 248 | The name of the current input file, as initially set at class |
| 249 | instantiation time or stacked by later source requests. It may |
| 250 | be useful to examine this when constructing error messages. |
| 251 | </dl> |
| 252 | |
| 253 | <P> |
| 254 | <dl><dt><b><tt id='l2h-1497' xml:id='l2h-1497' class="member">instream</tt></b></dt> |
| 255 | <dd> |
| 256 | The input stream from which this <tt class="class">shlex</tt> instance is reading |
| 257 | characters. |
| 258 | </dl> |
| 259 | |
| 260 | <P> |
| 261 | <dl><dt><b><tt id='l2h-1498' xml:id='l2h-1498' class="member">source</tt></b></dt> |
| 262 | <dd> |
| 263 | This member is <code>None</code> by default. If you assign a string to it, |
| 264 | that string will be recognized as a lexical-level inclusion request |
| 265 | similar to the "<tt class="samp">source</tt>" keyword in various shells. That is, the |
| 266 | immediately following token will opened as a filename and input taken |
| 267 | from that stream until EOF, at which point the <tt class="method">close()</tt> |
| 268 | method of that stream will be called and the input source will again |
| 269 | become the original input stream. Source requests may be stacked any |
| 270 | number of levels deep. |
| 271 | </dl> |
| 272 | |
| 273 | <P> |
| 274 | <dl><dt><b><tt id='l2h-1499' xml:id='l2h-1499' class="member">debug</tt></b></dt> |
| 275 | <dd> |
| 276 | If this member is numeric and <code>1</code> or more, a <tt class="class">shlex</tt> |
| 277 | instance will print verbose progress output on its behavior. If you |
| 278 | need to use this, you can read the module source code to learn the |
| 279 | details. |
| 280 | </dl> |
| 281 | |
| 282 | <P> |
| 283 | <dl><dt><b><tt id='l2h-1500' xml:id='l2h-1500' class="member">lineno</tt></b></dt> |
| 284 | <dd> |
| 285 | Source line number (count of newlines seen so far plus one). |
| 286 | </dl> |
| 287 | |
| 288 | <P> |
| 289 | <dl><dt><b><tt id='l2h-1501' xml:id='l2h-1501' class="member">token</tt></b></dt> |
| 290 | <dd> |
| 291 | The token buffer. It may be useful to examine this when catching |
| 292 | exceptions. |
| 293 | </dl> |
| 294 | |
| 295 | <P> |
| 296 | <dl><dt><b><tt id='l2h-1502' xml:id='l2h-1502' class="member">eof</tt></b></dt> |
| 297 | <dd> |
| 298 | Token used to determine end of file. This will be set to the empty |
| 299 | string (<code>''</code>), in non-POSIX mode, and to <code>None</code> in |
| 300 | POSIX mode. |
| 301 | |
| 302 | <span class="versionnote">New in version 2.3.</span> |
| 303 | |
| 304 | </dl> |
| 305 | |
| 306 | <P> |
| 307 | |
| 308 | <DIV CLASS="navigation"> |
| 309 | <div class='online-navigation'> |
| 310 | <p></p><hr /> |
| 311 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 312 | <tr> |
| 313 | <td class='online-navigation'><a rel="prev" title="5.21 shlex " |
| 314 | href="module-shlex.html"><img src='../icons/previous.png' |
| 315 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 316 | <td class='online-navigation'><a rel="parent" title="5.21 shlex " |
| 317 | href="module-shlex.html"><img src='../icons/up.png' |
| 318 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 319 | <td class='online-navigation'><a rel="next" title="5.21.2 Parsing Rules" |
| 320 | href="shlex-parsing-rules.html"><img src='../icons/next.png' |
| 321 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 322 | <td align="center" width="100%">Python Library Reference</td> |
| 323 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 324 | href="contents.html"><img src='../icons/contents.png' |
| 325 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 326 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 327 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 328 | <td class='online-navigation'><a rel="index" title="Index" |
| 329 | href="genindex.html"><img src='../icons/index.png' |
| 330 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 331 | </tr></table> |
| 332 | <div class='online-navigation'> |
| 333 | <b class="navlabel">Previous:</b> |
| 334 | <a class="sectref" rel="prev" href="module-shlex.html">5.21 shlex </A> |
| 335 | <b class="navlabel">Up:</b> |
| 336 | <a class="sectref" rel="parent" href="module-shlex.html">5.21 shlex </A> |
| 337 | <b class="navlabel">Next:</b> |
| 338 | <a class="sectref" rel="next" href="shlex-parsing-rules.html">5.21.2 Parsing Rules</A> |
| 339 | </div> |
| 340 | </div> |
| 341 | <hr /> |
| 342 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 343 | </DIV> |
| 344 | <!--End of Navigation Panel--> |
| 345 | <ADDRESS> |
| 346 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 347 | </ADDRESS> |
| 348 | </BODY> |
| 349 | </HTML> |