mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 21:16:56 +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 # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # 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. # Add any paths that contain templates here, relative to this directory.
templates_path = ['-templates'] templates_path = ['-templates']
@ -91,7 +91,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # further. For a list of options available for each theme, see the

2
doc/index.rst
View File

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