--------------
-The :class:`shlex` class makes it easy to write lexical analyzers for simple
-syntaxes resembling that of the Unix shell. This will often be useful for
-writing minilanguages, (for example, in run control files for Python
+The :class:`~shlex.shlex` class makes it easy to write lexical analyzers for
+simple syntaxes resembling that of the Unix shell. This will often be useful
+for writing minilanguages, (for example, in run control files for Python
applications) or for parsing quoted strings.
Prior to Python 2.7.3, this module did not support Unicode input.
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` attribute of the :class:`shlex` instance to
- the empty string). This function operates in POSIX mode by default, but uses
- non-POSIX mode if the *posix* argument is false.
+ (setting the :attr:`~shlex.commenters` attribute of the
+ :class:`~shlex.shlex` instance to the empty string). This function operates
+ in POSIX mode by default, but uses non-POSIX mode if the *posix* argument is
+ false.
.. versionadded:: 2.3
.. note::
- Since the :func:`split` function instantiates a :class:`shlex` instance, passing
- ``None`` for *s* will read the string to split from standard input.
+ Since the :func:`split` function instantiates a :class:`~shlex.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
- from. It must be a file-/stream-like object with :meth:`read` and
- :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` attribute. 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
- possible to the POSIX shell parsing rules.
+ A :class:`~shlex.shlex` instance or subclass instance is a lexical analyzer
+ object. The initialization argument, if present, specifies where to read
+ characters from. It must be a file-/stream-like object with
+ :meth:`~io.TextIOBase.read` and :meth:`~io.TextIOBase.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:`~shlex.infile`
+ attribute. 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.shlex` instance will operate in
+ compatibility mode. When operating in POSIX mode, :class:`~shlex.shlex`
+ will try to be as close as possible to the POSIX shell parsing rules.
.. seealso::
shlex Objects
-------------
-A :class:`shlex` instance has the following methods:
+A :class:`~shlex.shlex` instance has the following methods:
.. 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
+ encounters an immediate end-of-file, :attr:`eof` is returned (the empty
string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
.. 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.
+ When :class:`~shlex.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
This hook is exposed so that you can use it to implement directory search paths,
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.
+ corresponding 'close' hook, but a shlex instance will call the
+ :meth:`~io.IOBase.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.
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:
+Instances of :class:`~shlex.shlex` subclasses have some public instance
+variables which either control lexical analysis or can be used for debugging:
.. attribute:: shlex.commenters
.. 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.
+ example, for parsing command lines with :class:`~shlex.shlex`, getting
+ tokens in a similar way to shell arguments.
.. versionadded:: 2.3
.. attribute:: shlex.instream
- The input stream from which this :class:`shlex` instance is reading characters.
+ The input stream from which this :class:`~shlex.shlex` instance is reading
+ characters.
.. attribute:: shlex.source
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.
+ point the :meth:`~io.IOBase.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.
.. attribute:: shlex.debug
- If this attribute 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.
+ If this attribute is numeric and ``1`` or more, a :class:`~shlex.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.
.. attribute:: shlex.lineno
Parsing Rules
-------------
-When operating in non-POSIX mode, :class:`shlex` will try to obey to the
+When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
following rules.
* Quote characters are not recognized within words (``Do"Not"Separate`` is
* Closing quotes separate words (``"Do"Separate`` is parsed as ``"Do"`` and
``Separate``);
-* If :attr:`whitespace_split` is ``False``, any character not declared to be a
- word character, whitespace, or a quote will be returned as a single-character
- token. If it is ``True``, :class:`shlex` will only split words in whitespaces;
+* If :attr:`~shlex.whitespace_split` is ``False``, any character not
+ declared to be a word character, whitespace, or a quote will be returned as
+ a single-character token. If it is ``True``, :class:`~shlex.shlex` will only
+ split words in whitespaces;
* EOF is signaled with an empty string (``''``);
* It's not possible to parse empty strings, even if quoted.
-When operating in POSIX mode, :class:`shlex` will try to obey to the following
-parsing rules.
+When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
+following parsing rules.
* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
parsed as the single word ``DoNotSeparate``);
* Non-quoted escape characters (e.g. ``'\'``) preserve the literal value of the
next character that follows;
-* Enclosing characters in quotes which are not part of :attr:`escapedquotes`
- (e.g. ``"'"``) preserve the literal value of all characters within the quotes;
+* Enclosing characters in quotes which are not part of
+ :attr:`~shlex.escapedquotes` (e.g. ``"'"``) preserve the literal value
+ of all characters within the quotes;
-* Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g.
- ``'"'``) preserves the literal value of all characters within the quotes, with
- the exception of the characters mentioned in :attr:`escape`. The escape
- characters retain its special meaning only when followed by the quote in use, or
- the escape character itself. Otherwise the escape character will be considered a
+* Enclosing characters in quotes which are part of
+ :attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
+ of all characters within the quotes, with the exception of the characters
+ mentioned in :attr:`~shlex.escape`. The escape characters retain its
+ special meaning only when followed by the quote in use, or the escape
+ character itself. Otherwise the escape character will be considered a
normal character.
* EOF is signaled with a :const:`None` value;
projects / python / commitdiff