mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 03:17:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Temporary disabled String Formatting part. Get rid of "conversion".

Browse Source
This commit is contained in:
Victor Zverovich 2012-12-18 07:15:15 -08:00
parent c1ca4a4574
commit a658427bbf
3 changed files with 84 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/conf.py
View File

@ -25,7 +25,7 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.mathjax']
extensions = ['sphinx.ext.ifconfig']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['-templates']
@ -91,7 +91,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme = 'sphinxdoc'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the

2
doc/index.rst
View File

@ -11,7 +11,7 @@ Contents:
.. toctree::
:maxdepth: 2
string
Indices and tables
==================

163
doc/string.rst
View File

@ -1,105 +1,107 @@
.. _string-formatting:
.. ifconfig:: False
String Formatting
-----------------
.. _string-formatting:
The built-in string class provides the ability to do complex variable
substitutions and value formatting via the :func:`format` method described in
:pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows
you to create and customize your own string formatting behaviors using the same
implementation as the built-in :meth:`format` method.
String Formatting
-----------------
The built-in string class provides the ability to do complex variable
substitutions and value formatting via the :func:`format` method described in
:pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows
you to create and customize your own string formatting behaviors using the same
implementation as the built-in :meth:`format` method.
.. class:: Formatter
.. class:: Formatter
The :class:`Formatter` class has the following public methods:
The :class:`Formatter` class has the following public methods:
.. method:: format(format_string, *args, **kwargs)
.. method:: format(format_string, *args, **kwargs)
:meth:`format` is the primary API method. It takes a format string and
an arbitrary set of positional and keyword arguments.
:meth:`format` is just a wrapper that calls :meth:`vformat`.
:meth:`format` is the primary API method. It takes a format string and
an arbitrary set of positional and keyword arguments.
:meth:`format` is just a wrapper that calls :meth:`vformat`.
.. method:: vformat(format_string, args, kwargs)
.. method:: vformat(format_string, args, kwargs)
This function does the actual work of formatting. It is exposed as a
separate function for cases where you want to pass in a predefined
dictionary of arguments, rather than unpacking and repacking the
dictionary as individual arguments using the ``*args`` and ``**kwds``
syntax. :meth:`vformat` does the work of breaking up the format string
into character data and replacement fields. It calls the various
methods described below.
This function does the actual work of formatting. It is exposed as a
separate function for cases where you want to pass in a predefined
dictionary of arguments, rather than unpacking and repacking the
dictionary as individual arguments using the ``*args`` and ``**kwds``
syntax. :meth:`vformat` does the work of breaking up the format string
into character data and replacement fields. It calls the various
methods described below.
In addition, the :class:`Formatter` defines a number of methods that are
intended to be replaced by subclasses:
In addition, the :class:`Formatter` defines a number of methods that are
intended to be replaced by subclasses:
.. method:: parse(format_string)
.. method:: parse(format_string)
Loop over the format_string and return an iterable of tuples
(*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
by :meth:`vformat` to break the string into either literal text, or
replacement fields.
Loop over the format_string and return an iterable of tuples
(*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
by :meth:`vformat` to break the string into either literal text, or
replacement fields.
The values in the tuple conceptually represent a span of literal text
followed by a single replacement field. If there is no literal text
(which can happen if two replacement fields occur consecutively), then
*literal_text* will be a zero-length string. If there is no replacement
field, then the values of *field_name*, *format_spec* and *conversion*
will be ``None``.
The values in the tuple conceptually represent a span of literal text
followed by a single replacement field. If there is no literal text
(which can happen if two replacement fields occur consecutively), then
*literal_text* will be a zero-length string. If there is no replacement
field, then the values of *field_name*, *format_spec* and *conversion*
will be ``None``.
.. method:: get_field(field_name, args, kwargs)
.. method:: get_field(field_name, args, kwargs)
Given *field_name* as returned by :meth:`parse` (see above), convert it to
an object to be formatted. Returns a tuple (obj, used_key). The default
version takes strings of the form defined in :pep:`3101`, such as
"0[name]" or "label.title". *args* and *kwargs* are as passed in to
:meth:`vformat`. The return value *used_key* has the same meaning as the
*key* parameter to :meth:`get_value`.
Given *field_name* as returned by :meth:`parse` (see above), convert it to
an object to be formatted. Returns a tuple (obj, used_key). The default
version takes strings of the form defined in :pep:`3101`, such as
"0[name]" or "label.title". *args* and *kwargs* are as passed in to
:meth:`vformat`. The return value *used_key* has the same meaning as the
*key* parameter to :meth:`get_value`.
.. method:: get_value(key, args, kwargs)
.. method:: get_value(key, args, kwargs)
Retrieve a given field value. The *key* argument will be either an
integer or a string. If it is an integer, it represents the index of the
positional argument in *args*; if it is a string, then it represents a
named argument in *kwargs*.
Retrieve a given field value. The *key* argument will be either an
integer or a string. If it is an integer, it represents the index of the
positional argument in *args*; if it is a string, then it represents a
named argument in *kwargs*.
The *args* parameter is set to the list of positional arguments to
:meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
keyword arguments.
The *args* parameter is set to the list of positional arguments to
:meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
keyword arguments.
For compound field names, these functions are only called for the first
component of the field name; Subsequent components are handled through
normal attribute and indexing operations.
For compound field names, these functions are only called for the first
component of the field name; Subsequent components are handled through
normal attribute and indexing operations.
So for example, the field expression '0.name' would cause
:meth:`get_value` to be called with a *key* argument of 0. The ``name``
attribute will be looked up after :meth:`get_value` returns by calling the
built-in :func:`getattr` function.
So for example, the field expression '0.name' would cause
:meth:`get_value` to be called with a *key* argument of 0. The ``name``
attribute will be looked up after :meth:`get_value` returns by calling the
built-in :func:`getattr` function.
If the index or keyword refers to an item that does not exist, then an
:exc:`IndexError` or :exc:`KeyError` should be raised.
If the index or keyword refers to an item that does not exist, then an
:exc:`IndexError` or :exc:`KeyError` should be raised.
.. method:: check_unused_args(used_args, args, kwargs)
.. method:: check_unused_args(used_args, args, kwargs)
Implement checking for unused arguments if desired. The arguments to this
function is the set of all argument keys that were actually referred to in
the format string (integers for positional arguments, and strings for
named arguments), and a reference to the *args* and *kwargs* that was
passed to vformat. The set of unused args can be calculated from these
parameters. :meth:`check_unused_args` is assumed to raise an exception if
the check fails.
Implement checking for unused arguments if desired. The arguments to this
function is the set of all argument keys that were actually referred to in
the format string (integers for positional arguments, and strings for
named arguments), and a reference to the *args* and *kwargs* that was
passed to vformat. The set of unused args can be calculated from these
parameters. :meth:`check_unused_args` is assumed to raise an exception if
the check fails.
.. method:: format_field(value, format_spec)
.. method:: format_field(value, format_spec)
:meth:`format_field` simply calls the global :func:`format` built-in. The
method is provided so that subclasses can override it.
:meth:`format_field` simply calls the global :func:`format` built-in. The
method is provided so that subclasses can override it.
.. method:: convert_field(value, conversion)
.. method:: convert_field(value, conversion)
Converts the value (returned by :meth:`get_field`) given a conversion type
(as in the tuple returned by the :meth:`parse` method). The default
version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
types.
Converts the value (returned by :meth:`get_field`) given a conversion type
(as in the tuple returned by the :meth:`parse` method). The default
version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
types.
.. _formatstrings:
@ -107,9 +109,8 @@ implementation as the built-in :meth:`format` method.
Format String Syntax
--------------------
The :meth:`str.format` method and the :class:`Formatter` class share the same
syntax for format strings (although in the case of :class:`Formatter`,
subclasses can define their own format string syntax).
The :meth:`Format` function and the :class:`Formatter` class share the same
syntax for format strings.
Format strings contain "replacement fields" surrounded by curly braces ``{}``.
Anything that is not contained in braces is considered literal text, which is
@ -119,20 +120,18 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows:
.. productionlist:: sf
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
replacement_field: "{" [`field_name`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: [`identifier` | `integer`]
attribute_name: `identifier`
element_index: `integer` | `index_string`
index_string: <any source character except "]"> +
conversion: "r" | "s" | "a"
format_spec: <described in the next section>
In less formal terms, the replacement field can start 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
The *field_name* is optionally followed by a *format_spec*, which is preceded
by a colon ``':'``. These specify a non-default format for the replacement value.
See also the :ref:`formatspec` section.