1
2.. index:: Format Strings
3.. _format-strings:
4
5Format Strings
6--------------
7
8libxo uses format strings to control the rendering of data into the
9various output styles.  Each format string contains a set of zero or
10more field descriptions, which describe independent data fields.  Each
11field description contains a set of modifiers, a content string, and
12zero, one, or two format descriptors.  The modifiers tell libxo what
13the field is and how to treat it, while the format descriptors are
14formatting instructions using printf-style format strings, telling
15libxo how to format the field.  The field description is placed inside
16a set of braces, with a colon (":") after the modifiers and a slash
17("/") before each format descriptors.  Text may be intermixed with
18field descriptions within the format string.
19
20The field description is given as follows::
21
22    '{' [ role | modifier ]* [',' long-names ]* ':' [ content ]
23            [ '/' field-format [ '/' encoding-format ]] '}'
24
25The role describes the function of the field, while the modifiers
26enable optional behaviors.  The contents, field-format, and
27encoding-format are used in varying ways, based on the role.  These
28are described in the following sections.
29
30In the following example, three field descriptors appear.  The first
31is a padding field containing three spaces of padding, the second is a
32label ("In stock"), and the third is a value field ("in-stock").  The
33in-stock field has a "%u" format that will parse the next argument
34passed to the xo_emit function as an unsigned integer::
35
36    xo_emit("{P:   }{Lwc:In stock}{:in-stock/%u}\n", 65);
37
38This single line of code can generate text (" In stock: 65\n"), XML
39("<in-stock>65</in-stock>"), JSON ('"in-stock": 6'), or HTML (too
40lengthy to be listed here).
41
42While roles and modifiers typically use single character for brevity,
43there are alternative names for each which allow more verbose
44formatting strings.  These names must be preceded by a comma, and may
45follow any single-character values::
46
47    xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65);
48