[Python-checkins] r71788 - in python/trunk/Doc: ACKS.txt library/string.rst

[eric.smith]

Author: eric.smith
Date: Wed Apr 22 02:47:00 2009
New Revision: 71788

Log:
Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy.

Modified:
   python/trunk/Doc/ACKS.txt
   python/trunk/Doc/library/string.rst

Modified: python/trunk/Doc/ACKS.txt
==============================================================================
--- python/trunk/Doc/ACKS.txt	(original)
+++ python/trunk/Doc/ACKS.txt	Wed Apr 22 02:47:00 2009
@@ -156,6 +156,7 @@
    * Paul Prescod
    * Eric S. Raymond
    * Edward K. Ream
+   * Terry J. Reedy
    * Sean Reifschneider
    * Bernhard Reiter
    * Armin Rigo

Modified: python/trunk/Doc/library/string.rst
==============================================================================
--- python/trunk/Doc/library/string.rst	(original)
+++ python/trunk/Doc/library/string.rst	Wed Apr 22 02:47:00 2009
@@ -221,21 +221,26 @@
 
    .. productionlist:: sf
       replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
-      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
+      field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
+      arg_name: (`identifier` | `integer`)?
       attribute_name: `identifier`
       element_index: `integer`
       conversion: "r" | "s"
       format_spec: <described in the next section>
 
-In less formal terms, the replacement field starts with a *field_name*, which
-can either be a number (for a positional argument), or an identifier (for
-keyword arguments).  Following this is an optional *conversion* field, which is
+In less formal terms, the replacement field starts with a *field_name* that specifies
+the object whose value is to be formatted and inserted
+into the output instead of the replacement field.
+The *field_name* is optionally followed by a  *conversion* field, which is
 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
-by a colon ``':'``.
+by a colon ``':'``.  These specify a non-default format for the replacement value.
 
-The *field_name* itself begins with either a number or a keyword.  If it's a
-number, it refers to a positional argument, and if it's a keyword it refers to a
-named keyword argument.  This can be followed by any number of index or
+The *field_name* itself begins with an *arg_name* that is either either a number or a
+keyword.  If it's a number, it refers to a positional argument, and if it's a keyword,
+it refers to a named keyword argument.  If the numerical arg_names in a format string
+are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
+and the numbers 0, 1, 2, ... will be automatically inserted in that order.
+The *arg_name* can be followed by any number of index or
 attribute expressions. An expression of the form ``'.name'`` selects the named
 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
 does an index lookup using :func:`__getitem__`.
@@ -244,6 +249,7 @@
 
    "First, thou shalt count to {0}" # References first positional argument
    "Bring me a {}"                  # Implicitly references the first positional argument
+   "From {} to {}"                  # Same as "From {0] to {1}"
    "My quest is {name}"             # References keyword argument 'name'
    "Weight in tons {0.weight}"      # 'weight' attribute of first positional arg
    "Units destroyed: {players[0]}"  # First element of keyword argument 'players'.