| |
| .. note:: |
| |
| The :mod:`shlex` module currently does not support Unicode input. |
| |
| The :mod:`shlex` module defines the following functions: |
| |
| |
n | .. function:: split(s[, comments]) |
n | .. function:: split(s[, comments[, posix]]) |
| |
| Split the string *s* using shell-like syntax. If *comments* is :const:`False` |
| (the default), the parsing of comments in the given string will be disabled |
| (setting the :attr:`commenters` member of the :class:`shlex` instance to the |
n | empty string). This function operates in POSIX mode. |
n | empty string). This function operates in POSIX mode by default, but uses |
| non-POSIX mode if the *posix* argument is false. |
| |
n | .. versionadded:: 2.3 |
| |
| .. versionadded:: 2.3 |
| .. versionchanged:: 2.6 |
| Added the *posix* parameter. |
| |
| .. note:: |
| |
| Since the :func:`split` function instantiates a :class:`shlex` instance, passing |
| ``None`` for *s* will read the string to split from standard input. |
| |
| The :mod:`shlex` module defines the following class: |
| |
| |
| .. class:: shlex([instream[, infile[, posix]]]) |
| |
| A :class:`shlex` instance or subclass instance is a lexical analyzer object. |
| The initialization argument, if present, specifies where to read characters |
| :meth:`readline` methods, or a string (strings are accepted since Python 2.3). |
| If no argument is given, input will be taken from ``sys.stdin``. The second |
| optional argument is a filename string, which sets the initial value of the |
| :attr:`infile` member. If the *instream* argument is omitted or equal to |
| ``sys.stdin``, this second argument defaults to "stdin". The *posix* argument |
| was introduced in Python 2.3, and defines the operational mode. When *posix* is |
| not true (default), the :class:`shlex` instance will operate in compatibility |
| mode. When operating in POSIX mode, :class:`shlex` will try to be as close as |
n | possible to the POSIX shell parsing rules. See section :ref:`shlex-objects`. |
n | possible to the POSIX shell parsing rules. |
| |
| |
| .. seealso:: |
| |
| Module :mod:`ConfigParser` |
| Parser for configuration files similar to the Windows :file:`.ini` files. |
| |
| |
| .. _shlex-objects: |
| |
| shlex Objects |
| ------------- |
| |
| A :class:`shlex` instance has the following methods: |
| |
| |
n | .. method:: XXX Class.get_token() |
n | .. method:: shlex.get_token() |
| |
| Return a token. If tokens have been stacked using :meth:`push_token`, pop a |
| token off the stack. Otherwise, read one from the input stream. If reading |
| encounters an immediate end-of-file, :attr:`self.eof` is returned (the empty |
| string (``''``) in non-POSIX mode, and ``None`` in POSIX mode). |
| |
| |
n | .. method:: XXX Class.push_token(str) |
n | .. method:: shlex.push_token(str) |
| |
| Push the argument onto the token stack. |
| |
| |
n | .. method:: XXX Class.read_token() |
n | .. method:: shlex.read_token() |
| |
| Read a raw token. Ignore the pushback stack, and do not interpret source |
| requests. (This is not ordinarily a useful entry point, and is documented here |
| only for the sake of completeness.) |
| |
| |
n | .. method:: XXX Class.sourcehook(filename) |
n | .. method:: shlex.sourcehook(filename) |
| |
| When :class:`shlex` detects a source request (see :attr:`source` below) this |
| method is given the following token as argument, and expected to return a tuple |
| consisting of a filename and an open file-like object. |
| |
| Normally, this method first strips any quotes off the argument. If the result |
| is an absolute pathname, or there was no previous source request in effect, or |
| the previous source was a stream (such as ``sys.stdin``), the result is left |
| addition of file extensions, and other namespace hacks. There is no |
| corresponding 'close' hook, but a shlex instance will call the :meth:`close` |
| method of the sourced input stream when it returns EOF. |
| |
| For more explicit control of source stacking, use the :meth:`push_source` and |
| :meth:`pop_source` methods. |
| |
| |
n | .. method:: XXX Class.push_source(stream[, filename]) |
n | .. method:: shlex.push_source(stream[, filename]) |
| |
| Push an input source stream onto the input stack. If the filename argument is |
| specified it will later be available for use in error messages. This is the |
| same method used internally by the :meth:`sourcehook` method. |
| |
| .. versionadded:: 2.1 |
| |
| |
n | .. method:: XXX Class.pop_source() |
n | .. method:: shlex.pop_source() |
| |
| Pop the last-pushed input source from the input stack. This is the same method |
| used internally when the lexer reaches EOF on a stacked input stream. |
| |
| .. versionadded:: 2.1 |
| |
| |
n | .. method:: XXX Class.error_leader([file[, line]]) |
n | .. method:: shlex.error_leader([file[, line]]) |
| |
| This method generates an error message leader in the format of a Unix C compiler |
| error label; the format is ``'"%s", line %d: '``, where the ``%s`` is replaced |
| with the name of the current source file and the ``%d`` with the current input |
| line number (the optional arguments can be used to override these). |
| |
| This convenience is provided to encourage :mod:`shlex` users to generate error |
| messages in the standard, parseable format understood by Emacs and other Unix |
| tools. |
| |
| Instances of :class:`shlex` subclasses have some public instance variables which |
| either control lexical analysis or can be used for debugging: |
| |
| |
n | .. attribute:: XXX Class.commenters |
n | .. attribute:: shlex.commenters |
| |
| The string of characters that are recognized as comment beginners. All |
| characters from the comment beginner to end of line are ignored. Includes just |
| ``'#'`` by default. |
| |
| |
n | .. attribute:: XXX Class.wordchars |
n | .. attribute:: shlex.wordchars |
| |
| The string of characters that will accumulate into multi-character tokens. By |
| default, includes all ASCII alphanumerics and underscore. |
| |
| |
n | .. attribute:: XXX Class.whitespace |
n | .. attribute:: shlex.whitespace |
| |
| Characters that will be considered whitespace and skipped. Whitespace bounds |
| tokens. By default, includes space, tab, linefeed and carriage-return. |
| |
| |
n | .. attribute:: XXX Class.escape |
n | .. attribute:: shlex.escape |
| |
| Characters that will be considered as escape. This will be only used in POSIX |
n | mode, and includes just ``'\\'`` by default. |
n | mode, and includes just ``'\'`` by default. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. attribute:: XXX Class.quotes |
n | .. attribute:: shlex.quotes |
| |
| Characters that will be considered string quotes. The token accumulates until |
| the same quote is encountered again (thus, different quote types protect each |
| other as in the shell.) By default, includes ASCII single and double quotes. |
| |
| |
n | .. attribute:: XXX Class.escapedquotes |
n | .. attribute:: shlex.escapedquotes |
| |
| Characters in :attr:`quotes` that will interpret escape characters defined in |
| :attr:`escape`. This is only used in POSIX mode, and includes just ``'"'`` by |
| default. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. attribute:: XXX Class.whitespace_split |
n | .. attribute:: shlex.whitespace_split |
| |
| If ``True``, tokens will only be split in whitespaces. This is useful, for |
| example, for parsing command lines with :class:`shlex`, getting tokens in a |
| similar way to shell arguments. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. attribute:: XXX Class.infile |
n | .. attribute:: shlex.infile |
| |
| The name of the current input file, as initially set at class instantiation time |
| or stacked by later source requests. It may be useful to examine this when |
| constructing error messages. |
| |
| |
n | .. attribute:: XXX Class.instream |
n | .. attribute:: shlex.instream |
| |
| The input stream from which this :class:`shlex` instance is reading characters. |
| |
| |
n | .. attribute:: XXX Class.source |
n | .. attribute:: shlex.source |
| |
| This member is ``None`` by default. If you assign a string to it, that string |
| will be recognized as a lexical-level inclusion request similar to the |
| ``source`` keyword in various shells. That is, the immediately following token |
| will opened as a filename and input taken from that stream until EOF, at which |
| point the :meth:`close` method of that stream will be called and the input |
| source will again become the original input stream. Source requests may be |
| stacked any number of levels deep. |
| |
| |
n | .. attribute:: XXX Class.debug |
n | .. attribute:: shlex.debug |
| |
| If this member is numeric and ``1`` or more, a :class:`shlex` instance will |
| print verbose progress output on its behavior. If you need to use this, you can |
| read the module source code to learn the details. |
| |
| |
n | .. attribute:: XXX Class.lineno |
n | .. attribute:: shlex.lineno |
| |
| Source line number (count of newlines seen so far plus one). |
| |
| |
n | .. attribute:: XXX Class.token |
n | .. attribute:: shlex.token |
| |
| The token buffer. It may be useful to examine this when catching exceptions. |
| |
| |
n | .. attribute:: XXX Class.eof |
n | .. attribute:: shlex.eof |
| |
| Token used to determine end of file. This will be set to the empty string |
| (``''``), in non-POSIX mode, and to ``None`` in POSIX mode. |
| |
| .. versionadded:: 2.3 |
| |
| |
| .. _shlex-parsing-rules: |