983afe3373
- Add xo_format_is_numeric() with improved logic to decide if format
strings are numeric, so json output quotes them
- Convert docs to sphinx/rst
- update tests
Includes fix for PR 221676:
27d3021cc3 (diff-5a0d468963477f7daedb8308c219dd80)
PR: 221676
MFC after: 5 days
48 lines
2.0 KiB
ReStructuredText
48 lines
2.0 KiB
ReStructuredText
|
|
.. index:: Format Strings
|
|
.. _format-strings:
|
|
|
|
Format Strings
|
|
--------------
|
|
|
|
libxo uses format strings to control the rendering of data into the
|
|
various output styles. Each format string contains a set of zero or
|
|
more field descriptions, which describe independent data fields. Each
|
|
field description contains a set of modifiers, a content string, and
|
|
zero, one, or two format descriptors. The modifiers tell libxo what
|
|
the field is and how to treat it, while the format descriptors are
|
|
formatting instructions using printf-style format strings, telling
|
|
libxo how to format the field. The field description is placed inside
|
|
a set of braces, with a colon (":") after the modifiers and a slash
|
|
("/") before each format descriptors. Text may be intermixed with
|
|
field descriptions within the format string.
|
|
|
|
The field description is given as follows::
|
|
|
|
'{' [ role | modifier ]* [',' long-names ]* ':' [ content ]
|
|
[ '/' field-format [ '/' encoding-format ]] '}'
|
|
|
|
The role describes the function of the field, while the modifiers
|
|
enable optional behaviors. The contents, field-format, and
|
|
encoding-format are used in varying ways, based on the role. These
|
|
are described in the following sections.
|
|
|
|
In the following example, three field descriptors appear. The first
|
|
is a padding field containing three spaces of padding, the second is a
|
|
label ("In stock"), and the third is a value field ("in-stock"). The
|
|
in-stock field has a "%u" format that will parse the next argument
|
|
passed to the xo_emit function as an unsigned integer::
|
|
|
|
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65);
|
|
|
|
This single line of code can generate text (" In stock: 65\n"), XML
|
|
("<in-stock>65</in-stock>"), JSON ('"in-stock": 6'), or HTML (too
|
|
lengthy to be listed here).
|
|
|
|
While roles and modifiers typically use single character for brevity,
|
|
there are alternative names for each which allow more verbose
|
|
formatting strings. These names must be preceded by a comma, and may
|
|
follow any single-character values::
|
|
|
|
xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65);
|