rest25/library/shlex.rst => rest262/library/shlex.rst
19
20.. note::
21
22   The :mod:`shlex` module currently does not support Unicode input.
23
24The :mod:`shlex` module defines the following functions:
25
26
n27-.. function:: split(s[, comments])
n27+.. function:: split(s[, comments[, posix]])
28
29   Split the string *s* using shell-like syntax. If *comments* is :const:`False`
30   (the default), the parsing of comments in the given string will be disabled
31   (setting the :attr:`commenters` member of the :class:`shlex` instance to the
n32-   empty string).  This function operates in POSIX mode.
n32+   empty string).  This function operates in POSIX mode by default, but uses
33+   non-POSIX mode if the *posix* argument is false.
33
n35+   .. versionadded:: 2.3
36+ 
34-   .. versionadded:: 2.3
37+   .. versionchanged:: 2.6
38+      Added the *posix* parameter.
39+ 
40+   .. note::
41+ 
42+      Since the :func:`split` function instantiates a :class:`shlex` instance, passing
43+      ``None`` for *s* will read the string to split from standard input.
35
36The :mod:`shlex` module defines the following class:
37
38
39.. class:: shlex([instream[, infile[, posix]]])
40
41   A :class:`shlex` instance or subclass instance is a lexical analyzer object.
42   The initialization argument, if present, specifies where to read characters
44   :meth:`readline` methods, or a string (strings are accepted since Python 2.3).
45   If no argument is given, input will be taken from ``sys.stdin``.  The second
46   optional argument is a filename string, which sets the initial value of the
47   :attr:`infile` member.  If the *instream* argument is omitted or equal to
48   ``sys.stdin``, this second argument defaults to "stdin".  The *posix* argument
49   was introduced in Python 2.3, and defines the operational mode.  When *posix* is
50   not true (default), the :class:`shlex` instance will operate in compatibility
51   mode.  When operating in POSIX mode, :class:`shlex` will try to be as close as
n52-   possible to the POSIX shell parsing rules.  See section :ref:`shlex-objects`.
n61+   possible to the POSIX shell parsing rules.
53
54
55.. seealso::
56
57   Module :mod:`ConfigParser`
58      Parser for configuration files similar to the Windows :file:`.ini` files.
59
60
61.. _shlex-objects:
62
63shlex Objects
64-------------
65
66A :class:`shlex` instance has the following methods:
67
68
n69-.. method:: XXX Class.get_token()
n78+.. method:: shlex.get_token()
70
71   Return a token.  If tokens have been stacked using :meth:`push_token`, pop a
72   token off the stack.  Otherwise, read one from the input stream.  If reading
73   encounters an immediate end-of-file, :attr:`self.eof` is returned (the empty
74   string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
75
76
n77-.. method:: XXX Class.push_token(str)
n86+.. method:: shlex.push_token(str)
78
79   Push the argument onto the token stack.
80
81
n82-.. method:: XXX Class.read_token()
n91+.. method:: shlex.read_token()
83
84   Read a raw token.  Ignore the pushback stack, and do not interpret source
85   requests.  (This is not ordinarily a useful entry point, and is documented here
86   only for the sake of completeness.)
87
88
n89-.. method:: XXX Class.sourcehook(filename)
n98+.. method:: shlex.sourcehook(filename)
90
91   When :class:`shlex` detects a source request (see :attr:`source` below) this
92   method is given the following token as argument, and expected to return a tuple
93   consisting of a filename and an open file-like object.
94
95   Normally, this method first strips any quotes off the argument.  If the result
96   is an absolute pathname, or there was no previous source request in effect, or
97   the previous source was a stream (such as ``sys.stdin``), the result is left
109   addition of file extensions, and other namespace hacks. There is no
110   corresponding 'close' hook, but a shlex instance will call the :meth:`close`
111   method of the sourced input stream when it returns EOF.
112
113   For more explicit control of source stacking, use the :meth:`push_source` and
114   :meth:`pop_source` methods.
115
116
n117-.. method:: XXX Class.push_source(stream[, filename])
n126+.. method:: shlex.push_source(stream[, filename])
118
119   Push an input source stream onto the input stack.  If the filename argument is
120   specified it will later be available for use in error messages.  This is the
121   same method used internally by the :meth:`sourcehook` method.
122
123   .. versionadded:: 2.1
124
125
n126-.. method:: XXX Class.pop_source()
n135+.. method:: shlex.pop_source()
127
128   Pop the last-pushed input source from the input stack. This is the same method
129   used internally when the lexer reaches EOF on a stacked input stream.
130
131   .. versionadded:: 2.1
132
133
n134-.. method:: XXX Class.error_leader([file[, line]])
n143+.. method:: shlex.error_leader([file[, line]])
135
136   This method generates an error message leader in the format of a Unix C compiler
137   error label; the format is ``'"%s", line %d: '``, where the ``%s`` is replaced
138   with the name of the current source file and the ``%d`` with the current input
139   line number (the optional arguments can be used to override these).
140
141   This convenience is provided to encourage :mod:`shlex` users to generate error
142   messages in the standard, parseable format understood by Emacs and other Unix
143   tools.
144
145Instances of :class:`shlex` subclasses have some public instance variables which
146either control lexical analysis or can be used for debugging:
147
148
n149-.. attribute:: XXX Class.commenters
n158+.. attribute:: shlex.commenters
150
151   The string of characters that are recognized as comment beginners. All
152   characters from the comment beginner to end of line are ignored. Includes just
153   ``'#'`` by default.
154
155
n156-.. attribute:: XXX Class.wordchars
n165+.. attribute:: shlex.wordchars
157
158   The string of characters that will accumulate into multi-character tokens.  By
159   default, includes all ASCII alphanumerics and underscore.
160
161
n162-.. attribute:: XXX Class.whitespace
n171+.. attribute:: shlex.whitespace
163
164   Characters that will be considered whitespace and skipped.  Whitespace bounds
165   tokens.  By default, includes space, tab, linefeed and carriage-return.
166
167
n168-.. attribute:: XXX Class.escape
n177+.. attribute:: shlex.escape
169
170   Characters that will be considered as escape. This will be only used in POSIX
n171-   mode, and includes just ``'\\'`` by default.
n180+   mode, and includes just ``'\'`` by default.
172
173   .. versionadded:: 2.3
174
175
n176-.. attribute:: XXX Class.quotes
n185+.. attribute:: shlex.quotes
177
178   Characters that will be considered string quotes.  The token accumulates until
179   the same quote is encountered again (thus, different quote types protect each
180   other as in the shell.)  By default, includes ASCII single and double quotes.
181
182
n183-.. attribute:: XXX Class.escapedquotes
n192+.. attribute:: shlex.escapedquotes
184
185   Characters in :attr:`quotes` that will interpret escape characters defined in
186   :attr:`escape`.  This is only used in POSIX mode, and includes just ``'"'`` by
187   default.
188
189   .. versionadded:: 2.3
190
191
n192-.. attribute:: XXX Class.whitespace_split
n201+.. attribute:: shlex.whitespace_split
193
194   If ``True``, tokens will only be split in whitespaces. This is useful, for
195   example, for parsing command lines with :class:`shlex`, getting tokens in a
196   similar way to shell arguments.
197
198   .. versionadded:: 2.3
199
200
n201-.. attribute:: XXX Class.infile
n210+.. attribute:: shlex.infile
202
203   The name of the current input file, as initially set at class instantiation time
204   or stacked by later source requests.  It may be useful to examine this when
205   constructing error messages.
206
207
n208-.. attribute:: XXX Class.instream
n217+.. attribute:: shlex.instream
209
210   The input stream from which this :class:`shlex` instance is reading characters.
211
212
n213-.. attribute:: XXX Class.source
n222+.. attribute:: shlex.source
214
215   This member is ``None`` by default.  If you assign a string to it, that string
216   will be recognized as a lexical-level inclusion request similar to the
217   ``source`` keyword in various shells.  That is, the immediately following token
218   will opened as a filename and input taken from that stream until EOF, at which
219   point the :meth:`close` method of that stream will be called and the input
220   source will again become the original input stream. Source requests may be
221   stacked any number of levels deep.
222
223
n224-.. attribute:: XXX Class.debug
n233+.. attribute:: shlex.debug
225
226   If this member is numeric and ``1`` or more, a :class:`shlex` instance will
227   print verbose progress output on its behavior.  If you need to use this, you can
228   read the module source code to learn the details.
229
230
n231-.. attribute:: XXX Class.lineno
n240+.. attribute:: shlex.lineno
232
233   Source line number (count of newlines seen so far plus one).
234
235
n236-.. attribute:: XXX Class.token
n245+.. attribute:: shlex.token
237
238   The token buffer.  It may be useful to examine this when catching exceptions.
239
240
n241-.. attribute:: XXX Class.eof
n250+.. attribute:: shlex.eof
242
243   Token used to determine end of file. This will be set to the empty string
244   (``''``), in non-POSIX mode, and to ``None`` in POSIX mode.
245
246   .. versionadded:: 2.3
247
248
249.. _shlex-parsing-rules:
274* It's not possible to parse empty strings, even if quoted.
275
276When operating in POSIX mode, :class:`shlex` will try to obey to the following
277parsing rules.
278
279* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
280  parsed as the single word ``DoNotSeparate``);
281
n282-* Non-quoted escape characters (e.g. ``'\\'``) preserve the literal value of the
n291+* Non-quoted escape characters (e.g. ``'\'``) preserve the literal value of the
283  next character that follows;
284
285* Enclosing characters in quotes which are not part of :attr:`escapedquotes`
t286-  (e.g. ``'''``) preserve the literal value of all characters within the quotes;
t295+  (e.g. ``"'"``) preserve the literal value of all characters within the quotes;
287
288* Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g.
289  ``'"'``) preserves the literal value of all characters within the quotes, with
290  the exception of the characters mentioned in :attr:`escape`. The escape
291  characters retain its special meaning only when followed by the quote in use, or
292  the escape character itself. Otherwise the escape character will be considered a
293  normal character.
294
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op