contrib/libxo/doc/field-modifiers.rst

   1
   2 .. index:: Field Modifiers
   3 .. _field-modifiers:
   4
   5 Field Modifiers
   6 ~~~~~~~~~~~~~~~
   7
   8 Field modifiers are flags which modify the way content emitted for
   9 particular output styles:
  10
  11 === =============== ===================================================
  12  M   Name            Description
  13 === =============== ===================================================
  14  a   argument        The content appears as a 'const char \*' argument
  15  c   colon           A colon (":") is appended after the label
  16  d   display         Only emit field for display styles (text/HTML)
  17  e   encoding        Only emit for encoding styles (XML/JSON)
  18  g   gettext         Call gettext on field's render content
  19  h   humanize (hn)   Format large numbers in human-readable style
  20 \    hn-space        Humanize: Place space between numeric and unit
  21 \    hn-decimal      Humanize: Add a decimal digit, if number < 10
  22 \    hn-1000         Humanize: Use 1000 as divisor instead of 1024
  23  k   key             Field is a key, suitable for XPath predicates
  24  l   leaf-list       Field is a leaf-list
  25  n   no-quotes       Do not quote the field when using JSON style
  26  p   plural          Gettext: Use comma-separated plural form
  27  q   quotes          Quote the field when using JSON style
  28  t   trim            Trim leading and trailing whitespace
  29  w   white           A blank (" ") is appended after the label
  30 === =============== ===================================================
  31
  32 Roles and modifiers can also use more verbose names, when preceded by
  33 a comma.  For example, the modifier string "Lwc" (or "L,white,colon")
  34 means the field has a label role (text that describes the next field)
  35 and should be followed by a colon ('c') and a space ('w').  The
  36 modifier string "Vkq" (or ":key,quote") means the field has a value
  37 role (the default role), that it is a key for the current instance,
  38 and that the value should be quoted when encoded for JSON.
  39
  40 .. index:: Field Modifiers; Argument
  41 .. _argument-modifier:
  42
  43 The Argument Modifier ({a:})
  44 ++++++++++++++++++++++++++++
  45
  46 .. index:: Field Modifiers; Argument
  47
  48 The argument modifier indicates that the content of the field
  49 descriptor will be placed as a UTF-8 string (const char \*) argument
  50 within the xo_emit parameters::
  51
  52     EXAMPLE:
  53         xo_emit("{La:} {a:}\n", "Label text", "label", "value");
  54     TEXT:
  55         Label text value
  56     JSON:
  57         "label": "value"
  58     XML:
  59         <label>value</label>
  60
  61 The argument modifier allows field names for value fields to be passed
  62 on the stack, avoiding the need to build a field descriptor using
  63 snprintf.  For many field roles, the argument modifier is not needed,
  64 since those roles have specific mechanisms for arguments, such as
  65 "{C:fg-%s}".
  66
  67 .. index:: Field Modifiers; Colon
  68 .. _colon-modifier:
  69
  70 The Colon Modifier ({c:})
  71 +++++++++++++++++++++++++
  72
  73 .. index:: Field Modifiers; Colon
  74
  75 The colon modifier appends a single colon to the data value::
  76
  77     EXAMPLE:
  78         xo_emit("{Lc:Name}{:name}\n", "phil");
  79     TEXT:
  80         Name:phil
  81
  82 The colon modifier is only used for the TEXT and HTML output
  83 styles. It is commonly combined with the space modifier ('{w:}').
  84 It is purely a convenience feature.
  85
  86 .. index:: Field Modifiers; Display
  87 .. _display-modifier:
  88
  89 The Display Modifier ({d:})
  90 +++++++++++++++++++++++++++
  91
  92 .. index:: Field Modifiers; Display
  93
  94 The display modifier indicated the field should only be generated for
  95 the display output styles, TEXT and HTML::
  96
  97     EXAMPLE:
  98         xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
  99     TEXT:
 100         Name: phil 1
 101     XML:
 102         <id>1</id>
 103
 104 The display modifier is the opposite of the encoding modifier, and
 105 they are often used to give to distinct views of the underlying data.
 106
 107 .. index:: Field Modifiers; Encoding
 108 .. _encoding-modifier:
 109
 110 The Encoding Modifier ({e:})
 111 ++++++++++++++++++++++++++++
 112
 113 .. index:: Field Modifiers; Encoding
 114
 115 The display modifier indicated the field should only be generated for
 116 the display output styles, TEXT and HTML::
 117
 118     EXAMPLE:
 119         xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
 120     TEXT:
 121         Name: phil
 122     XML:
 123         <name>phil</name><id>1</id>
 124
 125 The encoding modifier is the opposite of the display modifier, and
 126 they are often used to give to distinct views of the underlying data.
 127
 128 .. index:: Field Modifiers; Gettext
 129 .. _gettext-modifier:
 130
 131 The Gettext Modifier ({g:})
 132 +++++++++++++++++++++++++++
 133
 134 .. index:: Field Modifiers; Gettext
 135 .. index:: gettext
 136
 137 The gettext modifier is used to translate individual fields using the
 138 gettext domain (typically set using the "`{G:}`" role) and current
 139 language settings.  Once libxo renders the field value, it is passed
 140 to gettext(3), where it is used as a key to find the native language
 141 translation.
 142
 143 In the following example, the strings "State" and "full" are passed
 144 to gettext() to find locale-based translated strings::
 145
 146     xo_emit("{Lgwc:State}{g:state}\n", "full");
 147
 148 See :ref:`gettext-role`, :ref:`plural-modifier`, and
 149 :ref:`i18n` for additional details.
 150
 151 .. index:: Field Modifiers; Humanize
 152 .. _humanize-modifier:
 153
 154 The Humanize Modifier ({h:})
 155 ++++++++++++++++++++++++++++
 156
 157 .. index:: Field Modifiers; Humanize
 158
 159 The humanize modifier is used to render large numbers as in a
 160 human-readable format.  While numbers like "44470272" are completely
 161 readable to computers and savants, humans will generally find "44M"
 162 more meaningful.
 163
 164 "hn" can be used as an alias for "humanize".
 165
 166 The humanize modifier only affects display styles (TEXT and HMTL).
 167 The "`no-humanize`" option (See :ref:`options`) will block
 168 the function of the humanize modifier.
 169
 170 There are a number of modifiers that affect details of humanization.
 171 These are only available in as full names, not single characters.  The
 172 "`hn-space`" modifier places a space between the number and any
 173 multiplier symbol, such as "M" or "K" (ex: "44 K").  The
 174 "`hn-decimal`" modifier will add a decimal point and a single tenths
 175 digit when the number is less than 10 (ex: "4.4K").  The "`hn-1000`"
 176 modifier will use 1000 as divisor instead of 1024, following the
 177 JEDEC-standard instead of the more natural binary powers-of-two
 178 tradition::
 179
 180     EXAMPLE:
 181         xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
 182             "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
 183             "{h,hn-decimal:remaining/%u}\n",
 184             input, output, errors, capacity, remaining);
 185     TEXT:
 186         21, 57 K, 96M, 44M, 1.2G
 187
 188 In the HTML style, the original numeric value is rendered in the
 189 "data-number" attribute on the <div> element::
 190
 191     <div class="data" data-tag="errors"
 192          data-number="100663296">96M</div>
 193
 194 .. index:: Field Modifiers; Key
 195 .. _key-modifier:
 196
 197 The Key Modifier ({k:})
 198 +++++++++++++++++++++++
 199
 200 .. index:: Field Modifiers; Key
 201
 202 The key modifier is used to indicate that a particular field helps
 203 uniquely identify an instance of list data::
 204
 205     EXAMPLE:
 206         xo_open_list("user");
 207         for (i = 0; i < num_users; i++) {
 208             xo_open_instance("user");
 209             xo_emit("User {k:name} has {:count} tickets\n",
 210                user[i].u_name, user[i].u_tickets);
 211             xo_close_instance("user");
 212         }
 213         xo_close_list("user");
 214
 215 .. index:: XOF_XPATH
 216
 217 Currently the key modifier is only used when generating XPath value
 218 for the HTML output style when XOF_XPATH is set, but other uses are
 219 likely in the near future.
 220
 221 .. index:: Field Modifiers; Leaf-List
 222 .. _leaf-list:
 223
 224 The Leaf-List Modifier ({l:})
 225 +++++++++++++++++++++++++++++
 226
 227 .. index:: Field Modifiers; Leaf-List
 228
 229 The leaf-list modifier is used to distinguish lists where each
 230 instance consists of only a single value.  In XML, these are
 231 rendered as single elements, where JSON renders them as arrays::
 232
 233     EXAMPLE:
 234         for (i = 0; i < num_users; i++) {
 235             xo_emit("Member {l:user}\n", user[i].u_name);
 236         }
 237     XML:
 238         <user>phil</user>
 239         <user>pallavi</user>
 240     JSON:
 241         "user": [ "phil", "pallavi" ]
 242
 243 The name of the field must match the name of the leaf list.
 244
 245 .. index:: Field Modifiers; No-Quotes
 246 .. _no-quotes-modifier:
 247
 248 The No-Quotes Modifier ({n:})
 249 +++++++++++++++++++++++++++++
 250
 251 .. index:: Field Modifiers; No-Quotes
 252
 253 The no-quotes modifier (and its twin, the 'quotes' modifier) affect
 254 the quoting of values in the JSON output style.  JSON uses quotes for
 255 string value, but no quotes for numeric, boolean, and null data.
 256 xo_emit applies a simple heuristic to determine whether quotes are
 257 needed, but often this needs to be controlled by the caller::
 258
 259     EXAMPLE:
 260         const char *bool = is_true ? "true" : "false";
 261         xo_emit("{n:fancy/%s}", bool);
 262     JSON:
 263         "fancy": true
 264
 265 .. index:: Field Modifiers; Plural
 266 .. _plural-modifier:
 267
 268 The Plural Modifier ({p:})
 269 ++++++++++++++++++++++++++
 270
 271 .. index:: Field Modifiers; Plural
 272 .. index:: gettext
 273
 274 The plural modifier selects the appropriate plural form of an
 275 expression based on the most recent number emitted and the current
 276 language settings.  The contents of the field should be the singular
 277 and plural English values, separated by a comma::
 278
 279     xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
 280
 281 The plural modifier is meant to work with the gettext modifier ({g:})
 282 but can work independently.  See :ref:`gettext-modifier`.
 283
 284 When used without the gettext modifier or when the message does not
 285 appear in the message catalog, the first token is chosen when the last
 286 numeric value is equal to 1; otherwise the second value is used,
 287 mimicking the simple pluralization rules of English.
 288
 289 When used with the gettext modifier, the ngettext(3) function is
 290 called to handle the heavy lifting, using the message catalog to
 291 convert the singular and plural forms into the native language.
 292
 293 .. index:: Field Modifiers; Quotes
 294 .. _quotes-modifier:
 295
 296 The Quotes Modifier ({q:})
 297 ++++++++++++++++++++++++++
 298
 299 .. index:: Field Modifiers; Quotes
 300
 301 The quotes modifier (and its twin, the 'no-quotes' modifier) affect
 302 the quoting of values in the JSON output style.  JSON uses quotes for
 303 string value, but no quotes for numeric, boolean, and null data.
 304 xo_emit applies a simple heuristic to determine whether quotes are
 305 needed, but often this needs to be controlled by the caller::
 306
 307     EXAMPLE:
 308         xo_emit("{q:time/%d}", 2014);
 309     JSON:
 310         "year": "2014"
 311
 312 The heuristic is based on the format; if the format uses any of the
 313 following conversion specifiers, then no quotes are used::
 314
 315     d i o u x X D O U e E f F g G a A c C p
 316
 317 .. index:: Field Modifiers; Trim
 318 .. _trim-modifier:
 319
 320 The Trim Modifier ({t:})
 321 ++++++++++++++++++++++++
 322
 323 .. index:: Field Modifiers; Trim
 324
 325 The trim modifier removes any leading or trailing whitespace from
 326 the value::
 327
 328     EXAMPLE:
 329         xo_emit("{t:description}", "   some  input   ");
 330     JSON:
 331         "description": "some input"
 332
 333 .. index:: Field Modifiers; White Space
 334 .. _white-space-modifier:
 335
 336 The White Space Modifier ({w:})
 337 +++++++++++++++++++++++++++++++
 338
 339 .. index:: Field Modifiers; White Space
 340
 341 The white space modifier appends a single space to the data value::
 342
 343     EXAMPLE:
 344         xo_emit("{Lw:Name}{:name}\n", "phil");
 345     TEXT:
 346         Name phil
 347
 348 The white space modifier is only used for the TEXT and HTML output
 349 styles. It is commonly combined with the colon modifier ('{c:}').
 350 It is purely a convenience feature.
 351
 352 Note that the sense of the 'w' modifier is reversed for the units role
 353 ({Uw:}); a blank is added before the contents, rather than after it.