518c518
< content: "December 2015";
---
> content: "April 2016";
22012c22012
< <td class="header right">December 30, 2015</td>
---
> <td class="header right">April 15, 2016</td>
22133c22133
< <a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
---
> <a href="#the-argument-modifier-a">The Argument Modifier ({a:})</a>
22137c22137
< <a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
---
> <a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
22141c22141
< <a href="#e-modifier">The Encoding Modifier ({e:})</a>
---
> <a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
22145c22145
< <a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
---
> <a href="#e-modifier">The Encoding Modifier ({e:})</a>
22149c22149
< <a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
---
> <a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
22153c22153
< <a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
---
> <a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
22157c22157
< <a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
---
> <a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
22161c22161
< <a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
---
> <a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
22165c22165
< <a href="#plural-modifier">The Plural Modifier ({p:})</a>
---
> <a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
22169c22169
< <a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
---
> <a href="#plural-modifier">The Plural Modifier ({p:})</a>
22172a22173,22180
> <a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_2_12">2.2.2.12���</div>
> <a href="#the-trim-modifier-t">The Trim Modifier ({t:})</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_2_13">2.2.2.13���</div>
22210a22219,22222
> <a href="#retain">Retaining Parsed Format Information</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_12">2.2.12���</div>
22217,22220d22228
< <a href="#command-line-arguments">Command-line Arguments</a>
< </li>
< <li class="tocline1">
< <div class="section-number" id="toc_doc_section_2_4">2.4���</div>
22223c22231
< <div class="section-number" id="toc_doc_section_2_4_1">2.4.1���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_1">2.3.1���</div>
22227c22235
< <div class="section-number" id="toc_doc_section_2_4_2">2.4.2���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_2">2.3.2���</div>
22231c22239
< <div class="section-number" id="toc_doc_section_2_4_3">2.4.3���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_3">2.3.3���</div>
22235c22243
< <div class="section-number" id="toc_doc_section_2_4_4">2.4.4���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_4">2.3.4���</div>
22241,22242c22249,22250
< <div class="section-number" id="toc_doc_section_2_5">2.5���</div>
< <a href="#handles">Handles</a>
---
> <div class="section-number" id="toc_doc_section_2_4">2.4���</div>
> <a href="#command-line-arguments">Command-line Arguments</a>
22244,22247d22251
< <li class="tocline1">
< <div class="section-number" id="toc_doc_section_2_6">2.6���</div>
< <a href="#utf-8">UTF-8</a>
< </li>
22255c22259
< <a href="#handles-2">Handles</a><ul class="toc">
---
> <a href="#handles">Handles</a><ul class="toc">
22309c22313
< <a href="#xo_attr">Attributes (xo_attr)</a>
---
> <a href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a>
22313c22317
< <a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
---
> <a href="#xo_attr">Attributes (xo_attr)</a>
22316a22321,22324
> <a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_3_2_4">3.2.4���</div>
22854,22857c22862,22863
< <li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a></li>
< <li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.4</a></li>
< <li><a href="#handles" title="Handles">Section�2.5</a></li>
< <li><a href="#utf-8" title="UTF-8">Section�2.6</a></li>
---
> <li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.3</a></li>
> <li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a></li>
22995c23001,23002
< <li><a href="#example" title="Example">Section�2.2.11</a></li>
---
> <li><a href="#retain" title="Retaining Parsed Format Information">Section�2.2.11</a></li>
> <li><a href="#example" title="Example">Section�2.2.12</a></li>
23358a23366,23370
> <td>a</td>
> <td>argument</td>
> <td>The content appears as a 'const char *' argument</td>
> </tr>
> <tr>
23438,23448c23450,23462
< <li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.1</a></li>
< <li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.2</a></li>
< <li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.3</a></li>
< <li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.4</a></li>
< <li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.5</a></li>
< <li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.6</a></li>
< <li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.7</a></li>
< <li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.8</a></li>
< <li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.9</a></li>
< <li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.10</a></li>
< <li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.11</a></li>
---
> <li><a href="#the-argument-modifier-a" title="The Argument Modifier ({a:})">Section�2.2.2.1</a></li>
> <li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.2</a></li>
> <li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.3</a></li>
> <li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.4</a></li>
> <li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.5</a></li>
> <li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.6</a></li>
> <li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.7</a></li>
> <li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.8</a></li>
> <li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.9</a></li>
> <li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.10</a></li>
> <li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.11</a></li>
> <li><a href="#the-trim-modifier-t" title="The Trim Modifier ({t:})">Section�2.2.2.12</a></li>
> <li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.13</a></li>
23454c23468
< <a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
---
> <a id="the-argument-modifier-a" href="#the-argument-modifier-a">The Argument Modifier ({a:})</a>
23456c23470
< <p id="doc_section_2_2_2_1_p_1">The colon modifier appends a single colon to the data value:</p>
---
> <p id="doc_section_2_2_2_1_p_1">The argument modifier indicates that the content of the field descriptor will be placed as a UTF-8 string (const char *) argument within the xo_emit parameters.</p>
23459c23473
< xo_emit("{Lc:Name}{:name}\n", "phil");
---
> xo_emit("{La:} {a:}\n", "Label text", "label", "value");
23461,23462c23475,23480
< Name:phil
< </pre> <p id="doc_section_2_2_2_1_p_3">The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier ('{w:}'). It is purely a convenience feature.</p>
---
> Label text value
> JSON:
> "label": "value"
> XML:
> <label>value</label>
> </pre> <p id="doc_section_2_2_2_1_p_3">The argument modifier allows field names for value fields to be passed on the stack, avoiding the need to build a field descriptor using snprintf. For many field roles, the argument modifier is not needed, since those roles have specific mechanisms for arguments, such as "{C:fg‑%s}".</p>
23468c23486
< <a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a>
---
> <a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
23470c23488
< <p id="doc_section_2_2_2_2_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
---
> <p id="doc_section_2_2_2_2_p_1">The colon modifier appends a single colon to the data value:</p>
23472a23491,23504
> xo_emit("{Lc:Name}{:name}\n", "phil");
> TEXT:
> Name:phil
> </pre> <p id="doc_section_2_2_2_2_p_3">The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier ('{w:}'). It is purely a convenience feature.</p>
> </div>
> <div class="content">
> <h4 id="doc_section_2_2_2_3">
> <div class="self-section-number">
> <a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
> <a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a>
> </h4>
> <p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
> <div id="doc_figure_u.50"></div> <pre>
> EXAMPLE:
23478c23510
< </pre> <p id="doc_section_2_2_2_2_p_3">The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data.</p>
---
> </pre> <p id="doc_section_2_2_2_3_p_3">The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data.</p>
23481c23513
< <h4 id="doc_section_2_2_2_3">
---
> <h4 id="doc_section_2_2_2_4">
23483c23515
< <a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
---
> <a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
23486,23487c23518,23519
< <p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
< <div id="doc_figure_u.50"></div> <pre>
---
> <p id="doc_section_2_2_2_4_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
> <div id="doc_figure_u.51"></div> <pre>
23494c23526
< </pre> <p id="doc_section_2_2_2_3_p_3">The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data.</p>
---
> </pre> <p id="doc_section_2_2_2_4_p_3">The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data.</p>
23497c23529
< <h4 id="doc_section_2_2_2_4">
---
> <h4 id="doc_section_2_2_2_5">
23499c23531
< <a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
---
> <a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
23502,23504c23534,23536
< <p id="doc_section_2_2_2_4_p_1">The gettext modifier is used to translate individual fields using the gettext domain (typically set using the "{G:}" role) and current language settings. Once libxo renders the field value, it is passed to gettext(3), where it is used as a key to find the native language translation.</p>
< <p id="doc_section_2_2_2_4_p_2">In the following example, the strings "State" and "full" are passed to gettext() to find locale-based translated strings.</p>
< <div id="doc_figure_u.51"></div> <pre>
---
> <p id="doc_section_2_2_2_5_p_1">The gettext modifier is used to translate individual fields using the gettext domain (typically set using the "{G:}" role) and current language settings. Once libxo renders the field value, it is passed to gettext(3), where it is used as a key to find the native language translation.</p>
> <p id="doc_section_2_2_2_5_p_2">In the following example, the strings "State" and "full" are passed to gettext() to find locale-based translated strings.</p>
> <div id="doc_figure_u.52"></div> <pre>
23506c23538
< </pre> <p id="doc_section_2_2_2_4_p_4">See <a href="#gettext-role" title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.9</a>, and <a href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a> for additional details.</p>
---
> </pre> <p id="doc_section_2_2_2_5_p_4">See <a href="#gettext-role" title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.10</a>, and <a href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a> for additional details.</p>
23509c23541
< <h4 id="doc_section_2_2_2_5">
---
> <h4 id="doc_section_2_2_2_6">
23511c23543
< <a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
---
> <a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
23514,23518c23546,23550
< <p id="doc_section_2_2_2_5_p_1">The humanize modifier is used to render large numbers as in a human-readable format. While numbers like "44470272" are completely readable to computers and savants, humans will generally find "44M" more meaningful.</p>
< <p id="doc_section_2_2_2_5_p_2">"hn" can be used as an alias for "humanize".</p>
< <p id="doc_section_2_2_2_5_p_3">The humanize modifier only affects display styles (TEXT and HMTL). The "no‑humanize" option (See <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the function of the humanize modifier.</p>
< <p id="doc_section_2_2_2_5_p_4">There are a number of modifiers that affect details of humanization. These are only available in as full names, not single characters. The "hn‑space" modifier places a space between the number and any multiplier symbol, such as "M" or "K" (ex: "44 K"). The "hn‑decimal" modifier will add a decimal point and a single tenths digit when the number is less than 10 (ex: "4.4K"). The "hn‑1000" modifier will use 1000 as divisor instead of 1024, following the JEDEC-standard instead of the more natural binary powers-of-two tradition.</p>
< <div id="doc_figure_u.52"></div> <pre>
---
> <p id="doc_section_2_2_2_6_p_1">The humanize modifier is used to render large numbers as in a human-readable format. While numbers like "44470272" are completely readable to computers and savants, humans will generally find "44M" more meaningful.</p>
> <p id="doc_section_2_2_2_6_p_2">"hn" can be used as an alias for "humanize".</p>
> <p id="doc_section_2_2_2_6_p_3">The humanize modifier only affects display styles (TEXT and HMTL). The "no‑humanize" option (See <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the function of the humanize modifier.</p>
> <p id="doc_section_2_2_2_6_p_4">There are a number of modifiers that affect details of humanization. These are only available in as full names, not single characters. The "hn‑space" modifier places a space between the number and any multiplier symbol, such as "M" or "K" (ex: "44 K"). The "hn‑decimal" modifier will add a decimal point and a single tenths digit when the number is less than 10 (ex: "4.4K"). The "hn‑1000" modifier will use 1000 as divisor instead of 1024, following the JEDEC-standard instead of the more natural binary powers-of-two tradition.</p>
> <div id="doc_figure_u.53"></div> <pre>
23526,23527c23558,23559
< </pre> <p id="doc_section_2_2_2_5_p_6">In the HTML style, the original numeric value is rendered in the "data‑number" attribute on the <div> element:</p>
< <div id="doc_figure_u.53"></div> <pre>
---
> </pre> <p id="doc_section_2_2_2_6_p_6">In the HTML style, the original numeric value is rendered in the "data‑number" attribute on the <div> element:</p>
> <div id="doc_figure_u.54"></div> <pre>
23532c23564
< <h4 id="doc_section_2_2_2_6">
---
> <h4 id="doc_section_2_2_2_7">
23534c23566
< <a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
---
> <a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
23537,23538c23569,23570
< <p id="doc_section_2_2_2_6_p_1">The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data.</p>
< <div id="doc_figure_u.54"></div> <pre>
---
> <p id="doc_section_2_2_2_7_p_1">The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data.</p>
> <div id="doc_figure_u.55"></div> <pre>
23548c23580
< </pre> <p id="doc_section_2_2_2_6_p_3">Currently the key modifier is only used when generating XPath value for the HTML output style when XOF_XPATH is set, but other uses are likely in the near future.</p>
---
> </pre> <p id="doc_section_2_2_2_7_p_3">Currently the key modifier is only used when generating XPath value for the HTML output style when XOF_XPATH is set, but other uses are likely in the near future.</p>
23551c23583
< <h4 id="doc_section_2_2_2_7">
---
> <h4 id="doc_section_2_2_2_8">
23553c23585
< <a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
---
> <a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
23556,23557c23588,23589
< <p id="doc_section_2_2_2_7_p_1">The leaf-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays.</p>
< <div id="doc_figure_u.55"></div> <pre>
---
> <p id="doc_section_2_2_2_8_p_1">The leaf-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays.</p>
> <div id="doc_figure_u.56"></div> <pre>
23567c23599
< </pre> <p id="doc_section_2_2_2_7_p_3">The name of the field must match the name of the leaf list.</p>
---
> </pre> <p id="doc_section_2_2_2_8_p_3">The name of the field must match the name of the leaf list.</p>
23570c23602
< <h4 id="doc_section_2_2_2_8">
---
> <h4 id="doc_section_2_2_2_9">
23572c23604
< <a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
---
> <a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
23575,23576c23607,23608
< <p id="doc_section_2_2_2_8_p_1">The no-quotes modifier (and its twin, the 'quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
< <div id="doc_figure_u.56"></div> <pre>
---
> <p id="doc_section_2_2_2_9_p_1">The no-quotes modifier (and its twin, the 'quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
> <div id="doc_figure_u.57"></div> <pre>
23584c23616
< <h4 id="doc_section_2_2_2_9">
---
> <h4 id="doc_section_2_2_2_10">
23586c23618
< <a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
---
> <a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
23589,23590c23621,23622
< <p id="doc_section_2_2_2_9_p_1">The plural modifier selects the appropriate plural form of an expression based on the most recent number emitted and the current language settings. The contents of the field should be the singular and plural English values, separated by a comma:</p>
< <div id="doc_figure_u.57"></div> <pre>
---
> <p id="doc_section_2_2_2_10_p_1">The plural modifier selects the appropriate plural form of an expression based on the most recent number emitted and the current language settings. The contents of the field should be the singular and plural English values, separated by a comma:</p>
> <div id="doc_figure_u.58"></div> <pre>
23592,23594c23624,23626
< </pre> <p id="doc_section_2_2_2_9_p_3">The plural modifier is meant to work with the gettext modifier ({g:}) but can work independently. See <a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.4</a>.</p>
< <p id="doc_section_2_2_2_9_p_4">When used without the gettext modifier or when the message does not appear in the message catalog, the first token is chosen when the last numeric value is equal to 1; otherwise the second value is used, mimicking the simple pluralization rules of English.</p>
< <p id="doc_section_2_2_2_9_p_5">When used with the gettext modifier, the ngettext(3) function is called to handle the heavy lifting, using the message catalog to convert the singular and plural forms into the native language.</p>
---
> </pre> <p id="doc_section_2_2_2_10_p_3">The plural modifier is meant to work with the gettext modifier ({g:}) but can work independently. See <a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.5</a>.</p>
> <p id="doc_section_2_2_2_10_p_4">When used without the gettext modifier or when the message does not appear in the message catalog, the first token is chosen when the last numeric value is equal to 1; otherwise the second value is used, mimicking the simple pluralization rules of English.</p>
> <p id="doc_section_2_2_2_10_p_5">When used with the gettext modifier, the ngettext(3) function is called to handle the heavy lifting, using the message catalog to convert the singular and plural forms into the native language.</p>
23597c23629
< <h4 id="doc_section_2_2_2_10">
---
> <h4 id="doc_section_2_2_2_11">
23599c23631
< <a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
---
> <a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
23602,23603c23634,23635
< <p id="doc_section_2_2_2_10_p_1">The quotes modifier (and its twin, the 'no‑quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
< <div id="doc_figure_u.58"></div> <pre>
---
> <p id="doc_section_2_2_2_11_p_1">The quotes modifier (and its twin, the 'no‑quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
> <div id="doc_figure_u.59"></div> <pre>
23607a23640,23642
> </pre> <p id="doc_section_2_2_2_11_p_3">The heuristic is based on the format; if the format uses any of the following conversion specifiers, then no quotes are used:</p>
> <div id="doc_figure_u.60"></div> <pre>
> d i o u x X D O U e E f F g G a A c C p
23610c23645
< <h4 id="doc_section_2_2_2_11">
---
> <h4 id="doc_section_2_2_2_12">
23612c23647,23660
< <a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
---
> <a href="#doc_section_2_2_2_12">2.2.2.12</a>�</div>
> <a id="the-trim-modifier-t" href="#the-trim-modifier-t">The Trim Modifier ({t:})</a>
> </h4>
> <p id="doc_section_2_2_2_12_p_1">The trim modifier removes any leading or trailing whitespace from the value.</p>
> <div id="doc_figure_u.61"></div> <pre>
> EXAMPLE:
> xo_emit("{t:description}", " some input ");
> JSON:
> "description": "some input"
> </pre> </div>
> <div class="content">
> <h4 id="doc_section_2_2_2_13">
> <div class="self-section-number">
> <a href="#doc_section_2_2_2_13">2.2.2.13</a>�</div>
23615,23616c23663,23664
< <p id="doc_section_2_2_2_11_p_1">The white space modifier appends a single space to the data value:</p>
< <div id="doc_figure_u.59"></div> <pre>
---
> <p id="doc_section_2_2_2_13_p_1">The white space modifier appends a single space to the data value:</p>
> <div id="doc_figure_u.62"></div> <pre>
23621,23622c23669,23670
< </pre> <p id="doc_section_2_2_2_11_p_3">The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier ('{c:}'). It is purely a convenience feature.</p>
< <p id="doc_section_2_2_2_11_p_4">Note that the sense of the 'w' modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it.</p>
---
> </pre> <p id="doc_section_2_2_2_13_p_3">The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier ('{c:}'). It is purely a convenience feature.</p>
> <p id="doc_section_2_2_2_13_p_4">Note that the sense of the 'w' modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it.</p>
23635c23683
< <div id="doc_figure_u.60"></div> <pre>
---
> <div id="doc_figure_u.63"></div> <pre>
23832,23833c23880,23915
< <p id="doc_section_2_2_4_p_2">For example, a function is passed a locale-base name, a hat size, and a time value. The hat size is formatted in a UTF-8 (ASCII) string, and the time value is formatted into a wchar_t string.</p>
< <div id="doc_figure_u.61"></div> <pre>
---
> <p id="doc_section_2_2_4_p_2">libxo will convert these arguments as needed to either UTF-8 (for XML, JSON, and HTML styles) or locale-based strings for display in text style.</p>
> <div id="doc_figure_u.64"></div> <pre>
> xo_emit("Alll strings are utf-8 content {:tag/%ls}",
> L"except for wide strings");
> </pre> <p id="doc_section_2_2_4_p_4">"%S" is equivalent to "%ls".</p>
> <div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
> <thead><tr>
> <th class="left">Format</th>
> <th class="left">Argument Type</th>
> <th class="left">Argument Contents</th>
> </tr></thead>
> <tbody>
> <tr>
> <td>%s</td>
> <td>const char *</td>
> <td>UTF-8 string</td>
> </tr>
> <tr>
> <td>%S</td>
> <td>const char *</td>
> <td>UTF-8 string (alias for '%s')</td>
> </tr>
> <tr>
> <td>%ls</td>
> <td>const wchar_t *</td>
> <td>Wide character UNICODE string</td>
> </tr>
> <tr>
> <td>%hs</td>
> <td>const char *</td>
> <td>locale-based string</td>
> </tr>
> </tbody>
> </table></div>
> <p id="doc_section_2_2_4_p_5">For example, a function is passed a locale-base name, a hat size, and a time value. The hat size is formatted in a UTF-8 (ASCII) string, and the time value is formatted into a wchar_t string.</p>
> <div id="doc_figure_u.65"></div> <pre>
23852,23855c23934,23937
< </pre> <p id="doc_section_2_2_4_p_4">It is important to note that xo_emit will perform the conversion required to make appropriate output. Text style output uses the current locale (as described above), while XML, JSON, and HTML use UTF-8.</p>
< <p id="doc_section_2_2_4_p_5">UTF-8 and locale-encoded strings can use multiple bytes to encode one column of data. The traditional "precision'" (aka "max‑width") value for "%s" printf formatting becomes overloaded since it specifies both the number of bytes that can be safely referenced and the maximum number of columns to emit. xo_emit uses the precision as the former, and adds a third value for specifying the maximum number of columns.</p>
< <p id="doc_section_2_2_4_p_6">In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the location given by 'name' are in used in filling those columns.</p>
< <div id="doc_figure_u.62"></div> <pre>
---
> </pre> <p id="doc_section_2_2_4_p_7">It is important to note that xo_emit will perform the conversion required to make appropriate output. Text style output uses the current locale (as described above), while XML, JSON, and HTML use UTF-8.</p>
> <p id="doc_section_2_2_4_p_8">UTF-8 and locale-encoded strings can use multiple bytes to encode one column of data. The traditional "precision'" (aka "max‑width") value for "%s" printf formatting becomes overloaded since it specifies both the number of bytes that can be safely referenced and the maximum number of columns to emit. xo_emit uses the precision as the former, and adds a third value for specifying the maximum number of columns.</p>
> <p id="doc_section_2_2_4_p_9">In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the location given by 'name' are in used in filling those columns.</p>
> <div id="doc_figure_u.66"></div> <pre>
23865c23947
< <div id="doc_figure_u.63"></div> <pre>
---
> <div id="doc_figure_u.67"></div> <pre>
23886c23968
< <div id="doc_figure_u.64"></div> <pre>
---
> <div id="doc_figure_u.68"></div> <pre>
23933c24015
< <div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
23989a24072,24128
> <a id="retain" href="#retain">Retaining Parsed Format Information</a>
> </h3>
> <p id="doc_section_2_2_11_p_1">libxo can retain the parsed internal information related to the given format string, allowing subsequent xo_emit calls, the retained information is used, avoiding repetitive parsing of the format string.</p>
> <div id="doc_figure_u.69"></div> <pre>
> SYNTAX:
> int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
> EXAMPLE:
> xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
> some, thing, fancy);
> </pre> <p id="doc_section_2_2_11_p_3">To retain parsed format information, use the XOEF_RETAIN flag to the xo_emit_f() function. A complete set of xo_emit_f functions exist to match all the xo_emit function signatures (with handles, varadic argument, and printf-like flags):</p>
> <div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
> <thead><tr>
> <th class="left">Function</th>
> <th class="left">Flags Equivalent</th>
> </tr></thead>
> <tbody>
> <tr>
> <td>xo_emit_hv</td>
> <td>xo_emit_hvf</td>
> </tr>
> <tr>
> <td>xo_emit_h</td>
> <td>xo_emit_hf</td>
> </tr>
> <tr>
> <td>xo_emit</td>
> <td>xo_emit_f</td>
> </tr>
> <tr>
> <td>xo_emit_hvp</td>
> <td>xo_emit_hvfp</td>
> </tr>
> <tr>
> <td>xo_emit_hp</td>
> <td>xo_emit_hfp</td>
> </tr>
> <tr>
> <td>xo_emit_p</td>
> <td>xo_emit_fp</td>
> </tr>
> </tbody>
> </table></div>
> <p id="doc_section_2_2_11_p_4">The format string must be immutable across multiple calls to xo_emit_f(), since the library retains the string. Typically this is done by using static constant strings, such as string literals. If the string is not immutable, the XOEF_RETAIN flag must not be used.</p>
> <p id="doc_section_2_2_11_p_5">The functions xo_retain_clear() and xo_retain_clear_all() release internal information on either a single format string or all format strings, respectively. Neither is required, but the library will retain this information until it is cleared or the process exits.</p>
> <div id="doc_figure_u.70"></div> <pre>
> const char *fmt = "{:name} {:count/%d}\n";
> for (i = 0; i < 1000; i++) {
> xo_open_instance("item");
> xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
> }
> xo_retain_clear(fmt);
> </pre> <p id="doc_section_2_2_11_p_7">The retained information is kept as thread-specific data.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_2_12">
> <div class="self-section-number">
> <a href="#doc_section_2_2_12">2.2.12</a>�</div>
23992,23993c24131,24132
< <p id="doc_section_2_2_11_p_1">In this example, the value for the number of items in stock is emitted:</p>
< <div id="doc_figure_u.65"></div> <pre>
---
> <p id="doc_section_2_2_12_p_1">In this example, the value for the number of items in stock is emitted:</p>
> <div id="doc_figure_u.71"></div> <pre>
23996,23997c24135,24136
< </pre> <p id="doc_section_2_2_11_p_3">This call will generate the following output:</p>
< <div id="doc_figure_u.66"></div> <pre>
---
> </pre> <p id="doc_section_2_2_12_p_3">This call will generate the following output:</p>
> <div id="doc_figure_u.72"></div> <pre>
24012,24013c24151,24152
< </pre> <p id="doc_section_2_2_11_p_5">Clearly HTML wins the verbosity award, and this output does not include XOF_XPATH or XOF_INFO data, which would expand the penultimate line to:</p>
< <div id="doc_figure_u.67"></div> <pre>
---
> </pre> <p id="doc_section_2_2_12_p_5">Clearly HTML wins the verbosity award, and this output does not include XOF_XPATH or XOF_INFO data, which would expand the penultimate line to:</p>
> <div id="doc_figure_u.73"></div> <pre>
24023a24163,24292
> <a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a>
> </h2>
> <p id="doc_section_2_3_p_1">For XML and JSON, individual fields appear inside hierarchies which provide context and meaning to the fields. Unfortunately, these encoding have a basic disconnect between how lists is similar objects are represented.</p>
> <p id="doc_section_2_3_p_2">XML encodes lists as set of sequential elements:</p>
> <div id="doc_figure_u.74"></div> <pre>
> <user>phil</user>
> <user>pallavi</user>
> <user>sjg</user>
> </pre> <p id="doc_section_2_3_p_4">JSON encodes lists using a single name and square brackets:</p>
> <div id="doc_figure_u.75"></div> <pre>
> "user": [ "phil", "pallavi", "sjg" ]
> </pre> <p id="doc_section_2_3_p_6">This means libxo needs three distinct indications of hierarchy: one for containers of hierarchy appear only once for any specific parent, one for lists, and one for each item in a list.</p>
> <p id="doc_section_2_3_p_7">Section Contents: </p>
> <ul>
> <li><a href="#containers" title="Containers">Section�2.3.1</a></li>
> <li><a href="#lists-and-instances" title="Lists and Instances">Section�2.3.2</a></li>
> <li><a href="#dtrt-mode" title="DTRT Mode">Section�2.3.3</a></li>
> <li><a href="#markers" title="Markers">Section�2.3.4</a></li>
> </ul>
> <div class="content">
> <h3 id="doc_section_2_3_1">
> <div class="self-section-number">
> <a href="#doc_section_2_3_1">2.3.1</a>�</div>
> <a id="containers" href="#containers">Containers</a>
> </h3>
> <p id="doc_section_2_3_1_p_1">A "container" is an element of a hierarchy that appears only once under any specific parent. The container has no value, but serves to contain other nodes.</p>
> <p id="doc_section_2_3_1_p_2">To open a container, call xo_open_container() or xo_open_container_h(). The former uses the default handle and the latter accepts a specific handle.</p>
> <div id="doc_figure_u.76"></div> <pre>
> int xo_open_container_h (xo_handle_t *xop, const char *name);
> int xo_open_container (const char *name);
> </pre> <p id="doc_section_2_3_1_p_4">To close a level, use the xo_close_container() or xo_close_container_h() functions:</p>
> <div id="doc_figure_u.77"></div> <pre>
> int xo_close_container_h (xo_handle_t *xop, const char *name);
> int xo_close_container (const char *name);
> </pre> <p id="doc_section_2_3_1_p_6">Each open call must have a matching close call. If the XOF_WARN flag is set and the name given does not match the name of the currently open container, a warning will be generated.</p>
> <div id="doc_figure_u.78"></div> <pre>
> Example:
>
> xo_open_container("top");
> xo_open_container("system");
> xo_emit("{:host-name/%s%s%s", hostname,
> domainname ? "." : "", domainname ?: "");
> xo_close_container("system");
> xo_close_container("top");
>
> Sample Output:
> Text:
> my-host.example.org
> XML:
> <top>
> <system>
> <host-name>my-host.example.org</host-name>
> </system>
> </top>
> JSON:
> "top" : {
> "system" : {
> "host-name": "my-host.example.org"
> }
> }
> HTML:
> <div class="data"
> data-tag="host-name">my-host.example.org</div>
> </pre> </div>
> <div class="content">
> <h3 id="doc_section_2_3_2">
> <div class="self-section-number">
> <a href="#doc_section_2_3_2">2.3.2</a>�</div>
> <a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a>
> </h3>
> <p id="doc_section_2_3_2_p_1">A list is set of one or more instances that appear under the same parent. The instances contain details about a specific object. One can think of instances as objects or records. A call is needed to open and close the list, while a distinct call is needed to open and close each instance of the list:</p>
> <div id="doc_figure_u.79"></div> <pre>
> xo_open_list("item");
>
> for (ip = list; ip->i_title; ip++) {
> xo_open_instance("item");
> xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
> xo_close_instance("item");
> }
>
> xo_close_list("item");
> </pre> <p id="doc_section_2_3_2_p_3">Getting the list and instance calls correct is critical to the proper generation of XML and JSON data.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_3_3">
> <div class="self-section-number">
> <a href="#doc_section_2_3_3">2.3.3</a>�</div>
> <a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a>
> </h3>
> <p id="doc_section_2_3_3_p_1">Some users may find tracking the names of open containers, lists, and instances inconvenient. libxo offers a "Do The Right Thing" mode, where libxo will track the names of open containers, lists, and instances so the close function can be called without a name. To enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output.</p>
> <div id="doc_figure_u.80"></div> <pre>
> xo_set_flags(NULL, XOF_DTRT);
> </pre> <p id="doc_section_2_3_3_p_3">Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance:</p>
> <div id="doc_figure_u.81"></div> <pre>
> xo_open_container("top");
> ...
> xo_close_container_d();
> </pre> <p id="doc_section_2_3_3_p_5">This also works for lists and instances:</p>
> <div id="doc_figure_u.82"></div> <pre>
> xo_open_list("item");
> for (...) {
> xo_open_instance("item");
> xo_emit(...);
> xo_close_instance_d();
> }
> xo_close_list_d();
> </pre> <p id="doc_section_2_3_3_p_7">Note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_3_4">
> <div class="self-section-number">
> <a href="#doc_section_2_3_4">2.3.4</a>�</div>
> <a id="markers" href="#markers">Markers</a>
> </h3>
> <p id="doc_section_2_3_4_p_1">Markers are used to protect and restore the state of open constructs. While a marker is open, no other open constructs can be closed. When a marker is closed, all constructs open since the marker was opened will be closed.</p>
> <p id="doc_section_2_3_4_p_2">Markers use names which are not user-visible, allowing the caller to choose appropriate internal names.</p>
> <p id="doc_section_2_3_4_p_3">In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish‑guts" is used to ensure that any constructs opened by the function are closed properly.</p>
> <div id="doc_figure_u.83"></div> <pre>
> for (i = 0; fish[i]; i++) {
> xo_open_instance("fish");
> xo_open_marker("fish-guts");
> dump_fish_details(i);
> xo_close_marker("fish-guts");
> }
> </pre> </div>
> </div>
> <div class="content">
> <h2 id="doc_section_2_4">
> <div class="self-section-number">
> <a href="#doc_section_2_4">2.4</a>�</div>
24026,24027c24295,24296
< <p id="doc_section_2_3_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p>
< <p id="doc_section_2_3_p_2"> </p>
---
> <p id="doc_section_2_4_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p>
> <p id="doc_section_2_4_p_2"> </p>
24033,24034c24302,24304
< <p id="doc_section_2_3_p_3">Options is a comma-separated list of tokens that correspond to output styles, flags, or features:</p>
< <div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <p id="doc_section_2_4_p_3">Programs using libxo are expecting to call the xo_parse_args function to parse these arguments. See <a href="#xo_parse_args" title="Parsing Command-line Arguments (xo_parse_args)">Section�3.4.1</a> for details.</p>
> <p id="doc_section_2_4_p_4">Options is a comma-separated list of tokens that correspond to output styles, flags, or features:</p>
> <div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24084a24355,24358
> <td>no-retain</td>
> <td>Prevent retaining formatting information</td>
> </tr>
> <tr>
24096a24371,24374
> <td>retain</td>
> <td>Force retaining formatting information</td>
> </tr>
> <tr>
24126c24404
< <p id="doc_section_2_3_p_4">The brief options are detailed in <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>.</p>
---
> <p id="doc_section_2_4_p_5">The brief options are detailed in <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>.</p>
24128,24213d24405
< <div class="content">
< <h2 id="doc_section_2_4">
< <div class="self-section-number">
< <a href="#doc_section_2_4">2.4</a>�</div>
< <a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a>
< </h2>
< <p id="doc_section_2_4_p_1">For XML and JSON, individual fields appear inside hierarchies which provide context and meaning to the fields. Unfortunately, these encoding have a basic disconnect between how lists is similar objects are represented.</p>
< <p id="doc_section_2_4_p_2">XML encodes lists as set of sequential elements:</p>
< <div id="doc_figure_u.68"></div> <pre>
< <user>phil</user>
< <user>pallavi</user>
< <user>sjg</user>
< </pre> <p id="doc_section_2_4_p_4">JSON encodes lists using a single name and square brackets:</p>
< <div id="doc_figure_u.69"></div> <pre>
< "user": [ "phil", "pallavi", "sjg" ]
< </pre> <p id="doc_section_2_4_p_6">This means libxo needs three distinct indications of hierarchy: one for containers of hierarchy appear only once for any specific parent, one for lists, and one for each item in a list.</p>
< <p id="doc_section_2_4_p_7">Section Contents: </p>
< <ul>
< <li><a href="#containers" title="Containers">Section�2.4.1</a></li>
< <li><a href="#lists-and-instances" title="Lists and Instances">Section�2.4.2</a></li>
< <li><a href="#dtrt-mode" title="DTRT Mode">Section�2.4.3</a></li>
< <li><a href="#markers" title="Markers">Section�2.4.4</a></li>
< </ul>
< <div class="content">
< <h3 id="doc_section_2_4_1">
< <div class="self-section-number">
< <a href="#doc_section_2_4_1">2.4.1</a>�</div>
< <a id="containers" href="#containers">Containers</a>
< </h3>
< <p id="doc_section_2_4_1_p_1">A "container" is an element of a hierarchy that appears only once under any specific parent. The container has no value, but serves to contain other nodes.</p>
< <p id="doc_section_2_4_1_p_2">To open a container, call xo_open_container() or xo_open_container_h(). The former uses the default handle and the latter accepts a specific handle.</p>
< <div id="doc_figure_u.70"></div> <pre>
< int xo_open_container_h (xo_handle_t *xop, const char *name);
< int xo_open_container (const char *name);
< </pre> <p id="doc_section_2_4_1_p_4">To close a level, use the xo_close_container() or xo_close_container_h() functions:</p>
< <div id="doc_figure_u.71"></div> <pre>
< int xo_close_container_h (xo_handle_t *xop, const char *name);
< int xo_close_container (const char *name);
< </pre> <p id="doc_section_2_4_1_p_6">Each open call must have a matching close call. If the XOF_WARN flag is set and the name given does not match the name of the currently open container, a warning will be generated.</p>
< <div id="doc_figure_u.72"></div> <pre>
< Example:
<
< xo_open_container("top");
< xo_open_container("system");
< xo_emit("{:host-name/%s%s%s", hostname,
< domainname ? "." : "", domainname ?: "");
< xo_close_container("system");
< xo_close_container("top");
<
< Sample Output:
< Text:
< my-host.example.org
< XML:
< <top>
< <system>
< <host-name>my-host.example.org</host-name>
< </system>
< </top>
< JSON:
< "top" : {
< "system" : {
< "host-name": "my-host.example.org"
< }
< }
< HTML:
< <div class="data"
< data-tag="host-name">my-host.example.org</div>
< </pre> </div>
< <div class="content">
< <h3 id="doc_section_2_4_2">
< <div class="self-section-number">
< <a href="#doc_section_2_4_2">2.4.2</a>�</div>
< <a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a>
< </h3>
< <p id="doc_section_2_4_2_p_1">A list is set of one or more instances that appear under the same parent. The instances contain details about a specific object. One can think of instances as objects or records. A call is needed to open and close the list, while a distinct call is needed to open and close each instance of the list:</p>
< <div id="doc_figure_u.73"></div> <pre>
< xo_open_list("item");
<
< for (ip = list; ip->i_title; ip++) {
< xo_open_instance("item");
< xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
< xo_close_instance("item");
< }
<
< xo_close_list("item");
< </pre> <p id="doc_section_2_4_2_p_3">Getting the list and instance calls correct is critical to the proper generation of XML and JSON data.</p>
24215,24286d24406
< <div class="content">
< <h3 id="doc_section_2_4_3">
< <div class="self-section-number">
< <a href="#doc_section_2_4_3">2.4.3</a>�</div>
< <a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a>
< </h3>
< <p id="doc_section_2_4_3_p_1">Some users may find tracking the names of open containers, lists, and instances inconvenient. libxo offers a "Do The Right Thing" mode, where libxo will track the names of open containers, lists, and instances so the close function can be called without a name. To enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output.</p>
< <div id="doc_figure_u.74"></div> <pre>
< xo_set_flags(NULL, XOF_DTRT);
< </pre> <p id="doc_section_2_4_3_p_3">Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance:</p>
< <div id="doc_figure_u.75"></div> <pre>
< xo_open_container("top");
< ...
< xo_close_container_d();
< </pre> <p id="doc_section_2_4_3_p_5">This also works for lists and instances:</p>
< <div id="doc_figure_u.76"></div> <pre>
< xo_open_list("item");
< for (...) {
< xo_open_instance("item");
< xo_emit(...);
< xo_close_instance_d();
< }
< xo_close_list_d();
< </pre> <p id="doc_section_2_4_3_p_7">Note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.</p>
< </div>
< <div class="content">
< <h3 id="doc_section_2_4_4">
< <div class="self-section-number">
< <a href="#doc_section_2_4_4">2.4.4</a>�</div>
< <a id="markers" href="#markers">Markers</a>
< </h3>
< <p id="doc_section_2_4_4_p_1">Markers are used to protect and restore the state of open constructs. While a marker is open, no other open constructs can be closed. When a marker is closed, all constructs open since the marker was opened will be closed.</p>
< <p id="doc_section_2_4_4_p_2">Markers use names which are not user-visible, allowing the caller to choose appropriate internal names.</p>
< <p id="doc_section_2_4_4_p_3">In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish‑guts" is used to ensure that any constructs opened by the function are closed properly.</p>
< <div id="doc_figure_u.77"></div> <pre>
< for (i = 0; fish[i]; i++) {
< xo_open_instance("fish");
< xo_open_marker("fish-guts");
< dump_fish_details(i);
< xo_close_marker("fish-guts");
< }
< </pre> </div>
< </div>
< <div class="content">
< <h2 id="doc_section_2_5">
< <div class="self-section-number">
< <a href="#doc_section_2_5">2.5</a>�</div>
< <a id="handles" href="#handles">Handles</a>
< </h2>
< <p id="doc_section_2_5_p_1">libxo uses "handles" to control its rendering functionality. The handle contains state and buffered data, as well as callback functions to process data.</p>
< <p id="doc_section_2_5_p_2">A default handle is used when a NULL is passed to functions accepting a handle. This handle is initialized to write its data to stdout using the default style of text (XO_STYLE_TEXT).</p>
< <p id="doc_section_2_5_p_3">For the convenience of callers, the libxo library includes handle-less functions that implicitly use the default handle. Any function that takes a handle will use the default handle is a value of NULL is passed in place of a valid handle.</p>
< <p id="doc_section_2_5_p_4">For example, the following are equivalent:</p>
< <div id="doc_figure_u.78"></div> <pre>
< xo_emit("test");
< xo_emit_h(NULL, "test");
< </pre> <p id="doc_section_2_5_p_6">Handles are created using xo_create() and destroy using xo_destroy().</p>
< </div>
< <div class="content">
< <h2 id="doc_section_2_6">
< <div class="self-section-number">
< <a href="#doc_section_2_6">2.6</a>�</div>
< <a id="utf-8" href="#utf-8">UTF-8</a>
< </h2>
< <p id="doc_section_2_6_p_1">All strings for libxo must be UTF-8. libxo will handle turning them into locale-based strings for display to the user.</p>
< <p id="doc_section_2_6_p_2">The only exception is argument formatted using the "%ls" format, which require a wide character string (wchar_t *) as input. libxo will convert these arguments as needed to either UTF-8 (for XML, JSON, and HTML styles) or locale-based strings for display in text style.</p>
< <div id="doc_figure_u.79"></div> <pre>
< xo_emit("Alll strings are utf-8 content {:tag/%ls}",
< L"except for wide strings");
< </pre> <p id="doc_section_2_6_p_4">"%S" is equivalent to "%ls".</p>
< </div>
< </div>
24297c24417
< <li><a href="#handles-2" title="Handles">Section�3.1</a></li>
---
> <li><a href="#handles" title="Handles">Section�3.1</a></li>
24308c24428
< <a id="handles-2" href="#handles-2">Handles</a>
---
> <a id="handles" href="#handles">Handles</a>
24310,24312c24430,24432
< <p id="doc_section_3_1_p_1">Handles give an abstraction for libxo that encapsulates the state of a stream of output. Handles have the data type "xo_handle_t" and are opaque to the caller.</p>
< <p id="doc_section_3_1_p_2">The library has a default handle that is automatically initialized. By default, this handle will send text style output to standard output. The xo_set_style and xo_set_flags functions can be used to change this behavior.</p>
< <p id="doc_section_3_1_p_3">Many libxo functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed NULL to access the default handle.</p>
---
> <p id="doc_section_3_1_p_1">libxo uses "handles" to control its rendering functionality. The handle contains state and buffered data, as well as callback functions to process data.</p>
> <p id="doc_section_3_1_p_2">Handles give an abstraction for libxo that encapsulates the state of a stream of output. Handles have the data type "xo_handle_t" and are opaque to the caller.</p>
> <p id="doc_section_3_1_p_3">The library has a default handle that is automatically initialized. By default, this handle will send text style output (XO_STYLE_TEXT) to standard output. The xo_set_style and xo_set_flags functions can be used to change this behavior.</p>
24314c24434,24440
< <p id="doc_section_3_1_p_5">Section Contents: </p>
---
> <p id="doc_section_3_1_p_5">Many libxo functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed NULL to access the default handle. For the convenience of callers, the libxo library includes handle-less functions that implicitly use the default handle.</p>
> <p id="doc_section_3_1_p_6">For example, the following are equivalent:</p>
> <div id="doc_figure_u.84"></div> <pre>
> xo_emit("test");
> xo_emit_h(NULL, "test");
> </pre> <p id="doc_section_3_1_p_8">Handles are created using xo_create() and destroy using xo_destroy().</p>
> <p id="doc_section_3_1_p_9">Section Contents: </p>
24330c24456
< <div id="doc_figure_u.80"></div> <pre>
---
> <div id="doc_figure_u.85"></div> <pre>
24346c24472
< <div id="doc_figure_u.81"></div> <pre>
---
> <div id="doc_figure_u.86"></div> <pre>
24358c24484
< <div id="doc_figure_u.82"></div> <pre>
---
> <div id="doc_figure_u.87"></div> <pre>
24371c24497
< <div id="doc_figure_u.83"></div> <pre>
---
> <div id="doc_figure_u.88"></div> <pre>
24374c24500
< <div id="doc_figure_u.84"></div> <pre>
---
> <div id="doc_figure_u.89"></div> <pre>
24388c24514
< <div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24420c24546
< <div id="doc_figure_u.85"></div> <pre>
---
> <div id="doc_figure_u.90"></div> <pre>
24423c24549
< <div id="doc_figure_u.86"></div> <pre>
---
> <div id="doc_figure_u.91"></div> <pre>
24435c24561
< <div id="doc_figure_u.87"></div> <pre>
---
> <div id="doc_figure_u.92"></div> <pre>
24438c24564
< <div id="doc_figure_u.88"></div> <pre>
---
> <div id="doc_figure_u.93"></div> <pre>
24453c24579
< <div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24531c24657
< <div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24550c24676
< <div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24561c24687
< <div id="doc_figure_u.89"></div> <pre>
---
> <div id="doc_figure_u.94"></div> <pre>
24574c24700
< <div id="doc_figure_u.90"></div> <pre>
---
> <div id="doc_figure_u.95"></div> <pre>
24584c24710
< <div id="doc_figure_u.91"></div> <pre>
---
> <div id="doc_figure_u.96"></div> <pre>
24586c24712
< </pre> <p id="doc_section_3_1_5_3_p_3">The options are identical to those listed in <a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a>.</p>
---
> </pre> <p id="doc_section_3_1_5_3_p_3">The options are identical to those listed in <a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a>.</p>
24596c24722
< <div id="doc_figure_u.92"></div> <pre>
---
> <div id="doc_figure_u.97"></div> <pre>
24607c24733
< <div id="doc_figure_u.93"></div> <pre>
---
> <div id="doc_figure_u.98"></div> <pre>
24611c24737
< </pre> <p id="doc_section_3_2_p_3">The "fmt" argument is a string containing field descriptors as specified in <a href="#format-strings" title="Format Strings">Section�2.2</a>. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See <a href="#handles" title="Handles">Section�2.5</a>.</p>
---
> </pre> <p id="doc_section_3_2_p_3">The "fmt" argument is a string containing field descriptors as specified in <a href="#format-strings" title="Format Strings">Section�2.2</a>. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See <a href="#handles" title="Handles">Section�3.1</a>.</p>
24615,24617c24741,24744
< <li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.1</a></li>
< <li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.2</a></li>
< <li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.3</a></li>
---
> <li><a href="#xo_emit_field" title="Single Field Emitting Functions (xo_emit_field)">Section�3.2.1</a></li>
> <li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.2</a></li>
> <li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.3</a></li>
> <li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.4</a></li>
24622a24750,24772
> <a id="xo_emit_field" href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a>
> </h3>
> <p id="doc_section_3_2_1_p_1">The following functions can also make output, but only make a single field at a time:</p>
> <div id="doc_figure_u.99"></div> <pre>
> int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod,
> const char *contents, const char *fmt,
> const char *efmt, va_list vap);
>
> int xo_emit_field_h (xo_handle_t *xop, const char *rolmod,
> const char *contents, const char *fmt,
> const char *efmt, ...);
>
> int xo_emit_field (const char *rolmod, const char *contents,
> const char *fmt, const char *efmt, ...);
> </pre> <p id="doc_section_3_2_1_p_3">These functions are intended to avoid the scenario where one would otherwise need to compose a format descriptors using snprintf(). The individual parts of the format descriptor are passed in distinctly.</p>
> <div id="doc_figure_u.100"></div> <pre>
> xo_emit("T", "Host name is ", NULL, NULL);
> xo_emit("V", "host-name", NULL, NULL, host-name);
> </pre> </div>
> <div class="content">
> <h3 id="doc_section_3_2_2">
> <div class="self-section-number">
> <a href="#doc_section_3_2_2">3.2.2</a>�</div>
24625,24626c24775,24776
< <p id="doc_section_3_2_1_p_1">The xo_attr() function emits attributes for the XML output style.</p>
< <div id="doc_figure_u.94"></div> <pre>
---
> <p id="doc_section_3_2_2_p_1">The xo_attr() function emits attributes for the XML output style.</p>
> <div id="doc_figure_u.101"></div> <pre>
24632,24633c24782,24783
< </pre> <p id="doc_section_3_2_1_p_3">The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().</p>
< <div id="doc_figure_u.95"></div> <pre>
---
> </pre> <p id="doc_section_3_2_2_p_3">The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().</p>
> <div id="doc_figure_u.102"></div> <pre>
24641,24642c24791,24792
< </pre> <p id="doc_section_3_2_1_p_5">xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.</p>
< <p id="doc_section_3_2_1_p_6">Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.</p>
---
> </pre> <p id="doc_section_3_2_2_p_5">xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.</p>
> <p id="doc_section_3_2_2_p_6">Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.</p>
24645c24795
< <h3 id="doc_section_3_2_2">
---
> <h3 id="doc_section_3_2_3">
24647c24797
< <a href="#doc_section_3_2_2">3.2.2</a>�</div>
---
> <a href="#doc_section_3_2_3">3.2.3</a>�</div>
24650,24651c24800,24801
< <p id="doc_section_3_2_2_p_1">libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:</p>
< <div id="doc_figure_u.96"></div> <pre>
---
> <p id="doc_section_3_2_3_p_1">libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:</p>
> <div id="doc_figure_u.103"></div> <pre>
24654c24804
< </pre> <p id="doc_section_3_2_2_p_3">Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".</p>
---
> </pre> <p id="doc_section_3_2_3_p_3">Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".</p>
24657c24807
< <h3 id="doc_section_3_2_3">
---
> <h3 id="doc_section_3_2_4">
24659c24809
< <a href="#doc_section_3_2_3">3.2.3</a>�</div>
---
> <a href="#doc_section_3_2_4">3.2.4</a>�</div>
24662,24663c24812,24813
< <p id="doc_section_3_2_3_p_1">When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.</p>
< <div id="doc_figure_u.97"></div> <pre>
---
> <p id="doc_section_3_2_4_p_1">When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.</p>
> <div id="doc_figure_u.104"></div> <pre>
24667,24668c24817,24818
< </pre> <p id="doc_section_3_2_3_p_3">Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.</p>
< <p id="doc_section_3_2_3_p_4">xo_finish_atexit is suitable for use with atexit(3).</p>
---
> </pre> <p id="doc_section_3_2_4_p_3">Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.</p>
> <p id="doc_section_3_2_4_p_4">xo_finish_atexit is suitable for use with atexit(3).</p>
24679c24829
< <div id="doc_figure_u.98"></div> <pre>
---
> <div id="doc_figure_u.105"></div> <pre>
24693c24843
< <div id="doc_figure_u.99"></div> <pre>
---
> <div id="doc_figure_u.106"></div> <pre>
24710c24860
< <div id="doc_figure_u.100"></div> <pre>
---
> <div id="doc_figure_u.107"></div> <pre>
24779c24929
< <div id="doc_figure_u.101"></div> <pre>
---
> <div id="doc_figure_u.108"></div> <pre>
24783c24933
< </pre> <p id="doc_section_3_4_1_p_3">Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See <a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a> for a description of valid arguments.</p>
---
> </pre> <p id="doc_section_3_4_1_p_3">Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See <a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a> for a description of valid arguments.</p>
24792c24942
< <div id="doc_figure_u.102"></div> <pre>
---
> <div id="doc_figure_u.109"></div> <pre>
24803c24953
< <div id="doc_figure_u.103"></div> <pre>
---
> <div id="doc_figure_u.110"></div> <pre>
24816c24966
< <div id="doc_figure_u.104"></div> <pre>
---
> <div id="doc_figure_u.111"></div> <pre>
24826c24976
< <div id="doc_figure_u.105"></div> <pre>
---
> <div id="doc_figure_u.112"></div> <pre>
24839c24989
< <div id="doc_figure_u.106"></div> <pre>
---
> <div id="doc_figure_u.113"></div> <pre>
24850c25000
< <div id="doc_figure_u.107"></div> <pre>
---
> <div id="doc_figure_u.114"></div> <pre>
24863c25013
< <div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24932c25082
< <div id="doc_figure_u.108"></div> <pre>
---
> <div id="doc_figure_u.115"></div> <pre>
24935c25085
< <div id="doc_figure_u.109"></div> <pre>
---
> <div id="doc_figure_u.116"></div> <pre>
24946c25096
< <div id="doc_figure_u.110"></div> <pre>
---
> <div id="doc_figure_u.117"></div> <pre>
24962c25112
< <div id="doc_figure_u.111"></div> <pre>
---
> <div id="doc_figure_u.118"></div> <pre>
24974c25124
< <div id="doc_figure_u.112"></div> <pre>
---
> <div id="doc_figure_u.119"></div> <pre>
24989c25139
< <div id="doc_figure_u.113"></div> <pre>
---
> <div id="doc_figure_u.120"></div> <pre>
25005c25155
< <div id="doc_figure_u.114"></div> <pre>
---
> <div id="doc_figure_u.121"></div> <pre>
25033c25183
< <div id="doc_figure_u.115"></div> <pre>
---
> <div id="doc_figure_u.122"></div> <pre>
25039c25189
< <div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25080c25230
< <div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25145c25295
< <div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25178c25328
< <div id="doc_figure_u.116"></div> <pre>
---
> <div id="doc_figure_u.123"></div> <pre>
25207c25357
< <div id="doc_figure_u.117"></div> <pre>
---
> <div id="doc_figure_u.124"></div> <pre>
25223c25373
< <div id="doc_figure_u.118"></div> <pre>
---
> <div id="doc_figure_u.125"></div> <pre>
25234c25384
< <div id="doc_figure_u.119"></div> <pre>
---
> <div id="doc_figure_u.126"></div> <pre>
25245c25395
< <div id="doc_figure_u.120"></div> <pre>
---
> <div id="doc_figure_u.127"></div> <pre>
25260c25410
< <div id="doc_figure_u.121"></div> <pre>
---
> <div id="doc_figure_u.128"></div> <pre>
25302c25452
< <div id="doc_figure_u.122"></div> <pre>
---
> <div id="doc_figure_u.129"></div> <pre>
25314c25464
< <div id="doc_figure_u.123"></div> <pre>
---
> <div id="doc_figure_u.130"></div> <pre>
25332c25482
< <div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25419c25569
< <div id="doc_figure_u.124"></div> <pre>
---
> <div id="doc_figure_u.131"></div> <pre>
25439c25589
< <div id="doc_figure_u.125"></div> <pre>
---
> <div id="doc_figure_u.132"></div> <pre>
25463c25613
< <div id="doc_figure_u.126"></div> <pre>
---
> <div id="doc_figure_u.133"></div> <pre>
25492c25642
< <div id="doc_figure_u.127"></div> <pre>
---
> <div id="doc_figure_u.134"></div> <pre>
25516c25666
< <div id="doc_figure_u.128"></div> <pre>
---
> <div id="doc_figure_u.135"></div> <pre>
25533c25683
< <div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25574c25724
< <div id="doc_figure_u.129"></div> <pre>
---
> <div id="doc_figure_u.136"></div> <pre>
25590c25740
< <div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.21"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25622c25772
< <div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.22"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25642c25792
< <div id="doc_figure_u.130"></div> <pre>
---
> <div id="doc_figure_u.137"></div> <pre>
25690,25692c25840,25842
< <p id="doc_section_8_1_1_p_1">In 2001, we added an XML API to the JUNOS operating system, which is built on top of FreeBSD. Eventually this API became standardized as the NETCONF API (RFC 6241). As part of this effort, we modified many FreeBSD utilities to emit XML, typically via a "‑X" switch. The results were mixed. The cost of maintaining this code, updating it and carrying it were non-trivial, and contributed to our expense (and the associated delay) with upgrading the version of FreeBSD on which each release of JUNOS is based.</p>
< <p id="doc_section_8_1_1_p_2">A recent (2014) effort within JUNOS aims at removing our modifications to the underlying FreeBSD code as a means of reducing the expense and delay. JUNOS is structured to have system components generate XML that is rendered by the CLI (think: login shell) into human-readable text. This allows the API to use the same plumbing as the CLI, and ensures that all components emit XML, and that it is emitted with knowledge of the consumer of that XML, yielding an API that have no incremental cost or feature delay.</p>
< <p id="doc_section_8_1_1_p_3">libxo is an effort to mix the best aspects of the JUNOS strategy into FreeBSD in a seemless way, allowing commands to make printf-like output calls without needing to care how the output is rendered.</p>
---
> <p id="doc_section_8_1_1_p_1">In 2001, we added an XML API to the JUNOS operating system, which is built on top of FreeBSD. Eventually this API became standardized as the NETCONF API (RFC 6241). As part of this effort, we modified many FreeBSD utilities to emit XML, typically via a "‑X" switch. The results were mixed. The cost of maintaining this code, updating it, and carrying it were non-trivial, and contributed to our expense (and the associated delay) with upgrading the version of FreeBSD on which each release of JUNOS is based.</p>
> <p id="doc_section_8_1_1_p_2">A recent (2014) effort within JUNOS aims at removing our modifications to the underlying FreeBSD code as a means of reducing the expense and delay in tracking HEAD. JUNOS is structured to have system components generate XML that is rendered by the CLI (think: login shell) into human-readable text. This allows the API to use the same plumbing as the CLI, and ensures that all components emit XML, and that it is emitted with knowledge of the consumer of that XML, yielding an API that have no incremental cost or feature delay.</p>
> <p id="doc_section_8_1_1_p_3">libxo is an effort to mix the best aspects of the JUNOS strategy into FreeBSD in a seemless way, allowing commands to make printf-like output calls with a single code path.</p>
25701c25851
< <div id="doc_figure_u.131"></div> <pre>
---
> <div id="doc_figure_u.138"></div> <pre>
25780c25930
< <div id="doc_figure_u.132"></div> <pre>
---
> <div id="doc_figure_u.139"></div> <pre>
25792c25942
< <dd>Have empathy for your users, choosing clear and useful fields that contain clear and useful data. You may need to augment the display content with xo_attr() calls (<a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.1</a>) or "{e:}" fields (<a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.3</a>) to make the data useful.</dd>
---
> <dd>Have empathy for your users, choosing clear and useful fields that contain clear and useful data. You may need to augment the display content with xo_attr() calls (<a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.2</a>) or "{e:}" fields (<a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.4</a>) to make the data useful.</dd>
25841c25991
< <div id="doc_figure_u.133"></div> <pre>
---
> <div id="doc_figure_u.140"></div> <pre>
25844c25994
< <div id="doc_figure_u.134"></div> <pre>
---
> <div id="doc_figure_u.141"></div> <pre>
25855c26005
< <div id="doc_figure_u.135"></div> <pre>
---
> <div id="doc_figure_u.142"></div> <pre>
25858c26008
< <div id="doc_figure_u.136"></div> <pre>
---
> <div id="doc_figure_u.143"></div> <pre>
25870c26020
< <div id="doc_figure_u.137"></div> <pre>
---
> <div id="doc_figure_u.144"></div> <pre>
25873c26023
< <div id="doc_figure_u.138"></div> <pre>
---
> <div id="doc_figure_u.145"></div> <pre>
25884c26034
< <div id="doc_figure_u.139"></div> <pre>
---
> <div id="doc_figure_u.146"></div> <pre>
25887c26037
< <div id="doc_figure_u.140"></div> <pre>
---
> <div id="doc_figure_u.147"></div> <pre>
25898c26048
< <div id="doc_figure_u.141"></div> <pre>
---
> <div id="doc_figure_u.148"></div> <pre>
25901c26051
< <div id="doc_figure_u.142"></div> <pre>
---
> <div id="doc_figure_u.149"></div> <pre>
25911c26061
< <div id="doc_figure_u.143"></div> <pre>
---
> <div id="doc_figure_u.150"></div> <pre>
25914c26064
< <div id="doc_figure_u.144"></div> <pre>
---
> <div id="doc_figure_u.151"></div> <pre>
25925c26075
< <div id="doc_figure_u.145"></div> <pre>
---
> <div id="doc_figure_u.152"></div> <pre>
25936c26086
< <div id="doc_figure_u.146"></div> <pre>
---
> <div id="doc_figure_u.153"></div> <pre>
25947c26097
< <div id="doc_figure_u.147"></div> <pre>
---
> <div id="doc_figure_u.154"></div> <pre>
25950c26100
< <div id="doc_figure_u.148"></div> <pre>
---
> <div id="doc_figure_u.155"></div> <pre>
25961c26111
< <div id="doc_figure_u.149"></div> <pre>
---
> <div id="doc_figure_u.156"></div> <pre>
25964c26114
< <div id="doc_figure_u.150"></div> <pre>
---
> <div id="doc_figure_u.157"></div> <pre>
25975c26125
< <div id="doc_figure_u.151"></div> <pre>
---
> <div id="doc_figure_u.158"></div> <pre>
25978c26128
< <div id="doc_figure_u.152"></div> <pre>
---
> <div id="doc_figure_u.159"></div> <pre>
25989c26139
< <div id="doc_figure_u.153"></div> <pre>
---
> <div id="doc_figure_u.160"></div> <pre>
25992c26142
< <div id="doc_figure_u.154"></div> <pre>
---
> <div id="doc_figure_u.161"></div> <pre>
26003c26153
< <div id="doc_figure_u.155"></div> <pre>
---
> <div id="doc_figure_u.162"></div> <pre>
26006c26156
< <div id="doc_figure_u.156"></div> <pre>
---
> <div id="doc_figure_u.163"></div> <pre>
26017c26167
< <div id="doc_figure_u.157"></div> <pre>
---
> <div id="doc_figure_u.164"></div> <pre>
26020c26170
< <div id="doc_figure_u.158"></div> <pre>
---
> <div id="doc_figure_u.165"></div> <pre>
26031c26181
< <div id="doc_figure_u.159"></div> <pre>
---
> <div id="doc_figure_u.166"></div> <pre>
26034c26184
< <div id="doc_figure_u.160"></div> <pre>
---
> <div id="doc_figure_u.167"></div> <pre>
26045c26195
< <div id="doc_figure_u.161"></div> <pre>
---
> <div id="doc_figure_u.168"></div> <pre>
26048c26198
< <div id="doc_figure_u.162"></div> <pre>
---
> <div id="doc_figure_u.169"></div> <pre>
26059c26209
< <div id="doc_figure_u.163"></div> <pre>
---
> <div id="doc_figure_u.170"></div> <pre>
26062c26212
< <div id="doc_figure_u.164"></div> <pre>
---
> <div id="doc_figure_u.171"></div> <pre>
26073c26223
< <div id="doc_figure_u.165"></div> <pre>
---
> <div id="doc_figure_u.172"></div> <pre>
26076c26226
< <div id="doc_figure_u.166"></div> <pre>
---
> <div id="doc_figure_u.173"></div> <pre>
26087c26237
< <div id="doc_figure_u.167"></div> <pre>
---
> <div id="doc_figure_u.174"></div> <pre>
26090c26240
< <div id="doc_figure_u.168"></div> <pre>
---
> <div id="doc_figure_u.175"></div> <pre>
26101c26251
< <div id="doc_figure_u.169"></div> <pre>
---
> <div id="doc_figure_u.176"></div> <pre>
26104c26254
< <div id="doc_figure_u.170"></div> <pre>
---
> <div id="doc_figure_u.177"></div> <pre>
26115c26265
< <div id="doc_figure_u.171"></div> <pre>
---
> <div id="doc_figure_u.178"></div> <pre>
26118c26268
< <div id="doc_figure_u.172"></div> <pre>
---
> <div id="doc_figure_u.179"></div> <pre>
26129c26279
< <div id="doc_figure_u.173"></div> <pre>
---
> <div id="doc_figure_u.180"></div> <pre>
26132c26282
< <div id="doc_figure_u.174"></div> <pre>
---
> <div id="doc_figure_u.181"></div> <pre>
26143c26293
< <div id="doc_figure_u.175"></div> <pre>
---
> <div id="doc_figure_u.182"></div> <pre>
26146c26296
< <div id="doc_figure_u.176"></div> <pre>
---
> <div id="doc_figure_u.183"></div> <pre>
26186c26336
< <div id="doc_figure_u.177"></div> <pre>
---
> <div id="doc_figure_u.184"></div> <pre>
26195c26345
< <div id="doc_figure_u.178"></div> <pre>
---
> <div id="doc_figure_u.185"></div> <pre>
26215c26365
< <div id="doc_figure_u.179"></div> <pre>
---
> <div id="doc_figure_u.186"></div> <pre>
26239c26389
< <div id="doc_figure_u.180"></div> <pre>
---
> <div id="doc_figure_u.187"></div> <pre>
26242c26392
< <div id="doc_figure_u.181"></div> <pre>
---
> <div id="doc_figure_u.188"></div> <pre>
26250,26251c26400,26401
< </pre> <p id="doc_section_9_3_1_p_5">At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (<a href="#handles" title="Handles">Section�2.5</a>). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.</p>
< <div id="doc_figure_u.182"></div> <pre>
---
> </pre> <p id="doc_section_9_3_1_p_5">At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (<a href="#handles" title="Handles">Section�3.1</a>). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.</p>
> <div id="doc_figure_u.189"></div> <pre>
26261c26411
< <div id="doc_figure_u.183"></div> <pre>
---
> <div id="doc_figure_u.190"></div> <pre>
26267c26417
< <div id="doc_figure_u.184"></div> <pre>
---
> <div id="doc_figure_u.191"></div> <pre>
26271c26421
< <div id="doc_figure_u.185"></div> <pre>
---
> <div id="doc_figure_u.192"></div> <pre>
26274c26424
< <div id="doc_figure_u.186"></div> <pre>
---
> <div id="doc_figure_u.193"></div> <pre>
26288c26438
< <div id="doc_figure_u.187"></div> <pre>
---
> <div id="doc_figure_u.194"></div> <pre>
26306c26456
< <div id="doc_figure_u.188"></div> <pre>
---
> <div id="doc_figure_u.195"></div> <pre>
26325c26475
< <div id="doc_figure_u.189"></div> <pre>
---
> <div id="doc_figure_u.196"></div> <pre>
26343c26493
< <div id="doc_figure_u.190"></div> <pre>
---
> <div id="doc_figure_u.197"></div> <pre>
26348c26498
< <div id="doc_figure_u.191"></div> <pre>
---
> <div id="doc_figure_u.198"></div> <pre>
26381c26531
< <div id="doc_figure_u.192"></div> <pre>
---
> <div id="doc_figure_u.199"></div> <pre>
26399c26549
< <div id="doc_figure_u.193"></div> <pre>
---
> <div id="doc_figure_u.200"></div> <pre>
26407c26557
< <div id="doc_figure_u.194"></div> <pre>
---
> <div id="doc_figure_u.201"></div> <pre>
26410c26560
< <div id="doc_figure_u.195"></div> <pre>
---
> <div id="doc_figure_u.202"></div> <pre>
26417c26567
< <div id="doc_figure_u.196"></div> <pre>
---
> <div id="doc_figure_u.203"></div> <pre>
26442c26592
< <div id="doc_figure_u.197"></div> <pre>
---
> <div id="doc_figure_u.204"></div> <pre>
26535c26685
< <div id="doc_figure_u.198"></div> <pre>
---
> <div id="doc_figure_u.205"></div> <pre>
26568c26718
< <div id="doc_figure_u.199"></div> <pre>
---
> <div id="doc_figure_u.206"></div> <pre>
26623c26773
< <div id="doc_figure_u.200"></div> <pre>
---
> <div id="doc_figure_u.207"></div> <pre>
26674c26824
< <div id="doc_figure_u.201"></div> <pre>
---
> <div id="doc_figure_u.208"></div> <pre>
26869c27019
< <div id="doc_figure_u.202"></div> <pre>
---
> <div id="doc_figure_u.209"></div> <pre>
< content: "December 2015";
---
> content: "April 2016";
22012c22012
< <td class="header right">December 30, 2015</td>
---
> <td class="header right">April 15, 2016</td>
22133c22133
< <a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
---
> <a href="#the-argument-modifier-a">The Argument Modifier ({a:})</a>
22137c22137
< <a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
---
> <a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
22141c22141
< <a href="#e-modifier">The Encoding Modifier ({e:})</a>
---
> <a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
22145c22145
< <a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
---
> <a href="#e-modifier">The Encoding Modifier ({e:})</a>
22149c22149
< <a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
---
> <a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
22153c22153
< <a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
---
> <a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
22157c22157
< <a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
---
> <a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
22161c22161
< <a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
---
> <a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
22165c22165
< <a href="#plural-modifier">The Plural Modifier ({p:})</a>
---
> <a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
22169c22169
< <a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
---
> <a href="#plural-modifier">The Plural Modifier ({p:})</a>
22172a22173,22180
> <a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_2_12">2.2.2.12���</div>
> <a href="#the-trim-modifier-t">The Trim Modifier ({t:})</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_2_13">2.2.2.13���</div>
22210a22219,22222
> <a href="#retain">Retaining Parsed Format Information</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_2_2_12">2.2.12���</div>
22217,22220d22228
< <a href="#command-line-arguments">Command-line Arguments</a>
< </li>
< <li class="tocline1">
< <div class="section-number" id="toc_doc_section_2_4">2.4���</div>
22223c22231
< <div class="section-number" id="toc_doc_section_2_4_1">2.4.1���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_1">2.3.1���</div>
22227c22235
< <div class="section-number" id="toc_doc_section_2_4_2">2.4.2���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_2">2.3.2���</div>
22231c22239
< <div class="section-number" id="toc_doc_section_2_4_3">2.4.3���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_3">2.3.3���</div>
22235c22243
< <div class="section-number" id="toc_doc_section_2_4_4">2.4.4���</div>
---
> <div class="section-number" id="toc_doc_section_2_3_4">2.3.4���</div>
22241,22242c22249,22250
< <div class="section-number" id="toc_doc_section_2_5">2.5���</div>
< <a href="#handles">Handles</a>
---
> <div class="section-number" id="toc_doc_section_2_4">2.4���</div>
> <a href="#command-line-arguments">Command-line Arguments</a>
22244,22247d22251
< <li class="tocline1">
< <div class="section-number" id="toc_doc_section_2_6">2.6���</div>
< <a href="#utf-8">UTF-8</a>
< </li>
22255c22259
< <a href="#handles-2">Handles</a><ul class="toc">
---
> <a href="#handles">Handles</a><ul class="toc">
22309c22313
< <a href="#xo_attr">Attributes (xo_attr)</a>
---
> <a href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a>
22313c22317
< <a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
---
> <a href="#xo_attr">Attributes (xo_attr)</a>
22316a22321,22324
> <a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
> </li>
> <li class="tocline1">
> <div class="section-number" id="toc_doc_section_3_2_4">3.2.4���</div>
22854,22857c22862,22863
< <li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a></li>
< <li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.4</a></li>
< <li><a href="#handles" title="Handles">Section�2.5</a></li>
< <li><a href="#utf-8" title="UTF-8">Section�2.6</a></li>
---
> <li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.3</a></li>
> <li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a></li>
22995c23001,23002
< <li><a href="#example" title="Example">Section�2.2.11</a></li>
---
> <li><a href="#retain" title="Retaining Parsed Format Information">Section�2.2.11</a></li>
> <li><a href="#example" title="Example">Section�2.2.12</a></li>
23358a23366,23370
> <td>a</td>
> <td>argument</td>
> <td>The content appears as a 'const char *' argument</td>
> </tr>
> <tr>
23438,23448c23450,23462
< <li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.1</a></li>
< <li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.2</a></li>
< <li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.3</a></li>
< <li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.4</a></li>
< <li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.5</a></li>
< <li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.6</a></li>
< <li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.7</a></li>
< <li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.8</a></li>
< <li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.9</a></li>
< <li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.10</a></li>
< <li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.11</a></li>
---
> <li><a href="#the-argument-modifier-a" title="The Argument Modifier ({a:})">Section�2.2.2.1</a></li>
> <li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.2</a></li>
> <li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.3</a></li>
> <li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.4</a></li>
> <li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.5</a></li>
> <li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.6</a></li>
> <li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.7</a></li>
> <li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.8</a></li>
> <li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.9</a></li>
> <li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.10</a></li>
> <li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.11</a></li>
> <li><a href="#the-trim-modifier-t" title="The Trim Modifier ({t:})">Section�2.2.2.12</a></li>
> <li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.13</a></li>
23454c23468
< <a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
---
> <a id="the-argument-modifier-a" href="#the-argument-modifier-a">The Argument Modifier ({a:})</a>
23456c23470
< <p id="doc_section_2_2_2_1_p_1">The colon modifier appends a single colon to the data value:</p>
---
> <p id="doc_section_2_2_2_1_p_1">The argument modifier indicates that the content of the field descriptor will be placed as a UTF-8 string (const char *) argument within the xo_emit parameters.</p>
23459c23473
< xo_emit("{Lc:Name}{:name}\n", "phil");
---
> xo_emit("{La:} {a:}\n", "Label text", "label", "value");
23461,23462c23475,23480
< Name:phil
< </pre> <p id="doc_section_2_2_2_1_p_3">The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier ('{w:}'). It is purely a convenience feature.</p>
---
> Label text value
> JSON:
> "label": "value"
> XML:
> <label>value</label>
> </pre> <p id="doc_section_2_2_2_1_p_3">The argument modifier allows field names for value fields to be passed on the stack, avoiding the need to build a field descriptor using snprintf. For many field roles, the argument modifier is not needed, since those roles have specific mechanisms for arguments, such as "{C:fg‑%s}".</p>
23468c23486
< <a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a>
---
> <a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
23470c23488
< <p id="doc_section_2_2_2_2_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
---
> <p id="doc_section_2_2_2_2_p_1">The colon modifier appends a single colon to the data value:</p>
23472a23491,23504
> xo_emit("{Lc:Name}{:name}\n", "phil");
> TEXT:
> Name:phil
> </pre> <p id="doc_section_2_2_2_2_p_3">The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier ('{w:}'). It is purely a convenience feature.</p>
> </div>
> <div class="content">
> <h4 id="doc_section_2_2_2_3">
> <div class="self-section-number">
> <a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
> <a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a>
> </h4>
> <p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
> <div id="doc_figure_u.50"></div> <pre>
> EXAMPLE:
23478c23510
< </pre> <p id="doc_section_2_2_2_2_p_3">The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data.</p>
---
> </pre> <p id="doc_section_2_2_2_3_p_3">The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data.</p>
23481c23513
< <h4 id="doc_section_2_2_2_3">
---
> <h4 id="doc_section_2_2_2_4">
23483c23515
< <a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
---
> <a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
23486,23487c23518,23519
< <p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
< <div id="doc_figure_u.50"></div> <pre>
---
> <p id="doc_section_2_2_2_4_p_1">The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML.</p>
> <div id="doc_figure_u.51"></div> <pre>
23494c23526
< </pre> <p id="doc_section_2_2_2_3_p_3">The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data.</p>
---
> </pre> <p id="doc_section_2_2_2_4_p_3">The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data.</p>
23497c23529
< <h4 id="doc_section_2_2_2_4">
---
> <h4 id="doc_section_2_2_2_5">
23499c23531
< <a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
---
> <a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
23502,23504c23534,23536
< <p id="doc_section_2_2_2_4_p_1">The gettext modifier is used to translate individual fields using the gettext domain (typically set using the "{G:}" role) and current language settings. Once libxo renders the field value, it is passed to gettext(3), where it is used as a key to find the native language translation.</p>
< <p id="doc_section_2_2_2_4_p_2">In the following example, the strings "State" and "full" are passed to gettext() to find locale-based translated strings.</p>
< <div id="doc_figure_u.51"></div> <pre>
---
> <p id="doc_section_2_2_2_5_p_1">The gettext modifier is used to translate individual fields using the gettext domain (typically set using the "{G:}" role) and current language settings. Once libxo renders the field value, it is passed to gettext(3), where it is used as a key to find the native language translation.</p>
> <p id="doc_section_2_2_2_5_p_2">In the following example, the strings "State" and "full" are passed to gettext() to find locale-based translated strings.</p>
> <div id="doc_figure_u.52"></div> <pre>
23506c23538
< </pre> <p id="doc_section_2_2_2_4_p_4">See <a href="#gettext-role" title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.9</a>, and <a href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a> for additional details.</p>
---
> </pre> <p id="doc_section_2_2_2_5_p_4">See <a href="#gettext-role" title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.10</a>, and <a href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a> for additional details.</p>
23509c23541
< <h4 id="doc_section_2_2_2_5">
---
> <h4 id="doc_section_2_2_2_6">
23511c23543
< <a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
---
> <a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
23514,23518c23546,23550
< <p id="doc_section_2_2_2_5_p_1">The humanize modifier is used to render large numbers as in a human-readable format. While numbers like "44470272" are completely readable to computers and savants, humans will generally find "44M" more meaningful.</p>
< <p id="doc_section_2_2_2_5_p_2">"hn" can be used as an alias for "humanize".</p>
< <p id="doc_section_2_2_2_5_p_3">The humanize modifier only affects display styles (TEXT and HMTL). The "no‑humanize" option (See <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the function of the humanize modifier.</p>
< <p id="doc_section_2_2_2_5_p_4">There are a number of modifiers that affect details of humanization. These are only available in as full names, not single characters. The "hn‑space" modifier places a space between the number and any multiplier symbol, such as "M" or "K" (ex: "44 K"). The "hn‑decimal" modifier will add a decimal point and a single tenths digit when the number is less than 10 (ex: "4.4K"). The "hn‑1000" modifier will use 1000 as divisor instead of 1024, following the JEDEC-standard instead of the more natural binary powers-of-two tradition.</p>
< <div id="doc_figure_u.52"></div> <pre>
---
> <p id="doc_section_2_2_2_6_p_1">The humanize modifier is used to render large numbers as in a human-readable format. While numbers like "44470272" are completely readable to computers and savants, humans will generally find "44M" more meaningful.</p>
> <p id="doc_section_2_2_2_6_p_2">"hn" can be used as an alias for "humanize".</p>
> <p id="doc_section_2_2_2_6_p_3">The humanize modifier only affects display styles (TEXT and HMTL). The "no‑humanize" option (See <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the function of the humanize modifier.</p>
> <p id="doc_section_2_2_2_6_p_4">There are a number of modifiers that affect details of humanization. These are only available in as full names, not single characters. The "hn‑space" modifier places a space between the number and any multiplier symbol, such as "M" or "K" (ex: "44 K"). The "hn‑decimal" modifier will add a decimal point and a single tenths digit when the number is less than 10 (ex: "4.4K"). The "hn‑1000" modifier will use 1000 as divisor instead of 1024, following the JEDEC-standard instead of the more natural binary powers-of-two tradition.</p>
> <div id="doc_figure_u.53"></div> <pre>
23526,23527c23558,23559
< </pre> <p id="doc_section_2_2_2_5_p_6">In the HTML style, the original numeric value is rendered in the "data‑number" attribute on the <div> element:</p>
< <div id="doc_figure_u.53"></div> <pre>
---
> </pre> <p id="doc_section_2_2_2_6_p_6">In the HTML style, the original numeric value is rendered in the "data‑number" attribute on the <div> element:</p>
> <div id="doc_figure_u.54"></div> <pre>
23532c23564
< <h4 id="doc_section_2_2_2_6">
---
> <h4 id="doc_section_2_2_2_7">
23534c23566
< <a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
---
> <a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
23537,23538c23569,23570
< <p id="doc_section_2_2_2_6_p_1">The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data.</p>
< <div id="doc_figure_u.54"></div> <pre>
---
> <p id="doc_section_2_2_2_7_p_1">The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data.</p>
> <div id="doc_figure_u.55"></div> <pre>
23548c23580
< </pre> <p id="doc_section_2_2_2_6_p_3">Currently the key modifier is only used when generating XPath value for the HTML output style when XOF_XPATH is set, but other uses are likely in the near future.</p>
---
> </pre> <p id="doc_section_2_2_2_7_p_3">Currently the key modifier is only used when generating XPath value for the HTML output style when XOF_XPATH is set, but other uses are likely in the near future.</p>
23551c23583
< <h4 id="doc_section_2_2_2_7">
---
> <h4 id="doc_section_2_2_2_8">
23553c23585
< <a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
---
> <a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
23556,23557c23588,23589
< <p id="doc_section_2_2_2_7_p_1">The leaf-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays.</p>
< <div id="doc_figure_u.55"></div> <pre>
---
> <p id="doc_section_2_2_2_8_p_1">The leaf-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays.</p>
> <div id="doc_figure_u.56"></div> <pre>
23567c23599
< </pre> <p id="doc_section_2_2_2_7_p_3">The name of the field must match the name of the leaf list.</p>
---
> </pre> <p id="doc_section_2_2_2_8_p_3">The name of the field must match the name of the leaf list.</p>
23570c23602
< <h4 id="doc_section_2_2_2_8">
---
> <h4 id="doc_section_2_2_2_9">
23572c23604
< <a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
---
> <a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
23575,23576c23607,23608
< <p id="doc_section_2_2_2_8_p_1">The no-quotes modifier (and its twin, the 'quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
< <div id="doc_figure_u.56"></div> <pre>
---
> <p id="doc_section_2_2_2_9_p_1">The no-quotes modifier (and its twin, the 'quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
> <div id="doc_figure_u.57"></div> <pre>
23584c23616
< <h4 id="doc_section_2_2_2_9">
---
> <h4 id="doc_section_2_2_2_10">
23586c23618
< <a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
---
> <a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
23589,23590c23621,23622
< <p id="doc_section_2_2_2_9_p_1">The plural modifier selects the appropriate plural form of an expression based on the most recent number emitted and the current language settings. The contents of the field should be the singular and plural English values, separated by a comma:</p>
< <div id="doc_figure_u.57"></div> <pre>
---
> <p id="doc_section_2_2_2_10_p_1">The plural modifier selects the appropriate plural form of an expression based on the most recent number emitted and the current language settings. The contents of the field should be the singular and plural English values, separated by a comma:</p>
> <div id="doc_figure_u.58"></div> <pre>
23592,23594c23624,23626
< </pre> <p id="doc_section_2_2_2_9_p_3">The plural modifier is meant to work with the gettext modifier ({g:}) but can work independently. See <a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.4</a>.</p>
< <p id="doc_section_2_2_2_9_p_4">When used without the gettext modifier or when the message does not appear in the message catalog, the first token is chosen when the last numeric value is equal to 1; otherwise the second value is used, mimicking the simple pluralization rules of English.</p>
< <p id="doc_section_2_2_2_9_p_5">When used with the gettext modifier, the ngettext(3) function is called to handle the heavy lifting, using the message catalog to convert the singular and plural forms into the native language.</p>
---
> </pre> <p id="doc_section_2_2_2_10_p_3">The plural modifier is meant to work with the gettext modifier ({g:}) but can work independently. See <a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.5</a>.</p>
> <p id="doc_section_2_2_2_10_p_4">When used without the gettext modifier or when the message does not appear in the message catalog, the first token is chosen when the last numeric value is equal to 1; otherwise the second value is used, mimicking the simple pluralization rules of English.</p>
> <p id="doc_section_2_2_2_10_p_5">When used with the gettext modifier, the ngettext(3) function is called to handle the heavy lifting, using the message catalog to convert the singular and plural forms into the native language.</p>
23597c23629
< <h4 id="doc_section_2_2_2_10">
---
> <h4 id="doc_section_2_2_2_11">
23599c23631
< <a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
---
> <a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
23602,23603c23634,23635
< <p id="doc_section_2_2_2_10_p_1">The quotes modifier (and its twin, the 'no‑quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
< <div id="doc_figure_u.58"></div> <pre>
---
> <p id="doc_section_2_2_2_11_p_1">The quotes modifier (and its twin, the 'no‑quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller.</p>
> <div id="doc_figure_u.59"></div> <pre>
23607a23640,23642
> </pre> <p id="doc_section_2_2_2_11_p_3">The heuristic is based on the format; if the format uses any of the following conversion specifiers, then no quotes are used:</p>
> <div id="doc_figure_u.60"></div> <pre>
> d i o u x X D O U e E f F g G a A c C p
23610c23645
< <h4 id="doc_section_2_2_2_11">
---
> <h4 id="doc_section_2_2_2_12">
23612c23647,23660
< <a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
---
> <a href="#doc_section_2_2_2_12">2.2.2.12</a>�</div>
> <a id="the-trim-modifier-t" href="#the-trim-modifier-t">The Trim Modifier ({t:})</a>
> </h4>
> <p id="doc_section_2_2_2_12_p_1">The trim modifier removes any leading or trailing whitespace from the value.</p>
> <div id="doc_figure_u.61"></div> <pre>
> EXAMPLE:
> xo_emit("{t:description}", " some input ");
> JSON:
> "description": "some input"
> </pre> </div>
> <div class="content">
> <h4 id="doc_section_2_2_2_13">
> <div class="self-section-number">
> <a href="#doc_section_2_2_2_13">2.2.2.13</a>�</div>
23615,23616c23663,23664
< <p id="doc_section_2_2_2_11_p_1">The white space modifier appends a single space to the data value:</p>
< <div id="doc_figure_u.59"></div> <pre>
---
> <p id="doc_section_2_2_2_13_p_1">The white space modifier appends a single space to the data value:</p>
> <div id="doc_figure_u.62"></div> <pre>
23621,23622c23669,23670
< </pre> <p id="doc_section_2_2_2_11_p_3">The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier ('{c:}'). It is purely a convenience feature.</p>
< <p id="doc_section_2_2_2_11_p_4">Note that the sense of the 'w' modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it.</p>
---
> </pre> <p id="doc_section_2_2_2_13_p_3">The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier ('{c:}'). It is purely a convenience feature.</p>
> <p id="doc_section_2_2_2_13_p_4">Note that the sense of the 'w' modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it.</p>
23635c23683
< <div id="doc_figure_u.60"></div> <pre>
---
> <div id="doc_figure_u.63"></div> <pre>
23832,23833c23880,23915
< <p id="doc_section_2_2_4_p_2">For example, a function is passed a locale-base name, a hat size, and a time value. The hat size is formatted in a UTF-8 (ASCII) string, and the time value is formatted into a wchar_t string.</p>
< <div id="doc_figure_u.61"></div> <pre>
---
> <p id="doc_section_2_2_4_p_2">libxo will convert these arguments as needed to either UTF-8 (for XML, JSON, and HTML styles) or locale-based strings for display in text style.</p>
> <div id="doc_figure_u.64"></div> <pre>
> xo_emit("Alll strings are utf-8 content {:tag/%ls}",
> L"except for wide strings");
> </pre> <p id="doc_section_2_2_4_p_4">"%S" is equivalent to "%ls".</p>
> <div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
> <thead><tr>
> <th class="left">Format</th>
> <th class="left">Argument Type</th>
> <th class="left">Argument Contents</th>
> </tr></thead>
> <tbody>
> <tr>
> <td>%s</td>
> <td>const char *</td>
> <td>UTF-8 string</td>
> </tr>
> <tr>
> <td>%S</td>
> <td>const char *</td>
> <td>UTF-8 string (alias for '%s')</td>
> </tr>
> <tr>
> <td>%ls</td>
> <td>const wchar_t *</td>
> <td>Wide character UNICODE string</td>
> </tr>
> <tr>
> <td>%hs</td>
> <td>const char *</td>
> <td>locale-based string</td>
> </tr>
> </tbody>
> </table></div>
> <p id="doc_section_2_2_4_p_5">For example, a function is passed a locale-base name, a hat size, and a time value. The hat size is formatted in a UTF-8 (ASCII) string, and the time value is formatted into a wchar_t string.</p>
> <div id="doc_figure_u.65"></div> <pre>
23852,23855c23934,23937
< </pre> <p id="doc_section_2_2_4_p_4">It is important to note that xo_emit will perform the conversion required to make appropriate output. Text style output uses the current locale (as described above), while XML, JSON, and HTML use UTF-8.</p>
< <p id="doc_section_2_2_4_p_5">UTF-8 and locale-encoded strings can use multiple bytes to encode one column of data. The traditional "precision'" (aka "max‑width") value for "%s" printf formatting becomes overloaded since it specifies both the number of bytes that can be safely referenced and the maximum number of columns to emit. xo_emit uses the precision as the former, and adds a third value for specifying the maximum number of columns.</p>
< <p id="doc_section_2_2_4_p_6">In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the location given by 'name' are in used in filling those columns.</p>
< <div id="doc_figure_u.62"></div> <pre>
---
> </pre> <p id="doc_section_2_2_4_p_7">It is important to note that xo_emit will perform the conversion required to make appropriate output. Text style output uses the current locale (as described above), while XML, JSON, and HTML use UTF-8.</p>
> <p id="doc_section_2_2_4_p_8">UTF-8 and locale-encoded strings can use multiple bytes to encode one column of data. The traditional "precision'" (aka "max‑width") value for "%s" printf formatting becomes overloaded since it specifies both the number of bytes that can be safely referenced and the maximum number of columns to emit. xo_emit uses the precision as the former, and adds a third value for specifying the maximum number of columns.</p>
> <p id="doc_section_2_2_4_p_9">In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the location given by 'name' are in used in filling those columns.</p>
> <div id="doc_figure_u.66"></div> <pre>
23865c23947
< <div id="doc_figure_u.63"></div> <pre>
---
> <div id="doc_figure_u.67"></div> <pre>
23886c23968
< <div id="doc_figure_u.64"></div> <pre>
---
> <div id="doc_figure_u.68"></div> <pre>
23933c24015
< <div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
23989a24072,24128
> <a id="retain" href="#retain">Retaining Parsed Format Information</a>
> </h3>
> <p id="doc_section_2_2_11_p_1">libxo can retain the parsed internal information related to the given format string, allowing subsequent xo_emit calls, the retained information is used, avoiding repetitive parsing of the format string.</p>
> <div id="doc_figure_u.69"></div> <pre>
> SYNTAX:
> int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
> EXAMPLE:
> xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
> some, thing, fancy);
> </pre> <p id="doc_section_2_2_11_p_3">To retain parsed format information, use the XOEF_RETAIN flag to the xo_emit_f() function. A complete set of xo_emit_f functions exist to match all the xo_emit function signatures (with handles, varadic argument, and printf-like flags):</p>
> <div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
> <thead><tr>
> <th class="left">Function</th>
> <th class="left">Flags Equivalent</th>
> </tr></thead>
> <tbody>
> <tr>
> <td>xo_emit_hv</td>
> <td>xo_emit_hvf</td>
> </tr>
> <tr>
> <td>xo_emit_h</td>
> <td>xo_emit_hf</td>
> </tr>
> <tr>
> <td>xo_emit</td>
> <td>xo_emit_f</td>
> </tr>
> <tr>
> <td>xo_emit_hvp</td>
> <td>xo_emit_hvfp</td>
> </tr>
> <tr>
> <td>xo_emit_hp</td>
> <td>xo_emit_hfp</td>
> </tr>
> <tr>
> <td>xo_emit_p</td>
> <td>xo_emit_fp</td>
> </tr>
> </tbody>
> </table></div>
> <p id="doc_section_2_2_11_p_4">The format string must be immutable across multiple calls to xo_emit_f(), since the library retains the string. Typically this is done by using static constant strings, such as string literals. If the string is not immutable, the XOEF_RETAIN flag must not be used.</p>
> <p id="doc_section_2_2_11_p_5">The functions xo_retain_clear() and xo_retain_clear_all() release internal information on either a single format string or all format strings, respectively. Neither is required, but the library will retain this information until it is cleared or the process exits.</p>
> <div id="doc_figure_u.70"></div> <pre>
> const char *fmt = "{:name} {:count/%d}\n";
> for (i = 0; i < 1000; i++) {
> xo_open_instance("item");
> xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
> }
> xo_retain_clear(fmt);
> </pre> <p id="doc_section_2_2_11_p_7">The retained information is kept as thread-specific data.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_2_12">
> <div class="self-section-number">
> <a href="#doc_section_2_2_12">2.2.12</a>�</div>
23992,23993c24131,24132
< <p id="doc_section_2_2_11_p_1">In this example, the value for the number of items in stock is emitted:</p>
< <div id="doc_figure_u.65"></div> <pre>
---
> <p id="doc_section_2_2_12_p_1">In this example, the value for the number of items in stock is emitted:</p>
> <div id="doc_figure_u.71"></div> <pre>
23996,23997c24135,24136
< </pre> <p id="doc_section_2_2_11_p_3">This call will generate the following output:</p>
< <div id="doc_figure_u.66"></div> <pre>
---
> </pre> <p id="doc_section_2_2_12_p_3">This call will generate the following output:</p>
> <div id="doc_figure_u.72"></div> <pre>
24012,24013c24151,24152
< </pre> <p id="doc_section_2_2_11_p_5">Clearly HTML wins the verbosity award, and this output does not include XOF_XPATH or XOF_INFO data, which would expand the penultimate line to:</p>
< <div id="doc_figure_u.67"></div> <pre>
---
> </pre> <p id="doc_section_2_2_12_p_5">Clearly HTML wins the verbosity award, and this output does not include XOF_XPATH or XOF_INFO data, which would expand the penultimate line to:</p>
> <div id="doc_figure_u.73"></div> <pre>
24023a24163,24292
> <a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a>
> </h2>
> <p id="doc_section_2_3_p_1">For XML and JSON, individual fields appear inside hierarchies which provide context and meaning to the fields. Unfortunately, these encoding have a basic disconnect between how lists is similar objects are represented.</p>
> <p id="doc_section_2_3_p_2">XML encodes lists as set of sequential elements:</p>
> <div id="doc_figure_u.74"></div> <pre>
> <user>phil</user>
> <user>pallavi</user>
> <user>sjg</user>
> </pre> <p id="doc_section_2_3_p_4">JSON encodes lists using a single name and square brackets:</p>
> <div id="doc_figure_u.75"></div> <pre>
> "user": [ "phil", "pallavi", "sjg" ]
> </pre> <p id="doc_section_2_3_p_6">This means libxo needs three distinct indications of hierarchy: one for containers of hierarchy appear only once for any specific parent, one for lists, and one for each item in a list.</p>
> <p id="doc_section_2_3_p_7">Section Contents: </p>
> <ul>
> <li><a href="#containers" title="Containers">Section�2.3.1</a></li>
> <li><a href="#lists-and-instances" title="Lists and Instances">Section�2.3.2</a></li>
> <li><a href="#dtrt-mode" title="DTRT Mode">Section�2.3.3</a></li>
> <li><a href="#markers" title="Markers">Section�2.3.4</a></li>
> </ul>
> <div class="content">
> <h3 id="doc_section_2_3_1">
> <div class="self-section-number">
> <a href="#doc_section_2_3_1">2.3.1</a>�</div>
> <a id="containers" href="#containers">Containers</a>
> </h3>
> <p id="doc_section_2_3_1_p_1">A "container" is an element of a hierarchy that appears only once under any specific parent. The container has no value, but serves to contain other nodes.</p>
> <p id="doc_section_2_3_1_p_2">To open a container, call xo_open_container() or xo_open_container_h(). The former uses the default handle and the latter accepts a specific handle.</p>
> <div id="doc_figure_u.76"></div> <pre>
> int xo_open_container_h (xo_handle_t *xop, const char *name);
> int xo_open_container (const char *name);
> </pre> <p id="doc_section_2_3_1_p_4">To close a level, use the xo_close_container() or xo_close_container_h() functions:</p>
> <div id="doc_figure_u.77"></div> <pre>
> int xo_close_container_h (xo_handle_t *xop, const char *name);
> int xo_close_container (const char *name);
> </pre> <p id="doc_section_2_3_1_p_6">Each open call must have a matching close call. If the XOF_WARN flag is set and the name given does not match the name of the currently open container, a warning will be generated.</p>
> <div id="doc_figure_u.78"></div> <pre>
> Example:
>
> xo_open_container("top");
> xo_open_container("system");
> xo_emit("{:host-name/%s%s%s", hostname,
> domainname ? "." : "", domainname ?: "");
> xo_close_container("system");
> xo_close_container("top");
>
> Sample Output:
> Text:
> my-host.example.org
> XML:
> <top>
> <system>
> <host-name>my-host.example.org</host-name>
> </system>
> </top>
> JSON:
> "top" : {
> "system" : {
> "host-name": "my-host.example.org"
> }
> }
> HTML:
> <div class="data"
> data-tag="host-name">my-host.example.org</div>
> </pre> </div>
> <div class="content">
> <h3 id="doc_section_2_3_2">
> <div class="self-section-number">
> <a href="#doc_section_2_3_2">2.3.2</a>�</div>
> <a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a>
> </h3>
> <p id="doc_section_2_3_2_p_1">A list is set of one or more instances that appear under the same parent. The instances contain details about a specific object. One can think of instances as objects or records. A call is needed to open and close the list, while a distinct call is needed to open and close each instance of the list:</p>
> <div id="doc_figure_u.79"></div> <pre>
> xo_open_list("item");
>
> for (ip = list; ip->i_title; ip++) {
> xo_open_instance("item");
> xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
> xo_close_instance("item");
> }
>
> xo_close_list("item");
> </pre> <p id="doc_section_2_3_2_p_3">Getting the list and instance calls correct is critical to the proper generation of XML and JSON data.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_3_3">
> <div class="self-section-number">
> <a href="#doc_section_2_3_3">2.3.3</a>�</div>
> <a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a>
> </h3>
> <p id="doc_section_2_3_3_p_1">Some users may find tracking the names of open containers, lists, and instances inconvenient. libxo offers a "Do The Right Thing" mode, where libxo will track the names of open containers, lists, and instances so the close function can be called without a name. To enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output.</p>
> <div id="doc_figure_u.80"></div> <pre>
> xo_set_flags(NULL, XOF_DTRT);
> </pre> <p id="doc_section_2_3_3_p_3">Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance:</p>
> <div id="doc_figure_u.81"></div> <pre>
> xo_open_container("top");
> ...
> xo_close_container_d();
> </pre> <p id="doc_section_2_3_3_p_5">This also works for lists and instances:</p>
> <div id="doc_figure_u.82"></div> <pre>
> xo_open_list("item");
> for (...) {
> xo_open_instance("item");
> xo_emit(...);
> xo_close_instance_d();
> }
> xo_close_list_d();
> </pre> <p id="doc_section_2_3_3_p_7">Note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.</p>
> </div>
> <div class="content">
> <h3 id="doc_section_2_3_4">
> <div class="self-section-number">
> <a href="#doc_section_2_3_4">2.3.4</a>�</div>
> <a id="markers" href="#markers">Markers</a>
> </h3>
> <p id="doc_section_2_3_4_p_1">Markers are used to protect and restore the state of open constructs. While a marker is open, no other open constructs can be closed. When a marker is closed, all constructs open since the marker was opened will be closed.</p>
> <p id="doc_section_2_3_4_p_2">Markers use names which are not user-visible, allowing the caller to choose appropriate internal names.</p>
> <p id="doc_section_2_3_4_p_3">In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish‑guts" is used to ensure that any constructs opened by the function are closed properly.</p>
> <div id="doc_figure_u.83"></div> <pre>
> for (i = 0; fish[i]; i++) {
> xo_open_instance("fish");
> xo_open_marker("fish-guts");
> dump_fish_details(i);
> xo_close_marker("fish-guts");
> }
> </pre> </div>
> </div>
> <div class="content">
> <h2 id="doc_section_2_4">
> <div class="self-section-number">
> <a href="#doc_section_2_4">2.4</a>�</div>
24026,24027c24295,24296
< <p id="doc_section_2_3_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p>
< <p id="doc_section_2_3_p_2"> </p>
---
> <p id="doc_section_2_4_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p>
> <p id="doc_section_2_4_p_2"> </p>
24033,24034c24302,24304
< <p id="doc_section_2_3_p_3">Options is a comma-separated list of tokens that correspond to output styles, flags, or features:</p>
< <div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <p id="doc_section_2_4_p_3">Programs using libxo are expecting to call the xo_parse_args function to parse these arguments. See <a href="#xo_parse_args" title="Parsing Command-line Arguments (xo_parse_args)">Section�3.4.1</a> for details.</p>
> <p id="doc_section_2_4_p_4">Options is a comma-separated list of tokens that correspond to output styles, flags, or features:</p>
> <div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24084a24355,24358
> <td>no-retain</td>
> <td>Prevent retaining formatting information</td>
> </tr>
> <tr>
24096a24371,24374
> <td>retain</td>
> <td>Force retaining formatting information</td>
> </tr>
> <tr>
24126c24404
< <p id="doc_section_2_3_p_4">The brief options are detailed in <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>.</p>
---
> <p id="doc_section_2_4_p_5">The brief options are detailed in <a href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>.</p>
24128,24213d24405
< <div class="content">
< <h2 id="doc_section_2_4">
< <div class="self-section-number">
< <a href="#doc_section_2_4">2.4</a>�</div>
< <a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a>
< </h2>
< <p id="doc_section_2_4_p_1">For XML and JSON, individual fields appear inside hierarchies which provide context and meaning to the fields. Unfortunately, these encoding have a basic disconnect between how lists is similar objects are represented.</p>
< <p id="doc_section_2_4_p_2">XML encodes lists as set of sequential elements:</p>
< <div id="doc_figure_u.68"></div> <pre>
< <user>phil</user>
< <user>pallavi</user>
< <user>sjg</user>
< </pre> <p id="doc_section_2_4_p_4">JSON encodes lists using a single name and square brackets:</p>
< <div id="doc_figure_u.69"></div> <pre>
< "user": [ "phil", "pallavi", "sjg" ]
< </pre> <p id="doc_section_2_4_p_6">This means libxo needs three distinct indications of hierarchy: one for containers of hierarchy appear only once for any specific parent, one for lists, and one for each item in a list.</p>
< <p id="doc_section_2_4_p_7">Section Contents: </p>
< <ul>
< <li><a href="#containers" title="Containers">Section�2.4.1</a></li>
< <li><a href="#lists-and-instances" title="Lists and Instances">Section�2.4.2</a></li>
< <li><a href="#dtrt-mode" title="DTRT Mode">Section�2.4.3</a></li>
< <li><a href="#markers" title="Markers">Section�2.4.4</a></li>
< </ul>
< <div class="content">
< <h3 id="doc_section_2_4_1">
< <div class="self-section-number">
< <a href="#doc_section_2_4_1">2.4.1</a>�</div>
< <a id="containers" href="#containers">Containers</a>
< </h3>
< <p id="doc_section_2_4_1_p_1">A "container" is an element of a hierarchy that appears only once under any specific parent. The container has no value, but serves to contain other nodes.</p>
< <p id="doc_section_2_4_1_p_2">To open a container, call xo_open_container() or xo_open_container_h(). The former uses the default handle and the latter accepts a specific handle.</p>
< <div id="doc_figure_u.70"></div> <pre>
< int xo_open_container_h (xo_handle_t *xop, const char *name);
< int xo_open_container (const char *name);
< </pre> <p id="doc_section_2_4_1_p_4">To close a level, use the xo_close_container() or xo_close_container_h() functions:</p>
< <div id="doc_figure_u.71"></div> <pre>
< int xo_close_container_h (xo_handle_t *xop, const char *name);
< int xo_close_container (const char *name);
< </pre> <p id="doc_section_2_4_1_p_6">Each open call must have a matching close call. If the XOF_WARN flag is set and the name given does not match the name of the currently open container, a warning will be generated.</p>
< <div id="doc_figure_u.72"></div> <pre>
< Example:
<
< xo_open_container("top");
< xo_open_container("system");
< xo_emit("{:host-name/%s%s%s", hostname,
< domainname ? "." : "", domainname ?: "");
< xo_close_container("system");
< xo_close_container("top");
<
< Sample Output:
< Text:
< my-host.example.org
< XML:
< <top>
< <system>
< <host-name>my-host.example.org</host-name>
< </system>
< </top>
< JSON:
< "top" : {
< "system" : {
< "host-name": "my-host.example.org"
< }
< }
< HTML:
< <div class="data"
< data-tag="host-name">my-host.example.org</div>
< </pre> </div>
< <div class="content">
< <h3 id="doc_section_2_4_2">
< <div class="self-section-number">
< <a href="#doc_section_2_4_2">2.4.2</a>�</div>
< <a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a>
< </h3>
< <p id="doc_section_2_4_2_p_1">A list is set of one or more instances that appear under the same parent. The instances contain details about a specific object. One can think of instances as objects or records. A call is needed to open and close the list, while a distinct call is needed to open and close each instance of the list:</p>
< <div id="doc_figure_u.73"></div> <pre>
< xo_open_list("item");
<
< for (ip = list; ip->i_title; ip++) {
< xo_open_instance("item");
< xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
< xo_close_instance("item");
< }
<
< xo_close_list("item");
< </pre> <p id="doc_section_2_4_2_p_3">Getting the list and instance calls correct is critical to the proper generation of XML and JSON data.</p>
24215,24286d24406
< <div class="content">
< <h3 id="doc_section_2_4_3">
< <div class="self-section-number">
< <a href="#doc_section_2_4_3">2.4.3</a>�</div>
< <a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a>
< </h3>
< <p id="doc_section_2_4_3_p_1">Some users may find tracking the names of open containers, lists, and instances inconvenient. libxo offers a "Do The Right Thing" mode, where libxo will track the names of open containers, lists, and instances so the close function can be called without a name. To enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output.</p>
< <div id="doc_figure_u.74"></div> <pre>
< xo_set_flags(NULL, XOF_DTRT);
< </pre> <p id="doc_section_2_4_3_p_3">Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance:</p>
< <div id="doc_figure_u.75"></div> <pre>
< xo_open_container("top");
< ...
< xo_close_container_d();
< </pre> <p id="doc_section_2_4_3_p_5">This also works for lists and instances:</p>
< <div id="doc_figure_u.76"></div> <pre>
< xo_open_list("item");
< for (...) {
< xo_open_instance("item");
< xo_emit(...);
< xo_close_instance_d();
< }
< xo_close_list_d();
< </pre> <p id="doc_section_2_4_3_p_7">Note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.</p>
< </div>
< <div class="content">
< <h3 id="doc_section_2_4_4">
< <div class="self-section-number">
< <a href="#doc_section_2_4_4">2.4.4</a>�</div>
< <a id="markers" href="#markers">Markers</a>
< </h3>
< <p id="doc_section_2_4_4_p_1">Markers are used to protect and restore the state of open constructs. While a marker is open, no other open constructs can be closed. When a marker is closed, all constructs open since the marker was opened will be closed.</p>
< <p id="doc_section_2_4_4_p_2">Markers use names which are not user-visible, allowing the caller to choose appropriate internal names.</p>
< <p id="doc_section_2_4_4_p_3">In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish‑guts" is used to ensure that any constructs opened by the function are closed properly.</p>
< <div id="doc_figure_u.77"></div> <pre>
< for (i = 0; fish[i]; i++) {
< xo_open_instance("fish");
< xo_open_marker("fish-guts");
< dump_fish_details(i);
< xo_close_marker("fish-guts");
< }
< </pre> </div>
< </div>
< <div class="content">
< <h2 id="doc_section_2_5">
< <div class="self-section-number">
< <a href="#doc_section_2_5">2.5</a>�</div>
< <a id="handles" href="#handles">Handles</a>
< </h2>
< <p id="doc_section_2_5_p_1">libxo uses "handles" to control its rendering functionality. The handle contains state and buffered data, as well as callback functions to process data.</p>
< <p id="doc_section_2_5_p_2">A default handle is used when a NULL is passed to functions accepting a handle. This handle is initialized to write its data to stdout using the default style of text (XO_STYLE_TEXT).</p>
< <p id="doc_section_2_5_p_3">For the convenience of callers, the libxo library includes handle-less functions that implicitly use the default handle. Any function that takes a handle will use the default handle is a value of NULL is passed in place of a valid handle.</p>
< <p id="doc_section_2_5_p_4">For example, the following are equivalent:</p>
< <div id="doc_figure_u.78"></div> <pre>
< xo_emit("test");
< xo_emit_h(NULL, "test");
< </pre> <p id="doc_section_2_5_p_6">Handles are created using xo_create() and destroy using xo_destroy().</p>
< </div>
< <div class="content">
< <h2 id="doc_section_2_6">
< <div class="self-section-number">
< <a href="#doc_section_2_6">2.6</a>�</div>
< <a id="utf-8" href="#utf-8">UTF-8</a>
< </h2>
< <p id="doc_section_2_6_p_1">All strings for libxo must be UTF-8. libxo will handle turning them into locale-based strings for display to the user.</p>
< <p id="doc_section_2_6_p_2">The only exception is argument formatted using the "%ls" format, which require a wide character string (wchar_t *) as input. libxo will convert these arguments as needed to either UTF-8 (for XML, JSON, and HTML styles) or locale-based strings for display in text style.</p>
< <div id="doc_figure_u.79"></div> <pre>
< xo_emit("Alll strings are utf-8 content {:tag/%ls}",
< L"except for wide strings");
< </pre> <p id="doc_section_2_6_p_4">"%S" is equivalent to "%ls".</p>
< </div>
< </div>
24297c24417
< <li><a href="#handles-2" title="Handles">Section�3.1</a></li>
---
> <li><a href="#handles" title="Handles">Section�3.1</a></li>
24308c24428
< <a id="handles-2" href="#handles-2">Handles</a>
---
> <a id="handles" href="#handles">Handles</a>
24310,24312c24430,24432
< <p id="doc_section_3_1_p_1">Handles give an abstraction for libxo that encapsulates the state of a stream of output. Handles have the data type "xo_handle_t" and are opaque to the caller.</p>
< <p id="doc_section_3_1_p_2">The library has a default handle that is automatically initialized. By default, this handle will send text style output to standard output. The xo_set_style and xo_set_flags functions can be used to change this behavior.</p>
< <p id="doc_section_3_1_p_3">Many libxo functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed NULL to access the default handle.</p>
---
> <p id="doc_section_3_1_p_1">libxo uses "handles" to control its rendering functionality. The handle contains state and buffered data, as well as callback functions to process data.</p>
> <p id="doc_section_3_1_p_2">Handles give an abstraction for libxo that encapsulates the state of a stream of output. Handles have the data type "xo_handle_t" and are opaque to the caller.</p>
> <p id="doc_section_3_1_p_3">The library has a default handle that is automatically initialized. By default, this handle will send text style output (XO_STYLE_TEXT) to standard output. The xo_set_style and xo_set_flags functions can be used to change this behavior.</p>
24314c24434,24440
< <p id="doc_section_3_1_p_5">Section Contents: </p>
---
> <p id="doc_section_3_1_p_5">Many libxo functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed NULL to access the default handle. For the convenience of callers, the libxo library includes handle-less functions that implicitly use the default handle.</p>
> <p id="doc_section_3_1_p_6">For example, the following are equivalent:</p>
> <div id="doc_figure_u.84"></div> <pre>
> xo_emit("test");
> xo_emit_h(NULL, "test");
> </pre> <p id="doc_section_3_1_p_8">Handles are created using xo_create() and destroy using xo_destroy().</p>
> <p id="doc_section_3_1_p_9">Section Contents: </p>
24330c24456
< <div id="doc_figure_u.80"></div> <pre>
---
> <div id="doc_figure_u.85"></div> <pre>
24346c24472
< <div id="doc_figure_u.81"></div> <pre>
---
> <div id="doc_figure_u.86"></div> <pre>
24358c24484
< <div id="doc_figure_u.82"></div> <pre>
---
> <div id="doc_figure_u.87"></div> <pre>
24371c24497
< <div id="doc_figure_u.83"></div> <pre>
---
> <div id="doc_figure_u.88"></div> <pre>
24374c24500
< <div id="doc_figure_u.84"></div> <pre>
---
> <div id="doc_figure_u.89"></div> <pre>
24388c24514
< <div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24420c24546
< <div id="doc_figure_u.85"></div> <pre>
---
> <div id="doc_figure_u.90"></div> <pre>
24423c24549
< <div id="doc_figure_u.86"></div> <pre>
---
> <div id="doc_figure_u.91"></div> <pre>
24435c24561
< <div id="doc_figure_u.87"></div> <pre>
---
> <div id="doc_figure_u.92"></div> <pre>
24438c24564
< <div id="doc_figure_u.88"></div> <pre>
---
> <div id="doc_figure_u.93"></div> <pre>
24453c24579
< <div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24531c24657
< <div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24550c24676
< <div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24561c24687
< <div id="doc_figure_u.89"></div> <pre>
---
> <div id="doc_figure_u.94"></div> <pre>
24574c24700
< <div id="doc_figure_u.90"></div> <pre>
---
> <div id="doc_figure_u.95"></div> <pre>
24584c24710
< <div id="doc_figure_u.91"></div> <pre>
---
> <div id="doc_figure_u.96"></div> <pre>
24586c24712
< </pre> <p id="doc_section_3_1_5_3_p_3">The options are identical to those listed in <a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a>.</p>
---
> </pre> <p id="doc_section_3_1_5_3_p_3">The options are identical to those listed in <a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a>.</p>
24596c24722
< <div id="doc_figure_u.92"></div> <pre>
---
> <div id="doc_figure_u.97"></div> <pre>
24607c24733
< <div id="doc_figure_u.93"></div> <pre>
---
> <div id="doc_figure_u.98"></div> <pre>
24611c24737
< </pre> <p id="doc_section_3_2_p_3">The "fmt" argument is a string containing field descriptors as specified in <a href="#format-strings" title="Format Strings">Section�2.2</a>. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See <a href="#handles" title="Handles">Section�2.5</a>.</p>
---
> </pre> <p id="doc_section_3_2_p_3">The "fmt" argument is a string containing field descriptors as specified in <a href="#format-strings" title="Format Strings">Section�2.2</a>. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See <a href="#handles" title="Handles">Section�3.1</a>.</p>
24615,24617c24741,24744
< <li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.1</a></li>
< <li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.2</a></li>
< <li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.3</a></li>
---
> <li><a href="#xo_emit_field" title="Single Field Emitting Functions (xo_emit_field)">Section�3.2.1</a></li>
> <li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.2</a></li>
> <li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.3</a></li>
> <li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.4</a></li>
24622a24750,24772
> <a id="xo_emit_field" href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a>
> </h3>
> <p id="doc_section_3_2_1_p_1">The following functions can also make output, but only make a single field at a time:</p>
> <div id="doc_figure_u.99"></div> <pre>
> int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod,
> const char *contents, const char *fmt,
> const char *efmt, va_list vap);
>
> int xo_emit_field_h (xo_handle_t *xop, const char *rolmod,
> const char *contents, const char *fmt,
> const char *efmt, ...);
>
> int xo_emit_field (const char *rolmod, const char *contents,
> const char *fmt, const char *efmt, ...);
> </pre> <p id="doc_section_3_2_1_p_3">These functions are intended to avoid the scenario where one would otherwise need to compose a format descriptors using snprintf(). The individual parts of the format descriptor are passed in distinctly.</p>
> <div id="doc_figure_u.100"></div> <pre>
> xo_emit("T", "Host name is ", NULL, NULL);
> xo_emit("V", "host-name", NULL, NULL, host-name);
> </pre> </div>
> <div class="content">
> <h3 id="doc_section_3_2_2">
> <div class="self-section-number">
> <a href="#doc_section_3_2_2">3.2.2</a>�</div>
24625,24626c24775,24776
< <p id="doc_section_3_2_1_p_1">The xo_attr() function emits attributes for the XML output style.</p>
< <div id="doc_figure_u.94"></div> <pre>
---
> <p id="doc_section_3_2_2_p_1">The xo_attr() function emits attributes for the XML output style.</p>
> <div id="doc_figure_u.101"></div> <pre>
24632,24633c24782,24783
< </pre> <p id="doc_section_3_2_1_p_3">The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().</p>
< <div id="doc_figure_u.95"></div> <pre>
---
> </pre> <p id="doc_section_3_2_2_p_3">The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().</p>
> <div id="doc_figure_u.102"></div> <pre>
24641,24642c24791,24792
< </pre> <p id="doc_section_3_2_1_p_5">xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.</p>
< <p id="doc_section_3_2_1_p_6">Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.</p>
---
> </pre> <p id="doc_section_3_2_2_p_5">xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.</p>
> <p id="doc_section_3_2_2_p_6">Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.</p>
24645c24795
< <h3 id="doc_section_3_2_2">
---
> <h3 id="doc_section_3_2_3">
24647c24797
< <a href="#doc_section_3_2_2">3.2.2</a>�</div>
---
> <a href="#doc_section_3_2_3">3.2.3</a>�</div>
24650,24651c24800,24801
< <p id="doc_section_3_2_2_p_1">libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:</p>
< <div id="doc_figure_u.96"></div> <pre>
---
> <p id="doc_section_3_2_3_p_1">libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:</p>
> <div id="doc_figure_u.103"></div> <pre>
24654c24804
< </pre> <p id="doc_section_3_2_2_p_3">Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".</p>
---
> </pre> <p id="doc_section_3_2_3_p_3">Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".</p>
24657c24807
< <h3 id="doc_section_3_2_3">
---
> <h3 id="doc_section_3_2_4">
24659c24809
< <a href="#doc_section_3_2_3">3.2.3</a>�</div>
---
> <a href="#doc_section_3_2_4">3.2.4</a>�</div>
24662,24663c24812,24813
< <p id="doc_section_3_2_3_p_1">When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.</p>
< <div id="doc_figure_u.97"></div> <pre>
---
> <p id="doc_section_3_2_4_p_1">When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.</p>
> <div id="doc_figure_u.104"></div> <pre>
24667,24668c24817,24818
< </pre> <p id="doc_section_3_2_3_p_3">Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.</p>
< <p id="doc_section_3_2_3_p_4">xo_finish_atexit is suitable for use with atexit(3).</p>
---
> </pre> <p id="doc_section_3_2_4_p_3">Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.</p>
> <p id="doc_section_3_2_4_p_4">xo_finish_atexit is suitable for use with atexit(3).</p>
24679c24829
< <div id="doc_figure_u.98"></div> <pre>
---
> <div id="doc_figure_u.105"></div> <pre>
24693c24843
< <div id="doc_figure_u.99"></div> <pre>
---
> <div id="doc_figure_u.106"></div> <pre>
24710c24860
< <div id="doc_figure_u.100"></div> <pre>
---
> <div id="doc_figure_u.107"></div> <pre>
24779c24929
< <div id="doc_figure_u.101"></div> <pre>
---
> <div id="doc_figure_u.108"></div> <pre>
24783c24933
< </pre> <p id="doc_section_3_4_1_p_3">Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See <a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a> for a description of valid arguments.</p>
---
> </pre> <p id="doc_section_3_4_1_p_3">Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See <a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a> for a description of valid arguments.</p>
24792c24942
< <div id="doc_figure_u.102"></div> <pre>
---
> <div id="doc_figure_u.109"></div> <pre>
24803c24953
< <div id="doc_figure_u.103"></div> <pre>
---
> <div id="doc_figure_u.110"></div> <pre>
24816c24966
< <div id="doc_figure_u.104"></div> <pre>
---
> <div id="doc_figure_u.111"></div> <pre>
24826c24976
< <div id="doc_figure_u.105"></div> <pre>
---
> <div id="doc_figure_u.112"></div> <pre>
24839c24989
< <div id="doc_figure_u.106"></div> <pre>
---
> <div id="doc_figure_u.113"></div> <pre>
24850c25000
< <div id="doc_figure_u.107"></div> <pre>
---
> <div id="doc_figure_u.114"></div> <pre>
24863c25013
< <div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
24932c25082
< <div id="doc_figure_u.108"></div> <pre>
---
> <div id="doc_figure_u.115"></div> <pre>
24935c25085
< <div id="doc_figure_u.109"></div> <pre>
---
> <div id="doc_figure_u.116"></div> <pre>
24946c25096
< <div id="doc_figure_u.110"></div> <pre>
---
> <div id="doc_figure_u.117"></div> <pre>
24962c25112
< <div id="doc_figure_u.111"></div> <pre>
---
> <div id="doc_figure_u.118"></div> <pre>
24974c25124
< <div id="doc_figure_u.112"></div> <pre>
---
> <div id="doc_figure_u.119"></div> <pre>
24989c25139
< <div id="doc_figure_u.113"></div> <pre>
---
> <div id="doc_figure_u.120"></div> <pre>
25005c25155
< <div id="doc_figure_u.114"></div> <pre>
---
> <div id="doc_figure_u.121"></div> <pre>
25033c25183
< <div id="doc_figure_u.115"></div> <pre>
---
> <div id="doc_figure_u.122"></div> <pre>
25039c25189
< <div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25080c25230
< <div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25145c25295
< <div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25178c25328
< <div id="doc_figure_u.116"></div> <pre>
---
> <div id="doc_figure_u.123"></div> <pre>
25207c25357
< <div id="doc_figure_u.117"></div> <pre>
---
> <div id="doc_figure_u.124"></div> <pre>
25223c25373
< <div id="doc_figure_u.118"></div> <pre>
---
> <div id="doc_figure_u.125"></div> <pre>
25234c25384
< <div id="doc_figure_u.119"></div> <pre>
---
> <div id="doc_figure_u.126"></div> <pre>
25245c25395
< <div id="doc_figure_u.120"></div> <pre>
---
> <div id="doc_figure_u.127"></div> <pre>
25260c25410
< <div id="doc_figure_u.121"></div> <pre>
---
> <div id="doc_figure_u.128"></div> <pre>
25302c25452
< <div id="doc_figure_u.122"></div> <pre>
---
> <div id="doc_figure_u.129"></div> <pre>
25314c25464
< <div id="doc_figure_u.123"></div> <pre>
---
> <div id="doc_figure_u.130"></div> <pre>
25332c25482
< <div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25419c25569
< <div id="doc_figure_u.124"></div> <pre>
---
> <div id="doc_figure_u.131"></div> <pre>
25439c25589
< <div id="doc_figure_u.125"></div> <pre>
---
> <div id="doc_figure_u.132"></div> <pre>
25463c25613
< <div id="doc_figure_u.126"></div> <pre>
---
> <div id="doc_figure_u.133"></div> <pre>
25492c25642
< <div id="doc_figure_u.127"></div> <pre>
---
> <div id="doc_figure_u.134"></div> <pre>
25516c25666
< <div id="doc_figure_u.128"></div> <pre>
---
> <div id="doc_figure_u.135"></div> <pre>
25533c25683
< <div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25574c25724
< <div id="doc_figure_u.129"></div> <pre>
---
> <div id="doc_figure_u.136"></div> <pre>
25590c25740
< <div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.21"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25622c25772
< <div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
---
> <div id="doc_table_u.22"><table summary="" class="tt full" cellpadding="3" cellspacing="0">
25642c25792
< <div id="doc_figure_u.130"></div> <pre>
---
> <div id="doc_figure_u.137"></div> <pre>
25690,25692c25840,25842
< <p id="doc_section_8_1_1_p_1">In 2001, we added an XML API to the JUNOS operating system, which is built on top of FreeBSD. Eventually this API became standardized as the NETCONF API (RFC 6241). As part of this effort, we modified many FreeBSD utilities to emit XML, typically via a "‑X" switch. The results were mixed. The cost of maintaining this code, updating it and carrying it were non-trivial, and contributed to our expense (and the associated delay) with upgrading the version of FreeBSD on which each release of JUNOS is based.</p>
< <p id="doc_section_8_1_1_p_2">A recent (2014) effort within JUNOS aims at removing our modifications to the underlying FreeBSD code as a means of reducing the expense and delay. JUNOS is structured to have system components generate XML that is rendered by the CLI (think: login shell) into human-readable text. This allows the API to use the same plumbing as the CLI, and ensures that all components emit XML, and that it is emitted with knowledge of the consumer of that XML, yielding an API that have no incremental cost or feature delay.</p>
< <p id="doc_section_8_1_1_p_3">libxo is an effort to mix the best aspects of the JUNOS strategy into FreeBSD in a seemless way, allowing commands to make printf-like output calls without needing to care how the output is rendered.</p>
---
> <p id="doc_section_8_1_1_p_1">In 2001, we added an XML API to the JUNOS operating system, which is built on top of FreeBSD. Eventually this API became standardized as the NETCONF API (RFC 6241). As part of this effort, we modified many FreeBSD utilities to emit XML, typically via a "‑X" switch. The results were mixed. The cost of maintaining this code, updating it, and carrying it were non-trivial, and contributed to our expense (and the associated delay) with upgrading the version of FreeBSD on which each release of JUNOS is based.</p>
> <p id="doc_section_8_1_1_p_2">A recent (2014) effort within JUNOS aims at removing our modifications to the underlying FreeBSD code as a means of reducing the expense and delay in tracking HEAD. JUNOS is structured to have system components generate XML that is rendered by the CLI (think: login shell) into human-readable text. This allows the API to use the same plumbing as the CLI, and ensures that all components emit XML, and that it is emitted with knowledge of the consumer of that XML, yielding an API that have no incremental cost or feature delay.</p>
> <p id="doc_section_8_1_1_p_3">libxo is an effort to mix the best aspects of the JUNOS strategy into FreeBSD in a seemless way, allowing commands to make printf-like output calls with a single code path.</p>
25701c25851
< <div id="doc_figure_u.131"></div> <pre>
---
> <div id="doc_figure_u.138"></div> <pre>
25780c25930
< <div id="doc_figure_u.132"></div> <pre>
---
> <div id="doc_figure_u.139"></div> <pre>
25792c25942
< <dd>Have empathy for your users, choosing clear and useful fields that contain clear and useful data. You may need to augment the display content with xo_attr() calls (<a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.1</a>) or "{e:}" fields (<a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.3</a>) to make the data useful.</dd>
---
> <dd>Have empathy for your users, choosing clear and useful fields that contain clear and useful data. You may need to augment the display content with xo_attr() calls (<a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.2</a>) or "{e:}" fields (<a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.4</a>) to make the data useful.</dd>
25841c25991
< <div id="doc_figure_u.133"></div> <pre>
---
> <div id="doc_figure_u.140"></div> <pre>
25844c25994
< <div id="doc_figure_u.134"></div> <pre>
---
> <div id="doc_figure_u.141"></div> <pre>
25855c26005
< <div id="doc_figure_u.135"></div> <pre>
---
> <div id="doc_figure_u.142"></div> <pre>
25858c26008
< <div id="doc_figure_u.136"></div> <pre>
---
> <div id="doc_figure_u.143"></div> <pre>
25870c26020
< <div id="doc_figure_u.137"></div> <pre>
---
> <div id="doc_figure_u.144"></div> <pre>
25873c26023
< <div id="doc_figure_u.138"></div> <pre>
---
> <div id="doc_figure_u.145"></div> <pre>
25884c26034
< <div id="doc_figure_u.139"></div> <pre>
---
> <div id="doc_figure_u.146"></div> <pre>
25887c26037
< <div id="doc_figure_u.140"></div> <pre>
---
> <div id="doc_figure_u.147"></div> <pre>
25898c26048
< <div id="doc_figure_u.141"></div> <pre>
---
> <div id="doc_figure_u.148"></div> <pre>
25901c26051
< <div id="doc_figure_u.142"></div> <pre>
---
> <div id="doc_figure_u.149"></div> <pre>
25911c26061
< <div id="doc_figure_u.143"></div> <pre>
---
> <div id="doc_figure_u.150"></div> <pre>
25914c26064
< <div id="doc_figure_u.144"></div> <pre>
---
> <div id="doc_figure_u.151"></div> <pre>
25925c26075
< <div id="doc_figure_u.145"></div> <pre>
---
> <div id="doc_figure_u.152"></div> <pre>
25936c26086
< <div id="doc_figure_u.146"></div> <pre>
---
> <div id="doc_figure_u.153"></div> <pre>
25947c26097
< <div id="doc_figure_u.147"></div> <pre>
---
> <div id="doc_figure_u.154"></div> <pre>
25950c26100
< <div id="doc_figure_u.148"></div> <pre>
---
> <div id="doc_figure_u.155"></div> <pre>
25961c26111
< <div id="doc_figure_u.149"></div> <pre>
---
> <div id="doc_figure_u.156"></div> <pre>
25964c26114
< <div id="doc_figure_u.150"></div> <pre>
---
> <div id="doc_figure_u.157"></div> <pre>
25975c26125
< <div id="doc_figure_u.151"></div> <pre>
---
> <div id="doc_figure_u.158"></div> <pre>
25978c26128
< <div id="doc_figure_u.152"></div> <pre>
---
> <div id="doc_figure_u.159"></div> <pre>
25989c26139
< <div id="doc_figure_u.153"></div> <pre>
---
> <div id="doc_figure_u.160"></div> <pre>
25992c26142
< <div id="doc_figure_u.154"></div> <pre>
---
> <div id="doc_figure_u.161"></div> <pre>
26003c26153
< <div id="doc_figure_u.155"></div> <pre>
---
> <div id="doc_figure_u.162"></div> <pre>
26006c26156
< <div id="doc_figure_u.156"></div> <pre>
---
> <div id="doc_figure_u.163"></div> <pre>
26017c26167
< <div id="doc_figure_u.157"></div> <pre>
---
> <div id="doc_figure_u.164"></div> <pre>
26020c26170
< <div id="doc_figure_u.158"></div> <pre>
---
> <div id="doc_figure_u.165"></div> <pre>
26031c26181
< <div id="doc_figure_u.159"></div> <pre>
---
> <div id="doc_figure_u.166"></div> <pre>
26034c26184
< <div id="doc_figure_u.160"></div> <pre>
---
> <div id="doc_figure_u.167"></div> <pre>
26045c26195
< <div id="doc_figure_u.161"></div> <pre>
---
> <div id="doc_figure_u.168"></div> <pre>
26048c26198
< <div id="doc_figure_u.162"></div> <pre>
---
> <div id="doc_figure_u.169"></div> <pre>
26059c26209
< <div id="doc_figure_u.163"></div> <pre>
---
> <div id="doc_figure_u.170"></div> <pre>
26062c26212
< <div id="doc_figure_u.164"></div> <pre>
---
> <div id="doc_figure_u.171"></div> <pre>
26073c26223
< <div id="doc_figure_u.165"></div> <pre>
---
> <div id="doc_figure_u.172"></div> <pre>
26076c26226
< <div id="doc_figure_u.166"></div> <pre>
---
> <div id="doc_figure_u.173"></div> <pre>
26087c26237
< <div id="doc_figure_u.167"></div> <pre>
---
> <div id="doc_figure_u.174"></div> <pre>
26090c26240
< <div id="doc_figure_u.168"></div> <pre>
---
> <div id="doc_figure_u.175"></div> <pre>
26101c26251
< <div id="doc_figure_u.169"></div> <pre>
---
> <div id="doc_figure_u.176"></div> <pre>
26104c26254
< <div id="doc_figure_u.170"></div> <pre>
---
> <div id="doc_figure_u.177"></div> <pre>
26115c26265
< <div id="doc_figure_u.171"></div> <pre>
---
> <div id="doc_figure_u.178"></div> <pre>
26118c26268
< <div id="doc_figure_u.172"></div> <pre>
---
> <div id="doc_figure_u.179"></div> <pre>
26129c26279
< <div id="doc_figure_u.173"></div> <pre>
---
> <div id="doc_figure_u.180"></div> <pre>
26132c26282
< <div id="doc_figure_u.174"></div> <pre>
---
> <div id="doc_figure_u.181"></div> <pre>
26143c26293
< <div id="doc_figure_u.175"></div> <pre>
---
> <div id="doc_figure_u.182"></div> <pre>
26146c26296
< <div id="doc_figure_u.176"></div> <pre>
---
> <div id="doc_figure_u.183"></div> <pre>
26186c26336
< <div id="doc_figure_u.177"></div> <pre>
---
> <div id="doc_figure_u.184"></div> <pre>
26195c26345
< <div id="doc_figure_u.178"></div> <pre>
---
> <div id="doc_figure_u.185"></div> <pre>
26215c26365
< <div id="doc_figure_u.179"></div> <pre>
---
> <div id="doc_figure_u.186"></div> <pre>
26239c26389
< <div id="doc_figure_u.180"></div> <pre>
---
> <div id="doc_figure_u.187"></div> <pre>
26242c26392
< <div id="doc_figure_u.181"></div> <pre>
---
> <div id="doc_figure_u.188"></div> <pre>
26250,26251c26400,26401
< </pre> <p id="doc_section_9_3_1_p_5">At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (<a href="#handles" title="Handles">Section�2.5</a>). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.</p>
< <div id="doc_figure_u.182"></div> <pre>
---
> </pre> <p id="doc_section_9_3_1_p_5">At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (<a href="#handles" title="Handles">Section�3.1</a>). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.</p>
> <div id="doc_figure_u.189"></div> <pre>
26261c26411
< <div id="doc_figure_u.183"></div> <pre>
---
> <div id="doc_figure_u.190"></div> <pre>
26267c26417
< <div id="doc_figure_u.184"></div> <pre>
---
> <div id="doc_figure_u.191"></div> <pre>
26271c26421
< <div id="doc_figure_u.185"></div> <pre>
---
> <div id="doc_figure_u.192"></div> <pre>
26274c26424
< <div id="doc_figure_u.186"></div> <pre>
---
> <div id="doc_figure_u.193"></div> <pre>
26288c26438
< <div id="doc_figure_u.187"></div> <pre>
---
> <div id="doc_figure_u.194"></div> <pre>
26306c26456
< <div id="doc_figure_u.188"></div> <pre>
---
> <div id="doc_figure_u.195"></div> <pre>
26325c26475
< <div id="doc_figure_u.189"></div> <pre>
---
> <div id="doc_figure_u.196"></div> <pre>
26343c26493
< <div id="doc_figure_u.190"></div> <pre>
---
> <div id="doc_figure_u.197"></div> <pre>
26348c26498
< <div id="doc_figure_u.191"></div> <pre>
---
> <div id="doc_figure_u.198"></div> <pre>
26381c26531
< <div id="doc_figure_u.192"></div> <pre>
---
> <div id="doc_figure_u.199"></div> <pre>
26399c26549
< <div id="doc_figure_u.193"></div> <pre>
---
> <div id="doc_figure_u.200"></div> <pre>
26407c26557
< <div id="doc_figure_u.194"></div> <pre>
---
> <div id="doc_figure_u.201"></div> <pre>
26410c26560
< <div id="doc_figure_u.195"></div> <pre>
---
> <div id="doc_figure_u.202"></div> <pre>
26417c26567
< <div id="doc_figure_u.196"></div> <pre>
---
> <div id="doc_figure_u.203"></div> <pre>
26442c26592
< <div id="doc_figure_u.197"></div> <pre>
---
> <div id="doc_figure_u.204"></div> <pre>
26535c26685
< <div id="doc_figure_u.198"></div> <pre>
---
> <div id="doc_figure_u.205"></div> <pre>
26568c26718
< <div id="doc_figure_u.199"></div> <pre>
---
> <div id="doc_figure_u.206"></div> <pre>
26623c26773
< <div id="doc_figure_u.200"></div> <pre>
---
> <div id="doc_figure_u.207"></div> <pre>
26674c26824
< <div id="doc_figure_u.201"></div> <pre>
---
> <div id="doc_figure_u.208"></div> <pre>
26869c27019
< <div id="doc_figure_u.202"></div> <pre>
---
> <div id="doc_figure_u.209"></div> <pre>