contrib/libxo/doc/format-strings.rst

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