From c4cae32683c0ece3a3fb06c69c11117b205f449d Mon Sep 17 00:00:00 2001 From: Eric Smith Date: Wed, 22 Apr 2009 00:53:01 +0000 Subject: Merged revisions 71788 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71788 | eric.smith | 2009-04-21 20:47:00 -0400 (Tue, 21 Apr 2009) | 1 line Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. ........ --- Doc/ACKS.txt | 1 + Doc/library/string.rst | 24 +++++++++++++++--------- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 80bd4c1..0d796ad 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -157,6 +157,7 @@ docs@python.org), and we'll be glad to correct the problem. * Paul Prescod * Eric S. Raymond * Edward K. Ream + * Terry J. Reedy * Sean Reifschneider * Bernhard Reiter * Armin Rigo diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 29bf160..517e209 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -196,21 +196,26 @@ The grammar for a replacement field is as follows: .. 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" | "a" format_spec: -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 ``':'``. - -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 +by a colon ``':'``. These specify a non-default format for the replacement value. + +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__`. @@ -219,6 +224,7 @@ Some simple format string examples:: "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'. -- cgit v0.12