Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/library/shlex.rst

    r2 r391  
    1 
    21:mod:`shlex` --- Simple lexical analysis
    32========================================
    … …  
    1312.. versionadded:: 1.5.2
    1413
    15 The :class:`shlex` class makes it easy to write lexical analyzers for simple
    16 syntaxes resembling that of the Unix shell.  This will often be useful for
    17 writing minilanguages, (for example, in run control files for Python
     14**Source code:** :source:`Lib/shlex.py`
     15
     16--------------
     17
     18
     19The :class:`~shlex.shlex` class makes it easy to write lexical analyzers for
     20simple syntaxes resembling that of the Unix shell.  This will often be useful
     21for writing minilanguages, (for example, in run control files for Python
    1822applications) or for parsing quoted strings.
    1923
    20 .. note::
    21 
    22    The :mod:`shlex` module currently does not support Unicode input.
     24Prior to Python 2.7.3, this module did not support Unicode input.
    2325
    2426The :mod:`shlex` module defines the following functions:
    … …  
    2931   Split the string *s* using shell-like syntax. If *comments* is :const:`False`
    3032   (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
    32    empty string).  This function operates in POSIX mode by default, but uses
    33    non-POSIX mode if the *posix* argument is false.
     33   (setting the :attr:`~shlex.commenters` attribute of the
     34   :class:`~shlex.shlex` instance to the empty string).  This function operates
     35   in POSIX mode by default, but uses non-POSIX mode if the *posix* argument is
     36   false.
    3437
    3538   .. versionadded:: 2.3
    … …  
    4043   .. note::
    4144
    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.
     45      Since the :func:`split` function instantiates a :class:`~shlex.shlex`
     46      instance, passing ``None`` for *s* will read the string to split from
     47      standard input.
    4448
    4549The :mod:`shlex` module defines the following class:
    … …  
    4852.. class:: shlex([instream[, infile[, posix]]])
    4953
    50    A :class:`shlex` instance or subclass instance is a lexical analyzer object.
    51    The initialization argument, if present, specifies where to read characters
    52    from. It must be a file-/stream-like object with :meth:`read` and
    53    :meth:`readline` methods, or a string (strings are accepted since Python 2.3).
    54    If no argument is given, input will be taken from ``sys.stdin``.  The second
    55    optional argument is a filename string, which sets the initial value of the
    56    :attr:`infile` member.  If the *instream* argument is omitted or equal to
    57    ``sys.stdin``, this second argument defaults to "stdin".  The *posix* argument
    58    was introduced in Python 2.3, and defines the operational mode.  When *posix* is
    59    not true (default), the :class:`shlex` instance will operate in compatibility
    60    mode.  When operating in POSIX mode, :class:`shlex` will try to be as close as
    61    possible to the POSIX shell parsing rules.
     54   A :class:`~shlex.shlex` instance or subclass instance is a lexical analyzer
     55   object.  The initialization argument, if present, specifies where to read
     56   characters from. It must be a file-/stream-like object with
     57   :meth:`~io.TextIOBase.read` and :meth:`~io.TextIOBase.readline` methods, or
     58   a string (strings are accepted since Python 2.3).  If no argument is given,
     59   input will be taken from ``sys.stdin``.  The second optional argument is a
     60   filename string, which sets the initial value of the :attr:`~shlex.infile`
     61   attribute.  If the *instream* argument is omitted or equal to ``sys.stdin``,
     62   this second argument defaults to "stdin".  The *posix* argument was
     63   introduced in Python 2.3, and defines the operational mode.  When *posix* is
     64   not true (default), the :class:`~shlex.shlex` instance will operate in
     65   compatibility mode.  When operating in POSIX mode, :class:`~shlex.shlex`
     66   will try to be as close as possible to the POSIX shell parsing rules.
    6267
    6368
    … …  
    7378-------------
    7479
    75 A :class:`shlex` instance has the following methods:
     80A :class:`~shlex.shlex` instance has the following methods:
    7681
    7782
    … …  
    8085   Return a token.  If tokens have been stacked using :meth:`push_token`, pop a
    8186   token off the stack.  Otherwise, read one from the input stream.  If reading
    82    encounters an immediate end-of-file, :attr:`self.eof` is returned (the empty
     87   encounters an immediate end-of-file, :attr:`eof` is returned (the empty
    8388   string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
    8489
    … …  
    98103.. method:: shlex.sourcehook(filename)
    99104
    100    When :class:`shlex` detects a source request (see :attr:`source` below) this
    101    method is given the following token as argument, and expected to return a tuple
    102    consisting of a filename and an open file-like object.
     105   When :class:`~shlex.shlex` detects a source request (see :attr:`source`
     106   below) this method is given the following token as argument, and expected
     107   to return a tuple consisting of a filename and an open file-like object.
    103108
    104109   Normally, this method first strips any quotes off the argument.  If the result
    … …  
    117122   This hook is exposed so that you can use it to implement directory search paths,
    118123   addition of file extensions, and other namespace hacks. There is no
    119    corresponding 'close' hook, but a shlex instance will call the :meth:`close`
    120    method of the sourced input stream when it returns EOF.
     124   corresponding 'close' hook, but a shlex instance will call the
     125   :meth:`~io.IOBase.close` method of the sourced input stream when it returns
     126   EOF.
    121127
    122128   For more explicit control of source stacking, use the :meth:`push_source` and
    … …  
    152158   tools.
    153159
    154 Instances of :class:`shlex` subclasses have some public instance variables which
    155 either control lexical analysis or can be used for debugging:
     160Instances of :class:`~shlex.shlex` subclasses have some public instance
     161variables which either control lexical analysis or can be used for debugging:
    156162
    157163
    … …  
    202208
    203209   If ``True``, tokens will only be split in whitespaces. This is useful, for
    204    example, for parsing command lines with :class:`shlex`, getting tokens in a
    205    similar way to shell arguments.
     210   example, for parsing command lines with :class:`~shlex.shlex`, getting
     211   tokens in a similar way to shell arguments.
    206212
    207213   .. versionadded:: 2.3
    … …  
    217223.. attribute:: shlex.instream
    218224
    219    The input stream from which this :class:`shlex` instance is reading characters.
     225   The input stream from which this :class:`~shlex.shlex` instance is reading
     226   characters.
    220227
    221228
    222229.. attribute:: shlex.source
    223230
    224    This member is ``None`` by default.  If you assign a string to it, that string
    225    will be recognized as a lexical-level inclusion request similar to the
     231   This attribute is ``None`` by default.  If you assign a string to it, that
     232   string will be recognized as a lexical-level inclusion request similar to the
    226233   ``source`` keyword in various shells.  That is, the immediately following token
    227234   will opened as a filename and input taken from that stream until EOF, at which
    228    point the :meth:`close` method of that stream will be called and the input
    229    source will again become the original input stream. Source requests may be
    230    stacked any number of levels deep.
     235   point the :meth:`~io.IOBase.close` method of that stream will be called and
     236   the input source will again become the original input stream.  Source
     237   requests may be stacked any number of levels deep.
    231238
    232239
    233240.. attribute:: shlex.debug
    234241
    235    If this member is numeric and ``1`` or more, a :class:`shlex` instance will
    236    print verbose progress output on its behavior.  If you need to use this, you can
    237    read the module source code to learn the details.
     242   If this attribute is numeric and ``1`` or more, a :class:`~shlex.shlex`
     243   instance will print verbose progress output on its behavior.  If you need
     244   to use this, you can read the module source code to learn the details.
    238245
    239246
    … …  
    261268-------------
    262269
    263 When operating in non-POSIX mode, :class:`shlex` will try to obey to the
     270When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
    264271following rules.
    265272
    … …  
    275282  ``Separate``);
    276283
    277 * If :attr:`whitespace_split` is ``False``, any character not declared to be a
    278   word character, whitespace, or a quote will be returned as a single-character
    279   token. If it is ``True``, :class:`shlex` will only split words in whitespaces;
     284* If :attr:`~shlex.whitespace_split` is ``False``, any character not
     285  declared to be a word character, whitespace, or a quote will be returned as
     286  a single-character token. If it is ``True``, :class:`~shlex.shlex` will only
     287  split words in whitespaces;
    280288
    281289* EOF is signaled with an empty string (``''``);
    … …  
    283291* It's not possible to parse empty strings, even if quoted.
    284292
    285 When operating in POSIX mode, :class:`shlex` will try to obey to the following
    286 parsing rules.
     293When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
     294following parsing rules.
    287295
    288296* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
    … …  
    292300  next character that follows;
    293301
    294 * Enclosing characters in quotes which are not part of :attr:`escapedquotes`
    295   (e.g. ``"'"``) preserve the literal value of all characters within the quotes;
    296 
    297 * Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g.
    298   ``'"'``) preserves the literal value of all characters within the quotes, with
    299   the exception of the characters mentioned in :attr:`escape`. The escape
    300   characters retain its special meaning only when followed by the quote in use, or
    301   the escape character itself. Otherwise the escape character will be considered a
     302* Enclosing characters in quotes which are not part of
     303  :attr:`~shlex.escapedquotes` (e.g. ``"'"``) preserve the literal value
     304  of all characters within the quotes;
     305
     306* Enclosing characters in quotes which are part of
     307  :attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
     308  of all characters within the quotes, with the exception of the characters
     309  mentioned in :attr:`~shlex.escape`.  The escape characters retain its
     310  special meaning only when followed by the quote in use, or the escape
     311  character itself. Otherwise the escape character will be considered a
    302312  normal character.
    303313
Note: See TracChangeset for help on using the changeset viewer.