2 .. index:: Field Modifiers
8 Field modifiers are flags which modify the way content emitted for
9 particular output styles:
11 === =============== ===================================================
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 === =============== ===================================================
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.
40 .. index:: Field Modifiers; Argument
41 .. _argument-modifier:
43 The Argument Modifier ({a:})
44 ++++++++++++++++++++++++++++
46 .. index:: Field Modifiers; Argument
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::
53 xo_emit("{La:} {a:}\n", "Label text", "label", "value");
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
67 .. index:: Field Modifiers; Colon
70 The Colon Modifier ({c:})
71 +++++++++++++++++++++++++
73 .. index:: Field Modifiers; Colon
75 The colon modifier appends a single colon to the data value::
78 xo_emit("{Lc:Name}{:name}\n", "phil");
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.
86 .. index:: Field Modifiers; Display
89 The Display Modifier ({d:})
90 +++++++++++++++++++++++++++
92 .. index:: Field Modifiers; Display
94 The display modifier indicated the field should only be generated for
95 the display output styles, TEXT and HTML::
98 xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
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.
107 .. index:: Field Modifiers; Encoding
108 .. _encoding-modifier:
110 The Encoding Modifier ({e:})
111 ++++++++++++++++++++++++++++
113 .. index:: Field Modifiers; Encoding
115 The display modifier indicated the field should only be generated for
116 the display output styles, TEXT and HTML::
119 xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
123 <name>phil</name><id>1</id>
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.
128 .. index:: Field Modifiers; Gettext
129 .. _gettext-modifier:
131 The Gettext Modifier ({g:})
132 +++++++++++++++++++++++++++
134 .. index:: Field Modifiers; Gettext
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
143 In the following example, the strings "State" and "full" are passed
144 to gettext() to find locale-based translated strings::
146 xo_emit("{Lgwc:State}{g:state}\n", "full");
148 See :ref:`gettext-role`, :ref:`plural-modifier`, and
149 :ref:`i18n` for additional details.
151 .. index:: Field Modifiers; Humanize
152 .. _humanize-modifier:
154 The Humanize Modifier ({h:})
155 ++++++++++++++++++++++++++++
157 .. index:: Field Modifiers; Humanize
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"
164 "hn" can be used as an alias for "humanize".
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.
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
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);
186 21, 57 K, 96M, 44M, 1.2G
188 In the HTML style, the original numeric value is rendered in the
189 "data-number" attribute on the <div> element::
191 <div class="data" data-tag="errors"
192 data-number="100663296">96M</div>
194 .. index:: Field Modifiers; Key
197 The Key Modifier ({k:})
198 +++++++++++++++++++++++
200 .. index:: Field Modifiers; Key
202 The key modifier is used to indicate that a particular field helps
203 uniquely identify an instance of list data::
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");
213 xo_close_list("user");
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.
221 .. index:: Field Modifiers; Leaf-List
224 The Leaf-List Modifier ({l:})
225 +++++++++++++++++++++++++++++
227 .. index:: Field Modifiers; Leaf-List
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::
234 for (i = 0; i < num_users; i++) {
235 xo_emit("Member {l:user}\n", user[i].u_name);
241 "user": [ "phil", "pallavi" ]
243 The name of the field must match the name of the leaf list.
245 .. index:: Field Modifiers; No-Quotes
246 .. _no-quotes-modifier:
248 The No-Quotes Modifier ({n:})
249 +++++++++++++++++++++++++++++
251 .. index:: Field Modifiers; No-Quotes
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::
260 const char *bool = is_true ? "true" : "false";
261 xo_emit("{n:fancy/%s}", bool);
265 .. index:: Field Modifiers; Plural
268 The Plural Modifier ({p:})
269 ++++++++++++++++++++++++++
271 .. index:: Field Modifiers; Plural
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::
279 xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
281 The plural modifier is meant to work with the gettext modifier ({g:})
282 but can work independently. See :ref:`gettext-modifier`.
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.
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.
293 .. index:: Field Modifiers; Quotes
296 The Quotes Modifier ({q:})
297 ++++++++++++++++++++++++++
299 .. index:: Field Modifiers; Quotes
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::
308 xo_emit("{q:time/%d}", 2014);
312 The heuristic is based on the format; if the format uses any of the
313 following conversion specifiers, then no quotes are used::
315 d i o u x X D O U e E f F g G a A c C p
317 .. index:: Field Modifiers; Trim
320 The Trim Modifier ({t:})
321 ++++++++++++++++++++++++
323 .. index:: Field Modifiers; Trim
325 The trim modifier removes any leading or trailing whitespace from
329 xo_emit("{t:description}", " some input ");
331 "description": "some input"
333 .. index:: Field Modifiers; White Space
334 .. _white-space-modifier:
336 The White Space Modifier ({w:})
337 +++++++++++++++++++++++++++++++
339 .. index:: Field Modifiers; White Space
341 The white space modifier appends a single space to the data value::
344 xo_emit("{Lw:Name}{:name}\n", "phil");
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.
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.