| libxo-manual.html (298067) | libxo-manual.html (298083) |
|---|---|
| 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 2<html lang="en"> 3<head profile="http://www.w3.org/2006/03/hcard"> 4<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<title>libxo: The Easy Way to Generate text, XML, JSON, and HTML output</title> 6<style type="text/css">/* 7 * $Id$ 8 * --- 501 unchanged lines hidden (view full) --- 510} 511 512@page { 513 @top-left { 514 content: ""; 515 516 } 517 @top-right { | 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 2<html lang="en"> 3<head profile="http://www.w3.org/2006/03/hcard"> 4<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<title>libxo: The Easy Way to Generate text, XML, JSON, and HTML output</title> 6<style type="text/css">/* 7 * $Id$ 8 * --- 501 unchanged lines hidden (view full) --- 510} 511 512@page { 513 @top-left { 514 content: ""; 515 516 } 517 @top-right { |
| 518 content: "December 2015"; | 518 content: "April 2016"; |
| 519 520 } 521 @top-center { 522 content: "LIBXO-MANUAL"; 523 524 } 525 @bottom-left { 526 content: "Shafer"; --- 21477 unchanged lines hidden (view full) --- 22004<td class="header right">P. Shafer</td> 22005</tr> 22006<tr> 22007<td class="header left"></td> 22008<td class="header right">Juniper Networks</td> 22009</tr> 22010<tr> 22011<td class="header left"></td> | 519 520 } 521 @top-center { 522 content: "LIBXO-MANUAL"; 523 524 } 525 @bottom-left { 526 content: "Shafer"; --- 21477 unchanged lines hidden (view full) --- 22004<td class="header right">P. Shafer</td> 22005</tr> 22006<tr> 22007<td class="header left"></td> 22008<td class="header right">Juniper Networks</td> 22009</tr> 22010<tr> 22011<td class="header left"></td> |
| 22012<td class="header right">December 30, 2015</td> | 22012<td class="header right">April 15, 2016</td> |
| 22013</tr> 22014</table></div> 22015<p id="title" class="title">libxo: The Easy Way to Generate text, XML, JSON, and HTML output<br><span class="filename">libxo-manual</span></p> 22016<div id="toc"> 22017<h1 class="np" id="doc.toc"><a href="#doc.toc">Table of Contents</a></h1> 22018<ul class="toc"> 22019<li class="tocline0"> 22020<div class="section-number" id="toc_doc_section_1">1���</div> --- 104 unchanged lines hidden (view full) --- 22125</li> 22126</ul> 22127</li> 22128<li class="tocline1"> 22129<div class="section-number" id="toc_doc_section_2_2_2">2.2.2���</div> 22130<a href="#field-modifiers">Field Modifiers</a><ul class="toc"> 22131<li class="tocline1"> 22132<div class="section-number" id="toc_doc_section_2_2_2_1">2.2.2.1���</div> | 22013</tr> 22014</table></div> 22015<p id="title" class="title">libxo: The Easy Way to Generate text, XML, JSON, and HTML output<br><span class="filename">libxo-manual</span></p> 22016<div id="toc"> 22017<h1 class="np" id="doc.toc"><a href="#doc.toc">Table of Contents</a></h1> 22018<ul class="toc"> 22019<li class="tocline0"> 22020<div class="section-number" id="toc_doc_section_1">1���</div> --- 104 unchanged lines hidden (view full) --- 22125</li> 22126</ul> 22127</li> 22128<li class="tocline1"> 22129<div class="section-number" id="toc_doc_section_2_2_2">2.2.2���</div> 22130<a href="#field-modifiers">Field Modifiers</a><ul class="toc"> 22131<li class="tocline1"> 22132<div class="section-number" id="toc_doc_section_2_2_2_1">2.2.2.1���</div> |
| 22133<a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a> | 22133<a href="#the-argument-modifier-a">The Argument Modifier ({a:})</a> |
| 22134</li> 22135<li class="tocline1"> 22136<div class="section-number" id="toc_doc_section_2_2_2_2">2.2.2.2���</div> | 22134</li> 22135<li class="tocline1"> 22136<div class="section-number" id="toc_doc_section_2_2_2_2">2.2.2.2���</div> |
| 22137<a href="#the-display-modifier-d">The Display Modifier ({d:})</a> | 22137<a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a> |
| 22138</li> 22139<li class="tocline1"> 22140<div class="section-number" id="toc_doc_section_2_2_2_3">2.2.2.3���</div> | 22138</li> 22139<li class="tocline1"> 22140<div class="section-number" id="toc_doc_section_2_2_2_3">2.2.2.3���</div> |
| 22141<a href="#e-modifier">The Encoding Modifier ({e:})</a> | 22141<a href="#the-display-modifier-d">The Display Modifier ({d:})</a> |
| 22142</li> 22143<li class="tocline1"> 22144<div class="section-number" id="toc_doc_section_2_2_2_4">2.2.2.4���</div> | 22142</li> 22143<li class="tocline1"> 22144<div class="section-number" id="toc_doc_section_2_2_2_4">2.2.2.4���</div> |
| 22145<a href="#gettext-modifier">The Gettext Modifier ({g:})</a> | 22145<a href="#e-modifier">The Encoding Modifier ({e:})</a> |
| 22146</li> 22147<li class="tocline1"> 22148<div class="section-number" id="toc_doc_section_2_2_2_5">2.2.2.5���</div> | 22146</li> 22147<li class="tocline1"> 22148<div class="section-number" id="toc_doc_section_2_2_2_5">2.2.2.5���</div> |
| 22149<a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a> | 22149<a href="#gettext-modifier">The Gettext Modifier ({g:})</a> |
| 22150</li> 22151<li class="tocline1"> 22152<div class="section-number" id="toc_doc_section_2_2_2_6">2.2.2.6���</div> | 22150</li> 22151<li class="tocline1"> 22152<div class="section-number" id="toc_doc_section_2_2_2_6">2.2.2.6���</div> |
| 22153<a href="#the-key-modifier-k">The Key Modifier ({k:})</a> | 22153<a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a> |
| 22154</li> 22155<li class="tocline1"> 22156<div class="section-number" id="toc_doc_section_2_2_2_7">2.2.2.7���</div> | 22154</li> 22155<li class="tocline1"> 22156<div class="section-number" id="toc_doc_section_2_2_2_7">2.2.2.7���</div> |
| 22157<a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a> | 22157<a href="#the-key-modifier-k">The Key Modifier ({k:})</a> |
| 22158</li> 22159<li class="tocline1"> 22160<div class="section-number" id="toc_doc_section_2_2_2_8">2.2.2.8���</div> | 22158</li> 22159<li class="tocline1"> 22160<div class="section-number" id="toc_doc_section_2_2_2_8">2.2.2.8���</div> |
| 22161<a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a> | 22161<a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a> |
| 22162</li> 22163<li class="tocline1"> 22164<div class="section-number" id="toc_doc_section_2_2_2_9">2.2.2.9���</div> | 22162</li> 22163<li class="tocline1"> 22164<div class="section-number" id="toc_doc_section_2_2_2_9">2.2.2.9���</div> |
| 22165<a href="#plural-modifier">The Plural Modifier ({p:})</a> | 22165<a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a> |
| 22166</li> 22167<li class="tocline1"> 22168<div class="section-number" id="toc_doc_section_2_2_2_10">2.2.2.10���</div> | 22166</li> 22167<li class="tocline1"> 22168<div class="section-number" id="toc_doc_section_2_2_2_10">2.2.2.10���</div> |
| 22169<a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a> | 22169<a href="#plural-modifier">The Plural Modifier ({p:})</a> |
| 22170</li> 22171<li class="tocline1"> 22172<div class="section-number" id="toc_doc_section_2_2_2_11">2.2.2.11���</div> | 22170</li> 22171<li class="tocline1"> 22172<div class="section-number" id="toc_doc_section_2_2_2_11">2.2.2.11���</div> |
| 22173<a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a> 22174</li> 22175<li class="tocline1"> 22176<div class="section-number" id="toc_doc_section_2_2_2_12">2.2.2.12���</div> 22177<a href="#the-trim-modifier-t">The Trim Modifier ({t:})</a> 22178</li> 22179<li class="tocline1"> 22180<div class="section-number" id="toc_doc_section_2_2_2_13">2.2.2.13���</div> |
|
| 22173<a href="#the-white-space-modifier-w">The White Space Modifier ({w:})</a> 22174</li> 22175</ul> 22176</li> 22177<li class="tocline1"> 22178<div class="section-number" id="toc_doc_section_2_2_3">2.2.3���</div> 22179<a href="#field-formatting">Field Formatting</a> 22180</li> --- 22 unchanged lines hidden (view full) --- 22203<a href="#content-strings">Content Strings</a> 22204</li> 22205<li class="tocline1"> 22206<div class="section-number" id="toc_doc_section_2_2_10">2.2.10���</div> 22207<a href="#printf-like">Argument Validation</a> 22208</li> 22209<li class="tocline1"> 22210<div class="section-number" id="toc_doc_section_2_2_11">2.2.11���</div> | 22181<a href="#the-white-space-modifier-w">The White Space Modifier ({w:})</a> 22182</li> 22183</ul> 22184</li> 22185<li class="tocline1"> 22186<div class="section-number" id="toc_doc_section_2_2_3">2.2.3���</div> 22187<a href="#field-formatting">Field Formatting</a> 22188</li> --- 22 unchanged lines hidden (view full) --- 22211<a href="#content-strings">Content Strings</a> 22212</li> 22213<li class="tocline1"> 22214<div class="section-number" id="toc_doc_section_2_2_10">2.2.10���</div> 22215<a href="#printf-like">Argument Validation</a> 22216</li> 22217<li class="tocline1"> 22218<div class="section-number" id="toc_doc_section_2_2_11">2.2.11���</div> |
| 22219<a href="#retain">Retaining Parsed Format Information</a> 22220</li> 22221<li class="tocline1"> 22222<div class="section-number" id="toc_doc_section_2_2_12">2.2.12���</div> |
|
| 22211<a href="#example">Example</a> 22212</li> 22213</ul> 22214</li> 22215<li class="tocline1"> 22216<div class="section-number" id="toc_doc_section_2_3">2.3���</div> | 22223<a href="#example">Example</a> 22224</li> 22225</ul> 22226</li> 22227<li class="tocline1"> 22228<div class="section-number" id="toc_doc_section_2_3">2.3���</div> |
| 22217<a href="#command-line-arguments">Command-line Arguments</a> 22218</li> 22219<li class="tocline1"> 22220<div class="section-number" id="toc_doc_section_2_4">2.4���</div> | |
| 22221<a href="#representing-hierarchy">Representing Hierarchy</a><ul class="toc"> 22222<li class="tocline1"> | 22229<a href="#representing-hierarchy">Representing Hierarchy</a><ul class="toc"> 22230<li class="tocline1"> |
| 22223<div class="section-number" id="toc_doc_section_2_4_1">2.4.1���</div> | 22231<div class="section-number" id="toc_doc_section_2_3_1">2.3.1���</div> |
| 22224<a href="#containers">Containers</a> 22225</li> 22226<li class="tocline1"> | 22232<a href="#containers">Containers</a> 22233</li> 22234<li class="tocline1"> |
| 22227<div class="section-number" id="toc_doc_section_2_4_2">2.4.2���</div> | 22235<div class="section-number" id="toc_doc_section_2_3_2">2.3.2���</div> |
| 22228<a href="#lists-and-instances">Lists and Instances</a> 22229</li> 22230<li class="tocline1"> | 22236<a href="#lists-and-instances">Lists and Instances</a> 22237</li> 22238<li class="tocline1"> |
| 22231<div class="section-number" id="toc_doc_section_2_4_3">2.4.3���</div> | 22239<div class="section-number" id="toc_doc_section_2_3_3">2.3.3���</div> |
| 22232<a href="#dtrt-mode">DTRT Mode</a> 22233</li> 22234<li class="tocline1"> | 22240<a href="#dtrt-mode">DTRT Mode</a> 22241</li> 22242<li class="tocline1"> |
| 22235<div class="section-number" id="toc_doc_section_2_4_4">2.4.4���</div> | 22243<div class="section-number" id="toc_doc_section_2_3_4">2.3.4���</div> |
| 22236<a href="#markers">Markers</a> 22237</li> 22238</ul> 22239</li> 22240<li class="tocline1"> | 22244<a href="#markers">Markers</a> 22245</li> 22246</ul> 22247</li> 22248<li class="tocline1"> |
| 22241<div class="section-number" id="toc_doc_section_2_5">2.5���</div> 22242<a href="#handles">Handles</a> | 22249<div class="section-number" id="toc_doc_section_2_4">2.4���</div> 22250<a href="#command-line-arguments">Command-line Arguments</a> |
| 22243</li> | 22251</li> |
| 22244<li class="tocline1"> 22245<div class="section-number" id="toc_doc_section_2_6">2.6���</div> 22246<a href="#utf-8">UTF-8</a> 22247</li> | |
| 22248</ul> 22249</li> 22250<li class="tocline0"> 22251<div class="section-number" id="toc_doc_section_3">3���</div> 22252<a href="#the-libxo-api">The libxo API</a><ul class="toc top-toc"> 22253<li class="tocline1"> 22254<div class="section-number" id="toc_doc_section_3_1">3.1���</div> | 22252</ul> 22253</li> 22254<li class="tocline0"> 22255<div class="section-number" id="toc_doc_section_3">3���</div> 22256<a href="#the-libxo-api">The libxo API</a><ul class="toc top-toc"> 22257<li class="tocline1"> 22258<div class="section-number" id="toc_doc_section_3_1">3.1���</div> |
| 22255<a href="#handles-2">Handles</a><ul class="toc"> | 22259Handles |
| 22256<li class="tocline1"> 22257<div class="section-number" id="toc_doc_section_3_1_1">3.1.1���</div> 22258<a href="#xo_create">xo_create</a> 22259</li> 22260<li class="tocline1"> 22261<div class="section-number" id="toc_doc_section_3_1_2">3.1.2���</div> 22262<a href="#xo_create_to_file">xo_create_to_file</a> 22263</li> --- 37 unchanged lines hidden (view full) --- 22301</li> 22302</ul> 22303</li> 22304<li class="tocline1"> 22305<div class="section-number" id="toc_doc_section_3_2">3.2���</div> 22306<a href="#emitting-content-xo_emit">Emitting Content (xo_emit)</a><ul class="toc"> 22307<li class="tocline1"> 22308<div class="section-number" id="toc_doc_section_3_2_1">3.2.1���</div> | 22260<li class="tocline1"> 22261<div class="section-number" id="toc_doc_section_3_1_1">3.1.1���</div> 22262<a href="#xo_create">xo_create</a> 22263</li> 22264<li class="tocline1"> 22265<div class="section-number" id="toc_doc_section_3_1_2">3.1.2���</div> 22266<a href="#xo_create_to_file">xo_create_to_file</a> 22267</li> --- 37 unchanged lines hidden (view full) --- 22305</li> 22306</ul> 22307</li> 22308<li class="tocline1"> 22309<div class="section-number" id="toc_doc_section_3_2">3.2���</div> 22310<a href="#emitting-content-xo_emit">Emitting Content (xo_emit)</a><ul class="toc"> 22311<li class="tocline1"> 22312<div class="section-number" id="toc_doc_section_3_2_1">3.2.1���</div> |
| 22309<a href="#xo_attr">Attributes (xo_attr)</a> | 22313<a href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a> |
| 22310</li> 22311<li class="tocline1"> 22312<div class="section-number" id="toc_doc_section_3_2_2">3.2.2���</div> | 22314</li> 22315<li class="tocline1"> 22316<div class="section-number" id="toc_doc_section_3_2_2">3.2.2���</div> |
| 22313<a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a> | 22317<a href="#xo_attr">Attributes (xo_attr)</a> |
| 22314</li> 22315<li class="tocline1"> 22316<div class="section-number" id="toc_doc_section_3_2_3">3.2.3���</div> | 22318</li> 22319<li class="tocline1"> 22320<div class="section-number" id="toc_doc_section_3_2_3">3.2.3���</div> |
| 22321<a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a> 22322</li> 22323<li class="tocline1"> 22324<div class="section-number" id="toc_doc_section_3_2_4">3.2.4���</div> |
|
| 22317<a href="#finishing-output-xo_finish">Finishing Output (xo_finish)</a> 22318</li> 22319</ul> 22320</li> 22321<li class="tocline1"> 22322<div class="section-number" id="toc_doc_section_3_3">3.3���</div> 22323<a href="#emitting-hierarchy">Emitting Hierarchy</a><ul class="toc"><li class="tocline1"> 22324<div class="section-number" id="toc_doc_section_3_3_1">3.3.1���</div> --- 521 unchanged lines hidden (view full) --- 22846 <div class="data" data-tag="domain" 22847 data-xpath="/top/domain">example.com</div> 22848 <div class="text">...</div> 22849 </div> 22850 </pre> <p id="doc_section_2_p_7">Section Contents: </p> 22851<ul> 22852<li><a href="#encoding-styles" title="Encoding Styles">Section�2.1</a></li> 22853<li><a href="#format-strings" title="Format Strings">Section�2.2</a></li> | 22325<a href="#finishing-output-xo_finish">Finishing Output (xo_finish)</a> 22326</li> 22327</ul> 22328</li> 22329<li class="tocline1"> 22330<div class="section-number" id="toc_doc_section_3_3">3.3���</div> 22331<a href="#emitting-hierarchy">Emitting Hierarchy</a><ul class="toc"><li class="tocline1"> 22332<div class="section-number" id="toc_doc_section_3_3_1">3.3.1���</div> --- 521 unchanged lines hidden (view full) --- 22854 <div class="data" data-tag="domain" 22855 data-xpath="/top/domain">example.com</div> 22856 <div class="text">...</div> 22857 </div> 22858 </pre> <p id="doc_section_2_p_7">Section Contents: </p> 22859<ul> 22860<li><a href="#encoding-styles" title="Encoding Styles">Section�2.1</a></li> 22861<li><a href="#format-strings" title="Format Strings">Section�2.2</a></li> |
| 22854<li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.3</a></li> 22855<li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.4</a></li> 22856<li><a href="#handles" title="Handles">Section�2.5</a></li> 22857<li><a href="#utf-8" title="UTF-8">Section�2.6</a></li> | 22862<li><a href="#representing-hierarchy" title="Representing Hierarchy">Section�2.3</a></li> 22863<li><a href="#command-line-arguments" title="Command-line Arguments">Section�2.4</a></li> |
| 22858</ul> 22859<div class="content"> 22860<h2 id="doc_section_2_1"> 22861<div class="self-section-number"> 22862<a href="#doc_section_2_1">2.1</a>�</div> 22863<a id="encoding-styles" href="#encoding-styles">Encoding Styles</a> 22864</h2> 22865<p id="doc_section_2_1_p_1">There are four encoding styles supported by libxo:</p> --- 121 unchanged lines hidden (view full) --- 22987<li><a href="#field-formatting" title="Field Formatting">Section�2.2.3</a></li> 22988<li><a href="#utf-8-and-locale-strings" title="UTF-8 and Locale Strings">Section�2.2.4</a></li> 22989<li><a href="#characters-outside-of-field-definitions" title="Characters Outside of Field Definitions">Section�2.2.5</a></li> 22990<li><a href="#m-is-supported" title='"%m" Is Supported'>Section�2.2.6</a></li> 22991<li><a href="#n-is-not-supported" title='"%n" Is Not Supported'>Section�2.2.7</a></li> 22992<li><a href="#the-encoding-format-eformat" title="The Encoding Format (eformat)">Section�2.2.8</a></li> 22993<li><a href="#content-strings" title="Content Strings">Section�2.2.9</a></li> 22994<li><a href="#printf-like" title="Argument Validation">Section�2.2.10</a></li> | 22864</ul> 22865<div class="content"> 22866<h2 id="doc_section_2_1"> 22867<div class="self-section-number"> 22868<a href="#doc_section_2_1">2.1</a>�</div> 22869<a id="encoding-styles" href="#encoding-styles">Encoding Styles</a> 22870</h2> 22871<p id="doc_section_2_1_p_1">There are four encoding styles supported by libxo:</p> --- 121 unchanged lines hidden (view full) --- 22993<li><a href="#field-formatting" title="Field Formatting">Section�2.2.3</a></li> 22994<li><a href="#utf-8-and-locale-strings" title="UTF-8 and Locale Strings">Section�2.2.4</a></li> 22995<li><a href="#characters-outside-of-field-definitions" title="Characters Outside of Field Definitions">Section�2.2.5</a></li> 22996<li><a href="#m-is-supported" title='"%m" Is Supported'>Section�2.2.6</a></li> 22997<li><a href="#n-is-not-supported" title='"%n" Is Not Supported'>Section�2.2.7</a></li> 22998<li><a href="#the-encoding-format-eformat" title="The Encoding Format (eformat)">Section�2.2.8</a></li> 22999<li><a href="#content-strings" title="Content Strings">Section�2.2.9</a></li> 23000<li><a href="#printf-like" title="Argument Validation">Section�2.2.10</a></li> |
| 22995<li><a href="#example" title="Example">Section�2.2.11</a></li> | 23001<li><a href="#retain" title="Retaining Parsed Format Information">Section�2.2.11</a></li> 23002<li><a href="#example" title="Example">Section�2.2.12</a></li> |
| 22996</ul> 22997<div class="content"> 22998<h3 id="doc_section_2_2_1"> 22999<div class="self-section-number"> 23000<a href="#doc_section_2_2_1">2.2.1</a>�</div> 23001<a id="field-roles" href="#field-roles">Field Roles</a> 23002</h3> 23003<p id="doc_section_2_2_1_p_1">Field roles are optional, and indicate the role and formatting of the content. The roles are listed below; only one role is permitted:</p> --- 347 unchanged lines hidden (view full) --- 23351<div id="doc_table_u.4"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> 23352<thead><tr> 23353<th class="left">M</th> 23354<th class="left">Name</th> 23355<th class="left">Description</th> 23356</tr></thead> 23357<tbody> 23358<tr> | 23003</ul> 23004<div class="content"> 23005<h3 id="doc_section_2_2_1"> 23006<div class="self-section-number"> 23007<a href="#doc_section_2_2_1">2.2.1</a>�</div> 23008<a id="field-roles" href="#field-roles">Field Roles</a> 23009</h3> 23010<p id="doc_section_2_2_1_p_1">Field roles are optional, and indicate the role and formatting of the content. The roles are listed below; only one role is permitted:</p> --- 347 unchanged lines hidden (view full) --- 23358<div id="doc_table_u.4"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> 23359<thead><tr> 23360<th class="left">M</th> 23361<th class="left">Name</th> 23362<th class="left">Description</th> 23363</tr></thead> 23364<tbody> 23365<tr> |
| 23366<td>a</td> 23367<td>argument</td> 23368<td>The content appears as a 'const char *' argument</td> 23369</tr> 23370<tr> |
|
| 23359<td>c</td> 23360<td>colon</td> 23361<td>A colon (":") is appended after the label</td> 23362</tr> 23363<tr> 23364<td>d</td> 23365<td>display</td> 23366<td>Only emit field for display styles (text/HTML)</td> --- 63 unchanged lines hidden (view full) --- 23430<td>white</td> 23431<td>A blank (" ") is appended after the label</td> 23432</tr> 23433</tbody> 23434</table></div> 23435<p id="doc_section_2_2_2_p_2">Roles and modifiers can also use more verbose names, when preceeded by a comma. For example, the modifier string "Lwc" (or "L,white,colon") means the field has a label role (text that describes the next field) and should be followed by a colon ('c') and a space ('w'). The modifier string "Vkq" (or ":key,quote") means the field has a value role (the default role), that it is a key for the current instance, and that the value should be quoted when encoded for JSON.</p> 23436<p id="doc_section_2_2_2_p_3">Section Contents: </p> 23437<ul> | 23371<td>c</td> 23372<td>colon</td> 23373<td>A colon (":") is appended after the label</td> 23374</tr> 23375<tr> 23376<td>d</td> 23377<td>display</td> 23378<td>Only emit field for display styles (text/HTML)</td> --- 63 unchanged lines hidden (view full) --- 23442<td>white</td> 23443<td>A blank (" ") is appended after the label</td> 23444</tr> 23445</tbody> 23446</table></div> 23447<p id="doc_section_2_2_2_p_2">Roles and modifiers can also use more verbose names, when preceeded by a comma. For example, the modifier string "Lwc" (or "L,white,colon") means the field has a label role (text that describes the next field) and should be followed by a colon ('c') and a space ('w'). The modifier string "Vkq" (or ":key,quote") means the field has a value role (the default role), that it is a key for the current instance, and that the value should be quoted when encoded for JSON.</p> 23448<p id="doc_section_2_2_2_p_3">Section Contents: </p> 23449<ul> |
| 23438<li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.1</a></li> 23439<li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.2</a></li> 23440<li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.3</a></li> 23441<li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.4</a></li> 23442<li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.5</a></li> 23443<li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.6</a></li> 23444<li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.7</a></li> 23445<li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.8</a></li> 23446<li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.9</a></li> 23447<li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.10</a></li> 23448<li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.11</a></li> | 23450<li><a href="#the-argument-modifier-a" title="The Argument Modifier ({a:})">Section�2.2.2.1</a></li> 23451<li><a href="#the-colon-modifier-c" title="The Colon Modifier ({c:})">Section�2.2.2.2</a></li> 23452<li><a href="#the-display-modifier-d" title="The Display Modifier ({d:})">Section�2.2.2.3</a></li> 23453<li><a href="#e-modifier" title="The Encoding Modifier ({e:})">Section�2.2.2.4</a></li> 23454<li><a href="#gettext-modifier" title="The Gettext Modifier ({g:})">Section�2.2.2.5</a></li> 23455<li><a href="#the-humanize-modifier-h" title="The Humanize Modifier ({h:})">Section�2.2.2.6</a></li> 23456<li><a href="#the-key-modifier-k" title="The Key Modifier ({k:})">Section�2.2.2.7</a></li> 23457<li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier ({l:})">Section�2.2.2.8</a></li> 23458<li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier ({n:})">Section�2.2.2.9</a></li> 23459<li><a href="#plural-modifier" title="The Plural Modifier ({p:})">Section�2.2.2.10</a></li> 23460<li><a href="#the-quotes-modifier-q" title="The Quotes Modifier ({q:})">Section�2.2.2.11</a></li> 23461<li><a href="#the-trim-modifier-t" title="The Trim Modifier ({t:})">Section�2.2.2.12</a></li> 23462<li><a href="#the-white-space-modifier-w" title="The White Space Modifier ({w:})">Section�2.2.2.13</a></li> |
| 23449</ul> 23450<div class="content"> 23451<h4 id="doc_section_2_2_2_1"> 23452<div class="self-section-number"> 23453<a href="#doc_section_2_2_2_1">2.2.2.1</a>�</div> | 23463</ul> 23464<div class="content"> 23465<h4 id="doc_section_2_2_2_1"> 23466<div class="self-section-number"> 23467<a href="#doc_section_2_2_2_1">2.2.2.1</a>�</div> |
| 23454<a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a> | 23468<a id="the-argument-modifier-a" href="#the-argument-modifier-a">The Argument Modifier ({a:})</a> |
| 23455</h4> | 23469</h4> |
| 23456<p id="doc_section_2_2_2_1_p_1">The colon modifier appends a single colon to the data value:</p> | 23470<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> |
| 23457<div id="doc_figure_u.48"></div> <pre> 23458 EXAMPLE: | 23471<div id="doc_figure_u.48"></div> <pre> 23472 EXAMPLE: |
| 23459 xo_emit("{Lc:Name}{:name}\n", "phil"); | 23473 xo_emit("{La:} {a:}\n", "Label text", "label", "value"); |
| 23460 TEXT: | 23474 TEXT: |
| 23461 Name:phil 23462 </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> | 23475 Label text value 23476 JSON: 23477 "label": "value" 23478 XML: 23479 <label>value</label> 23480 </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> |
| 23463</div> 23464<div class="content"> 23465<h4 id="doc_section_2_2_2_2"> 23466<div class="self-section-number"> 23467<a href="#doc_section_2_2_2_2">2.2.2.2</a>�</div> | 23481</div> 23482<div class="content"> 23483<h4 id="doc_section_2_2_2_2"> 23484<div class="self-section-number"> 23485<a href="#doc_section_2_2_2_2">2.2.2.2</a>�</div> |
| 23468<a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a> | 23486<a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier ({c:})</a> |
| 23469</h4> | 23487</h4> |
| 23470<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> | 23488<p id="doc_section_2_2_2_2_p_1">The colon modifier appends a single colon to the data value:</p> |
| 23471<div id="doc_figure_u.49"></div> <pre> 23472 EXAMPLE: | 23489<div id="doc_figure_u.49"></div> <pre> 23490 EXAMPLE: |
| 23491 xo_emit("{Lc:Name}{:name}\n", "phil"); 23492 TEXT: 23493 Name:phil 23494 </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> 23495</div> 23496<div class="content"> 23497<h4 id="doc_section_2_2_2_3"> 23498<div class="self-section-number"> 23499<a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div> 23500<a id="the-display-modifier-d" href="#the-display-modifier-d">The Display Modifier ({d:})</a> 23501</h4> 23502<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> 23503<div id="doc_figure_u.50"></div> <pre> 23504 EXAMPLE: |
|
| 23473 xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1); 23474 TEXT: 23475 Name: phil 1 23476 XML: 23477 <id>1</id> | 23505 xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1); 23506 TEXT: 23507 Name: phil 1 23508 XML: 23509 <id>1</id> |
| 23478 </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> | 23510 </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> |
| 23479</div> 23480<div class="content"> | 23511</div> 23512<div class="content"> |
| 23481<h4 id="doc_section_2_2_2_3"> | 23513<h4 id="doc_section_2_2_2_4"> |
| 23482<div class="self-section-number"> | 23514<div class="self-section-number"> |
| 23483<a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div> | 23515<a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div> |
| 23484<a id="e-modifier" href="#e-modifier">The Encoding Modifier ({e:})</a> 23485</h4> | 23516<a id="e-modifier" href="#e-modifier">The Encoding Modifier ({e:})</a> 23517</h4> |
| 23486<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> 23487<div id="doc_figure_u.50"></div> <pre> | 23518<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> 23519<div id="doc_figure_u.51"></div> <pre> |
| 23488 EXAMPLE: 23489 xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1); 23490 TEXT: 23491 Name: phil 23492 XML: 23493 <name>phil</name><id>1</id> | 23520 EXAMPLE: 23521 xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1); 23522 TEXT: 23523 Name: phil 23524 XML: 23525 <name>phil</name><id>1</id> |
| 23494 </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> | 23526 </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> |
| 23495</div> 23496<div class="content"> | 23527</div> 23528<div class="content"> |
| 23497<h4 id="doc_section_2_2_2_4"> | 23529<h4 id="doc_section_2_2_2_5"> |
| 23498<div class="self-section-number"> | 23530<div class="self-section-number"> |
| 23499<a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div> | 23531<a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div> |
| 23500<a id="gettext-modifier" href="#gettext-modifier">The Gettext Modifier ({g:})</a> 23501</h4> | 23532<a id="gettext-modifier" href="#gettext-modifier">The Gettext Modifier ({g:})</a> 23533</h4> |
| 23502<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> 23503<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> 23504<div id="doc_figure_u.51"></div> <pre> | 23534<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> 23535<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> 23536<div id="doc_figure_u.52"></div> <pre> |
| 23505 xo_emit("{Lgwc:State}{g:state}\n", "full"); | 23537 xo_emit("{Lgwc:State}{g:state}\n", "full"); |
| 23506 </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> | 23538 </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> |
| 23507</div> 23508<div class="content"> | 23539</div> 23540<div class="content"> |
| 23509<h4 id="doc_section_2_2_2_5"> | 23541<h4 id="doc_section_2_2_2_6"> |
| 23510<div class="self-section-number"> | 23542<div class="self-section-number"> |
| 23511<a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div> | 23543<a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div> |
| 23512<a id="the-humanize-modifier-h" href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a> 23513</h4> | 23544<a id="the-humanize-modifier-h" href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a> 23545</h4> |
| 23514<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> 23515<p id="doc_section_2_2_2_5_p_2">"hn" can be used as an alias for "humanize".</p> 23516<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> 23517<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> 23518<div id="doc_figure_u.52"></div> <pre> | 23546<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> 23547<p id="doc_section_2_2_2_6_p_2">"hn" can be used as an alias for "humanize".</p> 23548<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> 23549<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> 23550<div id="doc_figure_u.53"></div> <pre> |
| 23519 EXAMPLE: 23520 xo_emit("{h:input/%u}, {h,hn-space:output/%u}, " 23521 "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, " 23522 "{h,hn-decimal:remaining/%u}\n", 23523 input, output, errors, capacity, remaining); 23524 TEXT: 23525 21, 57 K, 96M, 44M, 1.2G | 23551 EXAMPLE: 23552 xo_emit("{h:input/%u}, {h,hn-space:output/%u}, " 23553 "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, " 23554 "{h,hn-decimal:remaining/%u}\n", 23555 input, output, errors, capacity, remaining); 23556 TEXT: 23557 21, 57 K, 96M, 44M, 1.2G |
| 23526 </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> 23527<div id="doc_figure_u.53"></div> <pre> | 23558 </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> 23559<div id="doc_figure_u.54"></div> <pre> |
| 23528 <div class="data" data-tag="errors" 23529 data-number="100663296">96M</div> 23530 </pre> </div> 23531<div class="content"> | 23560 <div class="data" data-tag="errors" 23561 data-number="100663296">96M</div> 23562 </pre> </div> 23563<div class="content"> |
| 23532<h4 id="doc_section_2_2_2_6"> | 23564<h4 id="doc_section_2_2_2_7"> |
| 23533<div class="self-section-number"> | 23565<div class="self-section-number"> |
| 23534<a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div> | 23566<a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div> |
| 23535<a id="the-key-modifier-k" href="#the-key-modifier-k">The Key Modifier ({k:})</a> 23536</h4> | 23567<a id="the-key-modifier-k" href="#the-key-modifier-k">The Key Modifier ({k:})</a> 23568</h4> |
| 23537<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> 23538<div id="doc_figure_u.54"></div> <pre> | 23569<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> 23570<div id="doc_figure_u.55"></div> <pre> |
| 23539 EXAMPLE: 23540 xo_open_list("user"); 23541 for (i = 0; i < num_users; i++) { 23542 xo_open_instance("user"); 23543 xo_emit("User {k:name} has {:count} tickets\n", 23544 user[i].u_name, user[i].u_tickets); 23545 xo_close_instance("user"); 23546 } 23547 xo_close_list("user"); | 23571 EXAMPLE: 23572 xo_open_list("user"); 23573 for (i = 0; i < num_users; i++) { 23574 xo_open_instance("user"); 23575 xo_emit("User {k:name} has {:count} tickets\n", 23576 user[i].u_name, user[i].u_tickets); 23577 xo_close_instance("user"); 23578 } 23579 xo_close_list("user"); |
| 23548 </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> | 23580 </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> |
| 23549</div> 23550<div class="content"> | 23581</div> 23582<div class="content"> |
| 23551<h4 id="doc_section_2_2_2_7"> | 23583<h4 id="doc_section_2_2_2_8"> |
| 23552<div class="self-section-number"> | 23584<div class="self-section-number"> |
| 23553<a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div> | 23585<a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div> |
| 23554<a id="the-leaf-list-modifier-l" href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a> 23555</h4> | 23586<a id="the-leaf-list-modifier-l" href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a> 23587</h4> |
| 23556<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> 23557<div id="doc_figure_u.55"></div> <pre> | 23588<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> 23589<div id="doc_figure_u.56"></div> <pre> |
| 23558 EXAMPLE: 23559 for (i = 0; i < num_users; i++) { 23560 xo_emit("Member {l:user}\n", user[i].u_name); 23561 } 23562 XML: 23563 <user>phil</user> 23564 <user>pallavi</user> 23565 JSON: 23566 "user": [ "phil", "pallavi" ] | 23590 EXAMPLE: 23591 for (i = 0; i < num_users; i++) { 23592 xo_emit("Member {l:user}\n", user[i].u_name); 23593 } 23594 XML: 23595 <user>phil</user> 23596 <user>pallavi</user> 23597 JSON: 23598 "user": [ "phil", "pallavi" ] |
| 23567 </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> | 23599 </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> |
| 23568</div> 23569<div class="content"> | 23600</div> 23601<div class="content"> |
| 23570<h4 id="doc_section_2_2_2_8"> | 23602<h4 id="doc_section_2_2_2_9"> |
| 23571<div class="self-section-number"> | 23603<div class="self-section-number"> |
| 23572<a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div> | 23604<a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div> |
| 23573<a id="the-no-quotes-modifier-n" href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a> 23574</h4> | 23605<a id="the-no-quotes-modifier-n" href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a> 23606</h4> |
| 23575<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> 23576<div id="doc_figure_u.56"></div> <pre> | 23607<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> 23608<div id="doc_figure_u.57"></div> <pre> |
| 23577 EXAMPLE: 23578 const char *bool = is_true ? "true" : "false"; 23579 xo_emit("{n:fancy/%s}", bool); 23580 JSON: 23581 "fancy": true 23582 </pre> </div> 23583<div class="content"> | 23609 EXAMPLE: 23610 const char *bool = is_true ? "true" : "false"; 23611 xo_emit("{n:fancy/%s}", bool); 23612 JSON: 23613 "fancy": true 23614 </pre> </div> 23615<div class="content"> |
| 23584<h4 id="doc_section_2_2_2_9"> | 23616<h4 id="doc_section_2_2_2_10"> |
| 23585<div class="self-section-number"> | 23617<div class="self-section-number"> |
| 23586<a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div> | 23618<a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div> |
| 23587<a id="plural-modifier" href="#plural-modifier">The Plural Modifier ({p:})</a> 23588</h4> | 23619<a id="plural-modifier" href="#plural-modifier">The Plural Modifier ({p:})</a> 23620</h4> |
| 23589<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> 23590<div id="doc_figure_u.57"></div> <pre> | 23621<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> 23622<div id="doc_figure_u.58"></div> <pre> |
| 23591 xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes); | 23623 xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes); |
| 23592 </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> 23593<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> 23594<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> | 23624 </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> 23625<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> 23626<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> |
| 23595</div> 23596<div class="content"> | 23627</div> 23628<div class="content"> |
| 23597<h4 id="doc_section_2_2_2_10"> | 23629<h4 id="doc_section_2_2_2_11"> |
| 23598<div class="self-section-number"> | 23630<div class="self-section-number"> |
| 23599<a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div> | 23631<a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div> |
| 23600<a id="the-quotes-modifier-q" href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a> 23601</h4> | 23632<a id="the-quotes-modifier-q" href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a> 23633</h4> |
| 23602<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> 23603<div id="doc_figure_u.58"></div> <pre> | 23634<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> 23635<div id="doc_figure_u.59"></div> <pre> |
| 23604 EXAMPLE: 23605 xo_emit("{q:time/%d}", 2014); 23606 JSON: 23607 "year": "2014" | 23636 EXAMPLE: 23637 xo_emit("{q:time/%d}", 2014); 23638 JSON: 23639 "year": "2014" |
| 23640 </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> 23641<div id="doc_figure_u.60"></div> <pre> 23642 d i o u x X D O U e E f F g G a A c C p |
|
| 23608 </pre> </div> 23609<div class="content"> | 23643 </pre> </div> 23644<div class="content"> |
| 23610<h4 id="doc_section_2_2_2_11"> | 23645<h4 id="doc_section_2_2_2_12"> |
| 23611<div class="self-section-number"> | 23646<div class="self-section-number"> |
| 23612<a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div> | 23647<a href="#doc_section_2_2_2_12">2.2.2.12</a>�</div> 23648<a id="the-trim-modifier-t" href="#the-trim-modifier-t">The Trim Modifier ({t:})</a> 23649</h4> 23650<p id="doc_section_2_2_2_12_p_1">The trim modifier removes any leading or trailing whitespace from the value.</p> 23651<div id="doc_figure_u.61"></div> <pre> 23652 EXAMPLE: 23653 xo_emit("{t:description}", " some input "); 23654 JSON: 23655 "description": "some input" 23656 </pre> </div> 23657<div class="content"> 23658<h4 id="doc_section_2_2_2_13"> 23659<div class="self-section-number"> 23660<a href="#doc_section_2_2_2_13">2.2.2.13</a>�</div> |
| 23613<a id="the-white-space-modifier-w" href="#the-white-space-modifier-w">The White Space Modifier ({w:})</a> 23614</h4> | 23661<a id="the-white-space-modifier-w" href="#the-white-space-modifier-w">The White Space Modifier ({w:})</a> 23662</h4> |
| 23615<p id="doc_section_2_2_2_11_p_1">The white space modifier appends a single space to the data value:</p> 23616<div id="doc_figure_u.59"></div> <pre> | 23663<p id="doc_section_2_2_2_13_p_1">The white space modifier appends a single space to the data value:</p> 23664<div id="doc_figure_u.62"></div> <pre> |
| 23617 EXAMPLE: 23618 xo_emit("{Lw:Name}{:name}\n", "phil"); 23619 TEXT: 23620 Name phil | 23665 EXAMPLE: 23666 xo_emit("{Lw:Name}{:name}\n", "phil"); 23667 TEXT: 23668 Name phil |
| 23621 </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> 23622<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> | 23669 </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> 23670<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> |
| 23623</div> 23624</div> 23625<div class="content"> 23626<h3 id="doc_section_2_2_3"> 23627<div class="self-section-number"> 23628<a href="#doc_section_2_2_3">2.2.3</a>�</div> 23629<a id="field-formatting" href="#field-formatting">Field Formatting</a> 23630</h3> 23631<p id="doc_section_2_2_3_p_1">The field format is similar to the format string for printf(3). Its use varies based on the role of the field, but generally is used to format the field's contents.</p> 23632<p id="doc_section_2_2_3_p_2">If the format string is not provided for a value field, it defaults to "%s".</p> 23633<p id="doc_section_2_2_3_p_3">Note a field definition can contain zero or more printf-style 'directives', which are sequences that start with a '%' and end with one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive is matched by one of more arguments to the xo_emit function.</p> 23634<p id="doc_section_2_2_3_p_4">The format string has the form:</p> | 23671</div> 23672</div> 23673<div class="content"> 23674<h3 id="doc_section_2_2_3"> 23675<div class="self-section-number"> 23676<a href="#doc_section_2_2_3">2.2.3</a>�</div> 23677<a id="field-formatting" href="#field-formatting">Field Formatting</a> 23678</h3> 23679<p id="doc_section_2_2_3_p_1">The field format is similar to the format string for printf(3). Its use varies based on the role of the field, but generally is used to format the field's contents.</p> 23680<p id="doc_section_2_2_3_p_2">If the format string is not provided for a value field, it defaults to "%s".</p> 23681<p id="doc_section_2_2_3_p_3">Note a field definition can contain zero or more printf-style 'directives', which are sequences that start with a '%' and end with one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive is matched by one of more arguments to the xo_emit function.</p> 23682<p id="doc_section_2_2_3_p_4">The format string has the form:</p> |
| 23635<div id="doc_figure_u.60"></div> <pre> | 23683<div id="doc_figure_u.63"></div> <pre> |
| 23636 '%' format-modifier * format-character 23637 </pre> <p id="doc_section_2_2_3_p_6">The format- modifier can be:</p> 23638<p id="doc_section_2_2_3_p_7"> </p> 23639<ul> 23640<li>a '#' character, indicating the output value should be prefixed with '0x', typically to indicate a base 16 (hex) value.</li> 23641<li>a minus sign ('‑'), indicating the output value should be padded on the right instead of the left.</li> 23642<li>a leading zero ('0') indicating the output value should be padded on the left with zeroes instead of spaces (' ').</li> 23643<li>one or more digits ('0' - '9') indicating the minimum width of the argument. If the width in columns of the output value is less that the minumum width, the value will be padded to reach the minimum.</li> --- 180 unchanged lines hidden (view full) --- 23824</div> 23825<div class="content"> 23826<h3 id="doc_section_2_2_4"> 23827<div class="self-section-number"> 23828<a href="#doc_section_2_2_4">2.2.4</a>�</div> 23829<a id="utf-8-and-locale-strings" href="#utf-8-and-locale-strings">UTF-8 and Locale Strings</a> 23830</h3> 23831<p id="doc_section_2_2_4_p_1">For strings, the 'h' and 'l' modifiers affect the interpretation of the bytes pointed to argument. The default '%s' string is a 'char *' pointer to a string encoded as UTF-8. Since UTF-8 is compatible with ASCII data, a normal 7-bit ASCII string can be used. '%ls' expects a 'wchar_t *' pointer to a wide-character string, encoded as a 32-bit Unicode values. '%hs' expects a 'char *' pointer to a multi-byte string encoded with the current locale, as given by the LC_CTYPE, LANG, or LC_ALL environment varibles. The first of this list of variables is used and if none of the variables are set, the locale defaults to "UTF‑8".</p> | 23684 '%' format-modifier * format-character 23685 </pre> <p id="doc_section_2_2_3_p_6">The format- modifier can be:</p> 23686<p id="doc_section_2_2_3_p_7"> </p> 23687<ul> 23688<li>a '#' character, indicating the output value should be prefixed with '0x', typically to indicate a base 16 (hex) value.</li> 23689<li>a minus sign ('‑'), indicating the output value should be padded on the right instead of the left.</li> 23690<li>a leading zero ('0') indicating the output value should be padded on the left with zeroes instead of spaces (' ').</li> 23691<li>one or more digits ('0' - '9') indicating the minimum width of the argument. If the width in columns of the output value is less that the minumum width, the value will be padded to reach the minimum.</li> --- 180 unchanged lines hidden (view full) --- 23872</div> 23873<div class="content"> 23874<h3 id="doc_section_2_2_4"> 23875<div class="self-section-number"> 23876<a href="#doc_section_2_2_4">2.2.4</a>�</div> 23877<a id="utf-8-and-locale-strings" href="#utf-8-and-locale-strings">UTF-8 and Locale Strings</a> 23878</h3> 23879<p id="doc_section_2_2_4_p_1">For strings, the 'h' and 'l' modifiers affect the interpretation of the bytes pointed to argument. The default '%s' string is a 'char *' pointer to a string encoded as UTF-8. Since UTF-8 is compatible with ASCII data, a normal 7-bit ASCII string can be used. '%ls' expects a 'wchar_t *' pointer to a wide-character string, encoded as a 32-bit Unicode values. '%hs' expects a 'char *' pointer to a multi-byte string encoded with the current locale, as given by the LC_CTYPE, LANG, or LC_ALL environment varibles. The first of this list of variables is used and if none of the variables are set, the locale defaults to "UTF‑8".</p> |
| 23832<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> 23833<div id="doc_figure_u.61"></div> <pre> | 23880<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> 23881<div id="doc_figure_u.64"></div> <pre> 23882 xo_emit("Alll strings are utf-8 content {:tag/%ls}", 23883 L"except for wide strings"); 23884 </pre> <p id="doc_section_2_2_4_p_4">"%S" is equivalent to "%ls".</p> 23885<div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> 23886<thead><tr> 23887<th class="left">Format</th> 23888<th class="left">Argument Type</th> 23889<th class="left">Argument Contents</th> 23890</tr></thead> 23891<tbody> 23892<tr> 23893<td>%s</td> 23894<td>const char *</td> 23895<td>UTF-8 string</td> 23896</tr> 23897<tr> 23898<td>%S</td> 23899<td>const char *</td> 23900<td>UTF-8 string (alias for '%s')</td> 23901</tr> 23902<tr> 23903<td>%ls</td> 23904<td>const wchar_t *</td> 23905<td>Wide character UNICODE string</td> 23906</tr> 23907<tr> 23908<td>%hs</td> 23909<td>const char *</td> 23910<td>locale-based string</td> 23911</tr> 23912</tbody> 23913</table></div> 23914<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> 23915<div id="doc_figure_u.65"></div> <pre> |
| 23834 void print_order (const char *name, int size, 23835 struct tm *timep) { 23836 char buf[32]; 23837 const char *size_val = "unknown"; 23838 23839 if (size > 0) 23840 snprintf(buf, sizeof(buf), "%d", size); 23841 size_val = buf; 23842 } 23843 23844 wchar_t when[32]; 23845 wcsftime(when, sizeof(when), L"%d%b%y", timep); 23846 23847 xo_emit("The hat for {:name/%hs} is {:size/%s}.\n", 23848 name, size_val); 23849 xo_emit("It was ordered on {:order-time/%ls}.\n", 23850 when); 23851 } | 23916 void print_order (const char *name, int size, 23917 struct tm *timep) { 23918 char buf[32]; 23919 const char *size_val = "unknown"; 23920 23921 if (size > 0) 23922 snprintf(buf, sizeof(buf), "%d", size); 23923 size_val = buf; 23924 } 23925 23926 wchar_t when[32]; 23927 wcsftime(when, sizeof(when), L"%d%b%y", timep); 23928 23929 xo_emit("The hat for {:name/%hs} is {:size/%s}.\n", 23930 name, size_val); 23931 xo_emit("It was ordered on {:order-time/%ls}.\n", 23932 when); 23933 } |
| 23852 </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> 23853<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> 23854<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> 23855<div id="doc_figure_u.62"></div> <pre> | 23934 </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> 23935<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> 23936<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> 23937<div id="doc_figure_u.66"></div> <pre> |
| 23856 xo_emit("{:name/%3.10.6s}", name); 23857 </pre> </div> 23858<div class="content"> 23859<h3 id="doc_section_2_2_5"> 23860<div class="self-section-number"> 23861<a href="#doc_section_2_2_5">2.2.5</a>�</div> 23862<a id="characters-outside-of-field-definitions" href="#characters-outside-of-field-definitions">Characters Outside of Field Definitions</a> 23863</h3> 23864<p id="doc_section_2_2_5_p_1">Characters in the format string that are not part of a field definition are copied to the output for the TEXT style, and are ignored for the JSON and XML styles. For HTML, these characters are placed in a <div> with class "text".</p> | 23938 xo_emit("{:name/%3.10.6s}", name); 23939 </pre> </div> 23940<div class="content"> 23941<h3 id="doc_section_2_2_5"> 23942<div class="self-section-number"> 23943<a href="#doc_section_2_2_5">2.2.5</a>�</div> 23944<a id="characters-outside-of-field-definitions" href="#characters-outside-of-field-definitions">Characters Outside of Field Definitions</a> 23945</h3> 23946<p id="doc_section_2_2_5_p_1">Characters in the format string that are not part of a field definition are copied to the output for the TEXT style, and are ignored for the JSON and XML styles. For HTML, these characters are placed in a <div> with class "text".</p> |
| 23865<div id="doc_figure_u.63"></div> <pre> | 23947<div id="doc_figure_u.67"></div> <pre> |
| 23866 EXAMPLE: 23867 xo_emit("The hat is {:size/%s}.\n", size_val); 23868 TEXT: 23869 The hat is extra small. 23870 XML: 23871 <size>extra small</size> 23872 JSON: 23873 "size": "extra small" --- 4 unchanged lines hidden (view full) --- 23878 </pre> </div> 23879<div class="content"> 23880<h3 id="doc_section_2_2_6"> 23881<div class="self-section-number"> 23882<a href="#doc_section_2_2_6">2.2.6</a>�</div> 23883<a id="m-is-supported" href="#m-is-supported">"%m" Is Supported</a> 23884</h3> 23885<p id="doc_section_2_2_6_p_1">libxo supports the '%m' directive, which formats the error message associated with the current value of "errno". It is the equivalent of "%s" with the argument strerror(errno).</p> | 23948 EXAMPLE: 23949 xo_emit("The hat is {:size/%s}.\n", size_val); 23950 TEXT: 23951 The hat is extra small. 23952 XML: 23953 <size>extra small</size> 23954 JSON: 23955 "size": "extra small" --- 4 unchanged lines hidden (view full) --- 23960 </pre> </div> 23961<div class="content"> 23962<h3 id="doc_section_2_2_6"> 23963<div class="self-section-number"> 23964<a href="#doc_section_2_2_6">2.2.6</a>�</div> 23965<a id="m-is-supported" href="#m-is-supported">"%m" Is Supported</a> 23966</h3> 23967<p id="doc_section_2_2_6_p_1">libxo supports the '%m' directive, which formats the error message associated with the current value of "errno". It is the equivalent of "%s" with the argument strerror(errno).</p> |
| 23886<div id="doc_figure_u.64"></div> <pre> | 23968<div id="doc_figure_u.68"></div> <pre> |
| 23887 xo_emit("{:filename} cannot be opened: {:error/%m}", filename); 23888 xo_emit("{:filename} cannot be opened: {:error/%s}", 23889 filename, strerror(errno)); 23890 </pre> </div> 23891<div class="content"> 23892<h3 id="doc_section_2_2_7"> 23893<div class="self-section-number"> 23894<a href="#doc_section_2_2_7">2.2.7</a>�</div> --- 30 unchanged lines hidden (view full) --- 23925<ul> 23926<li>implicit formats, where "{:tag}" has an implicit "%s";</li> 23927<li>the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to ten bytes of data can be inspected to fill a minimum of 4 columns and a maximum of 6;</li> 23928<li>percent signs in strings, where "{:filled}%" makes a single, trailing percent sign;</li> 23929<li>the "l" and "h" modifiers for strings, where "{:tag/%hs}" means locale-based string and "{:tag/%ls}" means a wide character string;</li> 23930<li>distinct encoding formats, where "{:tag/#%s/%s}" means the display styles (text and HTML) will use "#%s" where other styles use "%s";</li> 23931</ul> 23932<p id="doc_section_2_2_10_p_5">If none of these features are in use by your code, then using the "_p" variants might be wise.</p> | 23969 xo_emit("{:filename} cannot be opened: {:error/%m}", filename); 23970 xo_emit("{:filename} cannot be opened: {:error/%s}", 23971 filename, strerror(errno)); 23972 </pre> </div> 23973<div class="content"> 23974<h3 id="doc_section_2_2_7"> 23975<div class="self-section-number"> 23976<a href="#doc_section_2_2_7">2.2.7</a>�</div> --- 30 unchanged lines hidden (view full) --- 24007<ul> 24008<li>implicit formats, where "{:tag}" has an implicit "%s";</li> 24009<li>the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to ten bytes of data can be inspected to fill a minimum of 4 columns and a maximum of 6;</li> 24010<li>percent signs in strings, where "{:filled}%" makes a single, trailing percent sign;</li> 24011<li>the "l" and "h" modifiers for strings, where "{:tag/%hs}" means locale-based string and "{:tag/%ls}" means a wide character string;</li> 24012<li>distinct encoding formats, where "{:tag/#%s/%s}" means the display styles (text and HTML) will use "#%s" where other styles use "%s";</li> 24013</ul> 24014<p id="doc_section_2_2_10_p_5">If none of these features are in use by your code, then using the "_p" variants might be wise.</p> |
| 23933<div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24015<div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 23934<thead><tr> 23935<th class="left">Function</th> 23936<th class="left">printf-like Equivalent</th> 23937</tr></thead> 23938<tbody> 23939<tr> 23940<td>xo_emit_hv</td> 23941<td>xo_emit_hvp</td> --- 40 unchanged lines hidden (view full) --- 23982</tr> 23983</tbody> 23984</table></div> 23985</div> 23986<div class="content"> 23987<h3 id="doc_section_2_2_11"> 23988<div class="self-section-number"> 23989<a href="#doc_section_2_2_11">2.2.11</a>�</div> | 24016<thead><tr> 24017<th class="left">Function</th> 24018<th class="left">printf-like Equivalent</th> 24019</tr></thead> 24020<tbody> 24021<tr> 24022<td>xo_emit_hv</td> 24023<td>xo_emit_hvp</td> --- 40 unchanged lines hidden (view full) --- 24064</tr> 24065</tbody> 24066</table></div> 24067</div> 24068<div class="content"> 24069<h3 id="doc_section_2_2_11"> 24070<div class="self-section-number"> 24071<a href="#doc_section_2_2_11">2.2.11</a>�</div> |
| 24072<a id="retain" href="#retain">Retaining Parsed Format Information</a> 24073</h3> 24074<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> 24075<div id="doc_figure_u.69"></div> <pre> 24076 SYNTAX: 24077 int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...); 24078 EXAMPLE: 24079 xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n", 24080 some, thing, fancy); 24081 </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> 24082<div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> 24083<thead><tr> 24084<th class="left">Function</th> 24085<th class="left">Flags Equivalent</th> 24086</tr></thead> 24087<tbody> 24088<tr> 24089<td>xo_emit_hv</td> 24090<td>xo_emit_hvf</td> 24091</tr> 24092<tr> 24093<td>xo_emit_h</td> 24094<td>xo_emit_hf</td> 24095</tr> 24096<tr> 24097<td>xo_emit</td> 24098<td>xo_emit_f</td> 24099</tr> 24100<tr> 24101<td>xo_emit_hvp</td> 24102<td>xo_emit_hvfp</td> 24103</tr> 24104<tr> 24105<td>xo_emit_hp</td> 24106<td>xo_emit_hfp</td> 24107</tr> 24108<tr> 24109<td>xo_emit_p</td> 24110<td>xo_emit_fp</td> 24111</tr> 24112</tbody> 24113</table></div> 24114<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> 24115<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> 24116<div id="doc_figure_u.70"></div> <pre> 24117 const char *fmt = "{:name} {:count/%d}\n"; 24118 for (i = 0; i < 1000; i++) { 24119 xo_open_instance("item"); 24120 xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]); 24121 } 24122 xo_retain_clear(fmt); 24123 </pre> <p id="doc_section_2_2_11_p_7">The retained information is kept as thread-specific data.</p> 24124</div> 24125<div class="content"> 24126<h3 id="doc_section_2_2_12"> 24127<div class="self-section-number"> 24128<a href="#doc_section_2_2_12">2.2.12</a>�</div> |
|
| 23990<a id="example" href="#example">Example</a> 23991</h3> | 24129<a id="example" href="#example">Example</a> 24130</h3> |
| 23992<p id="doc_section_2_2_11_p_1">In this example, the value for the number of items in stock is emitted:</p> 23993<div id="doc_figure_u.65"></div> <pre> | 24131<p id="doc_section_2_2_12_p_1">In this example, the value for the number of items in stock is emitted:</p> 24132<div id="doc_figure_u.71"></div> <pre> |
| 23994 xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 23995 instock); | 24133 xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 24134 instock); |
| 23996 </pre> <p id="doc_section_2_2_11_p_3">This call will generate the following output:</p> 23997<div id="doc_figure_u.66"></div> <pre> | 24135 </pre> <p id="doc_section_2_2_12_p_3">This call will generate the following output:</p> 24136<div id="doc_figure_u.72"></div> <pre> |
| 23998 TEXT: 23999 In stock: 144 24000 XML: 24001 <in-stock>144</in-stock> 24002 JSON: 24003 "in-stock": 144, 24004 HTML: 24005 <div class="line"> 24006 <div class="padding"> </div> 24007 <div class="label">In stock</div> 24008 <div class="decoration">:</div> 24009 <div class="padding"> </div> 24010 <div class="data" data-tag="in-stock">144</div> 24011 </div> | 24137 TEXT: 24138 In stock: 144 24139 XML: 24140 <in-stock>144</in-stock> 24141 JSON: 24142 "in-stock": 144, 24143 HTML: 24144 <div class="line"> 24145 <div class="padding"> </div> 24146 <div class="label">In stock</div> 24147 <div class="decoration">:</div> 24148 <div class="padding"> </div> 24149 <div class="data" data-tag="in-stock">144</div> 24150 </div> |
| 24012 </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> 24013<div id="doc_figure_u.67"></div> <pre> | 24151 </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> 24152<div id="doc_figure_u.73"></div> <pre> |
| 24014 <div class="data" data-tag="in-stock" 24015 data-xpath="/top/data/item/in-stock" 24016 data-type="number" 24017 data-help="Number of items in stock">144</div> 24018 </pre> </div> 24019</div> 24020<div class="content"> 24021<h2 id="doc_section_2_3"> 24022<div class="self-section-number"> 24023<a href="#doc_section_2_3">2.3</a>�</div> | 24153 <div class="data" data-tag="in-stock" 24154 data-xpath="/top/data/item/in-stock" 24155 data-type="number" 24156 data-help="Number of items in stock">144</div> 24157 </pre> </div> 24158</div> 24159<div class="content"> 24160<h2 id="doc_section_2_3"> 24161<div class="self-section-number"> 24162<a href="#doc_section_2_3">2.3</a>�</div> |
| 24163<a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a> 24164</h2> 24165<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> 24166<p id="doc_section_2_3_p_2">XML encodes lists as set of sequential elements:</p> 24167<div id="doc_figure_u.74"></div> <pre> 24168 <user>phil</user> 24169 <user>pallavi</user> 24170 <user>sjg</user> 24171 </pre> <p id="doc_section_2_3_p_4">JSON encodes lists using a single name and square brackets:</p> 24172<div id="doc_figure_u.75"></div> <pre> 24173 "user": [ "phil", "pallavi", "sjg" ] 24174 </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> 24175<p id="doc_section_2_3_p_7">Section Contents: </p> 24176<ul> 24177<li><a href="#containers" title="Containers">Section�2.3.1</a></li> 24178<li><a href="#lists-and-instances" title="Lists and Instances">Section�2.3.2</a></li> 24179<li><a href="#dtrt-mode" title="DTRT Mode">Section�2.3.3</a></li> 24180<li><a href="#markers" title="Markers">Section�2.3.4</a></li> 24181</ul> 24182<div class="content"> 24183<h3 id="doc_section_2_3_1"> 24184<div class="self-section-number"> 24185<a href="#doc_section_2_3_1">2.3.1</a>�</div> 24186<a id="containers" href="#containers">Containers</a> 24187</h3> 24188<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> 24189<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> 24190<div id="doc_figure_u.76"></div> <pre> 24191 int xo_open_container_h (xo_handle_t *xop, const char *name); 24192 int xo_open_container (const char *name); 24193 </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> 24194<div id="doc_figure_u.77"></div> <pre> 24195 int xo_close_container_h (xo_handle_t *xop, const char *name); 24196 int xo_close_container (const char *name); 24197 </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> 24198<div id="doc_figure_u.78"></div> <pre> 24199 Example: 24200 24201 xo_open_container("top"); 24202 xo_open_container("system"); 24203 xo_emit("{:host-name/%s%s%s", hostname, 24204 domainname ? "." : "", domainname ?: ""); 24205 xo_close_container("system"); 24206 xo_close_container("top"); 24207 24208 Sample Output: 24209 Text: 24210 my-host.example.org 24211 XML: 24212 <top> 24213 <system> 24214 <host-name>my-host.example.org</host-name> 24215 </system> 24216 </top> 24217 JSON: 24218 "top" : { 24219 "system" : { 24220 "host-name": "my-host.example.org" 24221 } 24222 } 24223 HTML: 24224 <div class="data" 24225 data-tag="host-name">my-host.example.org</div> 24226 </pre> </div> 24227<div class="content"> 24228<h3 id="doc_section_2_3_2"> 24229<div class="self-section-number"> 24230<a href="#doc_section_2_3_2">2.3.2</a>�</div> 24231<a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a> 24232</h3> 24233<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> 24234<div id="doc_figure_u.79"></div> <pre> 24235 xo_open_list("item"); 24236 24237 for (ip = list; ip->i_title; ip++) { 24238 xo_open_instance("item"); 24239 xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title); 24240 xo_close_instance("item"); 24241 } 24242 24243 xo_close_list("item"); 24244 </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> 24245</div> 24246<div class="content"> 24247<h3 id="doc_section_2_3_3"> 24248<div class="self-section-number"> 24249<a href="#doc_section_2_3_3">2.3.3</a>�</div> 24250<a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a> 24251</h3> 24252<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> 24253<div id="doc_figure_u.80"></div> <pre> 24254 xo_set_flags(NULL, XOF_DTRT); 24255 </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> 24256<div id="doc_figure_u.81"></div> <pre> 24257 xo_open_container("top"); 24258 ... 24259 xo_close_container_d(); 24260 </pre> <p id="doc_section_2_3_3_p_5">This also works for lists and instances:</p> 24261<div id="doc_figure_u.82"></div> <pre> 24262 xo_open_list("item"); 24263 for (...) { 24264 xo_open_instance("item"); 24265 xo_emit(...); 24266 xo_close_instance_d(); 24267 } 24268 xo_close_list_d(); 24269 </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> 24270</div> 24271<div class="content"> 24272<h3 id="doc_section_2_3_4"> 24273<div class="self-section-number"> 24274<a href="#doc_section_2_3_4">2.3.4</a>�</div> 24275<a id="markers" href="#markers">Markers</a> 24276</h3> 24277<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> 24278<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> 24279<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> 24280<div id="doc_figure_u.83"></div> <pre> 24281 for (i = 0; fish[i]; i++) { 24282 xo_open_instance("fish"); 24283 xo_open_marker("fish-guts"); 24284 dump_fish_details(i); 24285 xo_close_marker("fish-guts"); 24286 } 24287 </pre> </div> 24288</div> 24289<div class="content"> 24290<h2 id="doc_section_2_4"> 24291<div class="self-section-number"> 24292<a href="#doc_section_2_4">2.4</a>�</div> |
|
| 24024<a id="command-line-arguments" href="#command-line-arguments">Command-line Arguments</a> 24025</h2> | 24293<a id="command-line-arguments" href="#command-line-arguments">Command-line Arguments</a> 24294</h2> |
| 24026<p id="doc_section_2_3_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p> 24027<p id="doc_section_2_3_p_2"> </p> | 24295<p id="doc_section_2_4_p_1">libxo uses command line options to trigger rendering behavior. The following options are recognised:</p> 24296<p id="doc_section_2_4_p_2"> </p> |
| 24028<ul> 24029<li>--libxo <options></li> 24030<li>--libxo=<options></li> 24031<li>--libxo:<brief‑options></li> 24032</ul> | 24297<ul> 24298<li>--libxo <options></li> 24299<li>--libxo=<options></li> 24300<li>--libxo:<brief‑options></li> 24301</ul> |
| 24033<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> 24034<div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24302<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> 24303<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> 24304<div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24035<thead><tr> 24036<th class="left">Token</th> 24037<th class="left">Action</th> 24038</tr></thead> 24039<tbody> 24040<tr> 24041<td>color</td> 24042<td>Enable colors/effects for display styles (TEXT, HTML)</td> --- 34 unchanged lines hidden (view full) --- 24077<td>no-humanize</td> 24078<td>Ignore the {h:} modifier (TEXT, HTML)</td> 24079</tr> 24080<tr> 24081<td>no-locale</td> 24082<td>Do not initialize the locale setting</td> 24083</tr> 24084<tr> | 24305<thead><tr> 24306<th class="left">Token</th> 24307<th class="left">Action</th> 24308</tr></thead> 24309<tbody> 24310<tr> 24311<td>color</td> 24312<td>Enable colors/effects for display styles (TEXT, HTML)</td> --- 34 unchanged lines hidden (view full) --- 24347<td>no-humanize</td> 24348<td>Ignore the {h:} modifier (TEXT, HTML)</td> 24349</tr> 24350<tr> 24351<td>no-locale</td> 24352<td>Do not initialize the locale setting</td> 24353</tr> 24354<tr> |
| 24355<td>no-retain</td> 24356<td>Prevent retaining formatting information</td> 24357</tr> 24358<tr> |
|
| 24085<td>no-top</td> 24086<td>Do not emit a top set of braces (JSON)</td> 24087</tr> 24088<tr> 24089<td>not-first</td> 24090<td>Pretend the 1st output item was not 1st (JSON)</td> 24091</tr> 24092<tr> 24093<td>pretty</td> 24094<td>Emit pretty-printed output</td> 24095</tr> 24096<tr> | 24359<td>no-top</td> 24360<td>Do not emit a top set of braces (JSON)</td> 24361</tr> 24362<tr> 24363<td>not-first</td> 24364<td>Pretend the 1st output item was not 1st (JSON)</td> 24365</tr> 24366<tr> 24367<td>pretty</td> 24368<td>Emit pretty-printed output</td> 24369</tr> 24370<tr> |
| 24371<td>retain</td> 24372<td>Force retaining formatting information</td> 24373</tr> 24374<tr> |
|
| 24097<td>text</td> 24098<td>Emit TEXT output</td> 24099</tr> 24100<tr> 24101<td>underscores</td> 24102<td>Replace XML-friendly "-"s with JSON friendly "_"s e</td> 24103</tr> 24104<tr> --- 13 unchanged lines hidden (view full) --- 24118<td>Emit XML output</td> 24119</tr> 24120<tr> 24121<td>xpath</td> 24122<td>Add XPath expressions (HTML)</td> 24123</tr> 24124</tbody> 24125</table></div> | 24375<td>text</td> 24376<td>Emit TEXT output</td> 24377</tr> 24378<tr> 24379<td>underscores</td> 24380<td>Replace XML-friendly "-"s with JSON friendly "_"s e</td> 24381</tr> 24382<tr> --- 13 unchanged lines hidden (view full) --- 24396<td>Emit XML output</td> 24397</tr> 24398<tr> 24399<td>xpath</td> 24400<td>Add XPath expressions (HTML)</td> 24401</tr> 24402</tbody> 24403</table></div> |
| 24126<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> | 24404<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> |
| 24127</div> | 24405</div> |
| 24128<div class="content"> 24129<h2 id="doc_section_2_4"> 24130<div class="self-section-number"> 24131<a href="#doc_section_2_4">2.4</a>�</div> 24132<a id="representing-hierarchy" href="#representing-hierarchy">Representing Hierarchy</a> 24133</h2> 24134<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> 24135<p id="doc_section_2_4_p_2">XML encodes lists as set of sequential elements:</p> 24136<div id="doc_figure_u.68"></div> <pre> 24137 <user>phil</user> 24138 <user>pallavi</user> 24139 <user>sjg</user> 24140 </pre> <p id="doc_section_2_4_p_4">JSON encodes lists using a single name and square brackets:</p> 24141<div id="doc_figure_u.69"></div> <pre> 24142 "user": [ "phil", "pallavi", "sjg" ] 24143 </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> 24144<p id="doc_section_2_4_p_7">Section Contents: </p> 24145<ul> 24146<li><a href="#containers" title="Containers">Section�2.4.1</a></li> 24147<li><a href="#lists-and-instances" title="Lists and Instances">Section�2.4.2</a></li> 24148<li><a href="#dtrt-mode" title="DTRT Mode">Section�2.4.3</a></li> 24149<li><a href="#markers" title="Markers">Section�2.4.4</a></li> 24150</ul> 24151<div class="content"> 24152<h3 id="doc_section_2_4_1"> 24153<div class="self-section-number"> 24154<a href="#doc_section_2_4_1">2.4.1</a>�</div> 24155<a id="containers" href="#containers">Containers</a> 24156</h3> 24157<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> 24158<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> 24159<div id="doc_figure_u.70"></div> <pre> 24160 int xo_open_container_h (xo_handle_t *xop, const char *name); 24161 int xo_open_container (const char *name); 24162 </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> 24163<div id="doc_figure_u.71"></div> <pre> 24164 int xo_close_container_h (xo_handle_t *xop, const char *name); 24165 int xo_close_container (const char *name); 24166 </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> 24167<div id="doc_figure_u.72"></div> <pre> 24168 Example: 24169 24170 xo_open_container("top"); 24171 xo_open_container("system"); 24172 xo_emit("{:host-name/%s%s%s", hostname, 24173 domainname ? "." : "", domainname ?: ""); 24174 xo_close_container("system"); 24175 xo_close_container("top"); 24176 24177 Sample Output: 24178 Text: 24179 my-host.example.org 24180 XML: 24181 <top> 24182 <system> 24183 <host-name>my-host.example.org</host-name> 24184 </system> 24185 </top> 24186 JSON: 24187 "top" : { 24188 "system" : { 24189 "host-name": "my-host.example.org" 24190 } 24191 } 24192 HTML: 24193 <div class="data" 24194 data-tag="host-name">my-host.example.org</div> 24195 </pre> </div> 24196<div class="content"> 24197<h3 id="doc_section_2_4_2"> 24198<div class="self-section-number"> 24199<a href="#doc_section_2_4_2">2.4.2</a>�</div> 24200<a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a> 24201</h3> 24202<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> 24203<div id="doc_figure_u.73"></div> <pre> 24204 xo_open_list("item"); 24205 24206 for (ip = list; ip->i_title; ip++) { 24207 xo_open_instance("item"); 24208 xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title); 24209 xo_close_instance("item"); 24210 } 24211 24212 xo_close_list("item"); 24213 </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> | |
| 24214</div> | 24406</div> |
| 24215<div class="content"> 24216<h3 id="doc_section_2_4_3"> 24217<div class="self-section-number"> 24218<a href="#doc_section_2_4_3">2.4.3</a>�</div> 24219<a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a> 24220</h3> 24221<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> 24222<div id="doc_figure_u.74"></div> <pre> 24223 xo_set_flags(NULL, XOF_DTRT); 24224 </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> 24225<div id="doc_figure_u.75"></div> <pre> 24226 xo_open_container("top"); 24227 ... 24228 xo_close_container_d(); 24229 </pre> <p id="doc_section_2_4_3_p_5">This also works for lists and instances:</p> 24230<div id="doc_figure_u.76"></div> <pre> 24231 xo_open_list("item"); 24232 for (...) { 24233 xo_open_instance("item"); 24234 xo_emit(...); 24235 xo_close_instance_d(); 24236 } 24237 xo_close_list_d(); 24238 </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> 24239</div> 24240<div class="content"> 24241<h3 id="doc_section_2_4_4"> 24242<div class="self-section-number"> 24243<a href="#doc_section_2_4_4">2.4.4</a>�</div> 24244<a id="markers" href="#markers">Markers</a> 24245</h3> 24246<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> 24247<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> 24248<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> 24249<div id="doc_figure_u.77"></div> <pre> 24250 for (i = 0; fish[i]; i++) { 24251 xo_open_instance("fish"); 24252 xo_open_marker("fish-guts"); 24253 dump_fish_details(i); 24254 xo_close_marker("fish-guts"); 24255 } 24256 </pre> </div> 24257</div> 24258<div class="content"> 24259<h2 id="doc_section_2_5"> 24260<div class="self-section-number"> 24261<a href="#doc_section_2_5">2.5</a>�</div> 24262<a id="handles" href="#handles">Handles</a> 24263</h2> 24264<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> 24265<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> 24266<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> 24267<p id="doc_section_2_5_p_4">For example, the following are equivalent:</p> 24268<div id="doc_figure_u.78"></div> <pre> 24269 xo_emit("test"); 24270 xo_emit_h(NULL, "test"); 24271 </pre> <p id="doc_section_2_5_p_6">Handles are created using xo_create() and destroy using xo_destroy().</p> 24272</div> 24273<div class="content"> 24274<h2 id="doc_section_2_6"> 24275<div class="self-section-number"> 24276<a href="#doc_section_2_6">2.6</a>�</div> 24277<a id="utf-8" href="#utf-8">UTF-8</a> 24278</h2> 24279<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> 24280<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> 24281<div id="doc_figure_u.79"></div> <pre> 24282 xo_emit("Alll strings are utf-8 content {:tag/%ls}", 24283 L"except for wide strings"); 24284 </pre> <p id="doc_section_2_6_p_4">"%S" is equivalent to "%ls".</p> 24285</div> 24286</div> | |
| 24287<hr class="noprint"> 24288<div class="content"> 24289<h1 id="doc_section_3" class="np"> 24290<div class="self-section-number"> 24291<a href="#doc_section_3">3_</a>�</div> 24292<a id="the-libxo-api" href="#the-libxo-api">The libxo API</a> 24293</h1> 24294<p id="doc_section_3_p_1">This section gives details about the functions in libxo, how to call them, and the actions they perform.</p> 24295<p id="doc_section_3_p_2">Section Contents: </p> 24296<ul> | 24407<hr class="noprint"> 24408<div class="content"> 24409<h1 id="doc_section_3" class="np"> 24410<div class="self-section-number"> 24411<a href="#doc_section_3">3_</a>�</div> 24412<a id="the-libxo-api" href="#the-libxo-api">The libxo API</a> 24413</h1> 24414<p id="doc_section_3_p_1">This section gives details about the functions in libxo, how to call them, and the actions they perform.</p> 24415<p id="doc_section_3_p_2">Section Contents: </p> 24416<ul> |
| 24297<li><a href="#handles-2" title="Handles">Section�3.1</a></li> | 24417 |
| 24298<li><a href="#emitting-content-xo_emit" title="Emitting Content (xo_emit)">Section�3.2</a></li> 24299<li><a href="#emitting-hierarchy" title="Emitting Hierarchy">Section�3.3</a></li> 24300<li><a href="#support-functions" title="Support Functions">Section�3.4</a></li> 24301<li><a href="#emitting-syslog-messages" title="Emitting syslog Messages">Section�3.5</a></li> 24302<li><a href="#creating-custom-encoders" title="Creating Custom Encoders">Section�3.6</a></li> 24303</ul> 24304<div class="content"> 24305<h2 id="doc_section_3_1"> 24306<div class="self-section-number"> 24307<a href="#doc_section_3_1">3.1</a>�</div> | 24418<li><a href="#emitting-content-xo_emit" title="Emitting Content (xo_emit)">Section�3.2</a></li> 24419<li><a href="#emitting-hierarchy" title="Emitting Hierarchy">Section�3.3</a></li> 24420<li><a href="#support-functions" title="Support Functions">Section�3.4</a></li> 24421<li><a href="#emitting-syslog-messages" title="Emitting syslog Messages">Section�3.5</a></li> 24422<li><a href="#creating-custom-encoders" title="Creating Custom Encoders">Section�3.6</a></li> 24423</ul> 24424<div class="content"> 24425<h2 id="doc_section_3_1"> 24426<div class="self-section-number"> 24427<a href="#doc_section_3_1">3.1</a>�</div> |
| 24308<a id="handles-2" href="#handles-2">Handles</a> | 24428<a id="handles" href="#handles">Handles</a> |
| 24309</h2> | 24429</h2> |
| 24310<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> 24311<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> 24312<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> | 24430<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> 24431<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> 24432<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> |
| 24313<p id="doc_section_3_1_p_4">For the typical command that is generating output on standard output, there is no need to create an explicit handle, but they are available when needed, e.g., for daemons that generate multiple streams of output.</p> | 24433<p id="doc_section_3_1_p_4">For the typical command that is generating output on standard output, there is no need to create an explicit handle, but they are available when needed, e.g., for daemons that generate multiple streams of output.</p> |
| 24314<p id="doc_section_3_1_p_5">Section Contents: </p> | 24434<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> 24435<p id="doc_section_3_1_p_6">For example, the following are equivalent:</p> 24436<div id="doc_figure_u.84"></div> <pre> 24437 xo_emit("test"); 24438 xo_emit_h(NULL, "test"); 24439 </pre> <p id="doc_section_3_1_p_8">Handles are created using xo_create() and destroy using xo_destroy().</p> 24440<p id="doc_section_3_1_p_9">Section Contents: </p> |
| 24315<ul> 24316<li><a href="#xo_create" title="xo_create">Section�3.1.1</a></li> 24317<li><a href="#xo_create_to_file" title="xo_create_to_file">Section�3.1.2</a></li> 24318<li><a href="#xo_set_writer" title="xo_set_writer">Section�3.1.3</a></li> 24319<li><a href="#xo_set_style" title="xo_set_style">Section�3.1.4</a></li> 24320<li><a href="#xo_set_flags" title="xo_set_flags">Section�3.1.5</a></li> 24321<li><a href="#xo_destroy" title="xo_destroy">Section�3.1.6</a></li> 24322</ul> 24323<div class="content"> 24324<h3 id="doc_section_3_1_1"> 24325<div class="self-section-number"> 24326<a href="#doc_section_3_1_1">3.1.1</a>�</div> 24327<a id="xo_create" href="#xo_create">xo_create</a> 24328</h3> 24329<p id="doc_section_3_1_1_p_1">A handle can be allocated using the xo_create() function:</p> | 24441<ul> 24442<li><a href="#xo_create" title="xo_create">Section�3.1.1</a></li> 24443<li><a href="#xo_create_to_file" title="xo_create_to_file">Section�3.1.2</a></li> 24444<li><a href="#xo_set_writer" title="xo_set_writer">Section�3.1.3</a></li> 24445<li><a href="#xo_set_style" title="xo_set_style">Section�3.1.4</a></li> 24446<li><a href="#xo_set_flags" title="xo_set_flags">Section�3.1.5</a></li> 24447<li><a href="#xo_destroy" title="xo_destroy">Section�3.1.6</a></li> 24448</ul> 24449<div class="content"> 24450<h3 id="doc_section_3_1_1"> 24451<div class="self-section-number"> 24452<a href="#doc_section_3_1_1">3.1.1</a>�</div> 24453<a id="xo_create" href="#xo_create">xo_create</a> 24454</h3> 24455<p id="doc_section_3_1_1_p_1">A handle can be allocated using the xo_create() function:</p> |
| 24330<div id="doc_figure_u.80"></div> <pre> | 24456<div id="doc_figure_u.85"></div> <pre> |
| 24331 xo_handle_t *xo_create (unsigned style, unsigned flags); 24332 24333 Example: 24334 xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN); 24335 .... 24336 xo_emit_h(xop, "testing\n"); 24337 </pre> <p id="doc_section_3_1_1_p_3">See also <a href="#styles" title="Output Styles (XO_STYLE_*)">Section�3.1.4.1</a> and <a href="#flags" title="Flags (XOF_*)">Section�3.1.5.1</a>.</p> 24338</div> 24339<div class="content"> 24340<h3 id="doc_section_3_1_2"> 24341<div class="self-section-number"> 24342<a href="#doc_section_3_1_2">3.1.2</a>�</div> 24343<a id="xo_create_to_file" href="#xo_create_to_file">xo_create_to_file</a> 24344</h3> 24345<p id="doc_section_3_1_2_p_1">By default, libxo writes output to standard output. A convenience function is provided for situations when output should be written to a different file:</p> | 24457 xo_handle_t *xo_create (unsigned style, unsigned flags); 24458 24459 Example: 24460 xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN); 24461 .... 24462 xo_emit_h(xop, "testing\n"); 24463 </pre> <p id="doc_section_3_1_1_p_3">See also <a href="#styles" title="Output Styles (XO_STYLE_*)">Section�3.1.4.1</a> and <a href="#flags" title="Flags (XOF_*)">Section�3.1.5.1</a>.</p> 24464</div> 24465<div class="content"> 24466<h3 id="doc_section_3_1_2"> 24467<div class="self-section-number"> 24468<a href="#doc_section_3_1_2">3.1.2</a>�</div> 24469<a id="xo_create_to_file" href="#xo_create_to_file">xo_create_to_file</a> 24470</h3> 24471<p id="doc_section_3_1_2_p_1">By default, libxo writes output to standard output. A convenience function is provided for situations when output should be written to a different file:</p> |
| 24346<div id="doc_figure_u.81"></div> <pre> | 24472<div id="doc_figure_u.86"></div> <pre> |
| 24347 xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, 24348 unsigned flags); 24349 </pre> <p id="doc_section_3_1_2_p_3">Use the XOF_CLOSE_FP flag to trigger a call to fclose() for the FILE pointer when the handle is destroyed.</p> 24350</div> 24351<div class="content"> 24352<h3 id="doc_section_3_1_3"> 24353<div class="self-section-number"> 24354<a href="#doc_section_3_1_3">3.1.3</a>�</div> 24355<a id="xo_set_writer" href="#xo_set_writer">xo_set_writer</a> 24356</h3> 24357<p id="doc_section_3_1_3_p_1">The xo_set_writer function allows custom 'write' functions which can tailor how libxo writes data. An opaque argument is recorded and passed back to the write function, allowing the function to acquire context information. The 'close' function can release this opaque data and any other resources as needed. The flush function can flush buffered data associated with the opaque object.</p> | 24473 xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, 24474 unsigned flags); 24475 </pre> <p id="doc_section_3_1_2_p_3">Use the XOF_CLOSE_FP flag to trigger a call to fclose() for the FILE pointer when the handle is destroyed.</p> 24476</div> 24477<div class="content"> 24478<h3 id="doc_section_3_1_3"> 24479<div class="self-section-number"> 24480<a href="#doc_section_3_1_3">3.1.3</a>�</div> 24481<a id="xo_set_writer" href="#xo_set_writer">xo_set_writer</a> 24482</h3> 24483<p id="doc_section_3_1_3_p_1">The xo_set_writer function allows custom 'write' functions which can tailor how libxo writes data. An opaque argument is recorded and passed back to the write function, allowing the function to acquire context information. The 'close' function can release this opaque data and any other resources as needed. The flush function can flush buffered data associated with the opaque object.</p> |
| 24358<div id="doc_figure_u.82"></div> <pre> | 24484<div id="doc_figure_u.87"></div> <pre> |
| 24359 void xo_set_writer (xo_handle_t *xop, void *opaque, 24360 xo_write_func_t write_func, 24361 xo_close_func_t close_func); 24362 xo_flush_func_t flush_func); 24363 </pre> </div> 24364<div class="content"> 24365<h3 id="doc_section_3_1_4"> 24366<div class="self-section-number"> 24367<a href="#doc_section_3_1_4">3.1.4</a>�</div> 24368<a id="xo_set_style" href="#xo_set_style">xo_set_style</a> 24369</h3> 24370<p id="doc_section_3_1_4_p_1">To set the style, use the xo_set_style() function:</p> | 24485 void xo_set_writer (xo_handle_t *xop, void *opaque, 24486 xo_write_func_t write_func, 24487 xo_close_func_t close_func); 24488 xo_flush_func_t flush_func); 24489 </pre> </div> 24490<div class="content"> 24491<h3 id="doc_section_3_1_4"> 24492<div class="self-section-number"> 24493<a href="#doc_section_3_1_4">3.1.4</a>�</div> 24494<a id="xo_set_style" href="#xo_set_style">xo_set_style</a> 24495</h3> 24496<p id="doc_section_3_1_4_p_1">To set the style, use the xo_set_style() function:</p> |
| 24371<div id="doc_figure_u.83"></div> <pre> | 24497<div id="doc_figure_u.88"></div> <pre> |
| 24372 void xo_set_style(xo_handle_t *xop, unsigned style); 24373 </pre> <p id="doc_section_3_1_4_p_3">To use the default handle, pass a NULL handle:</p> | 24498 void xo_set_style(xo_handle_t *xop, unsigned style); 24499 </pre> <p id="doc_section_3_1_4_p_3">To use the default handle, pass a NULL handle:</p> |
| 24374<div id="doc_figure_u.84"></div> <pre> | 24500<div id="doc_figure_u.89"></div> <pre> |
| 24375 xo_set_style(NULL, XO_STYLE_XML); 24376 </pre> <p id="doc_section_3_1_4_p_5">Section Contents: </p> 24377<ul> 24378<li><a href="#styles" title="Output Styles (XO_STYLE_*)">Section�3.1.4.1</a></li> 24379<li><a href="#xo_set_style_name" title="xo_set_style_name">Section�3.1.4.2</a></li> 24380</ul> 24381<div class="content"> 24382<h4 id="doc_section_3_1_4_1"> 24383<div class="self-section-number"> 24384<a href="#doc_section_3_1_4_1">3.1.4.1</a>�</div> 24385<a id="styles" href="#styles">Output Styles (XO_STYLE_*)</a> 24386</h4> 24387<p id="doc_section_3_1_4_1_p_1">The libxo functions accept a set of output styles:</p> | 24501 xo_set_style(NULL, XO_STYLE_XML); 24502 </pre> <p id="doc_section_3_1_4_p_5">Section Contents: </p> 24503<ul> 24504<li><a href="#styles" title="Output Styles (XO_STYLE_*)">Section�3.1.4.1</a></li> 24505<li><a href="#xo_set_style_name" title="xo_set_style_name">Section�3.1.4.2</a></li> 24506</ul> 24507<div class="content"> 24508<h4 id="doc_section_3_1_4_1"> 24509<div class="self-section-number"> 24510<a href="#doc_section_3_1_4_1">3.1.4.1</a>�</div> 24511<a id="styles" href="#styles">Output Styles (XO_STYLE_*)</a> 24512</h4> 24513<p id="doc_section_3_1_4_1_p_1">The libxo functions accept a set of output styles:</p> |
| 24388<div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24514<div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24389<thead><tr> 24390<th class="left">Flag</th> 24391<th class="left">Description</th> 24392</tr></thead> 24393<tbody> 24394<tr> 24395<td>XO_STYLE_TEXT</td> 24396<td>Traditional text output</td> --- 15 unchanged lines hidden (view full) --- 24412</div> 24413<div class="content"> 24414<h4 id="doc_section_3_1_4_2"> 24415<div class="self-section-number"> 24416<a href="#doc_section_3_1_4_2">3.1.4.2</a>�</div> 24417<a id="xo_set_style_name" href="#xo_set_style_name">xo_set_style_name</a> 24418</h4> 24419<p id="doc_section_3_1_4_2_p_1">The xo_set_style_name() can be used to set the style based on a name encoded as a string:</p> | 24515<thead><tr> 24516<th class="left">Flag</th> 24517<th class="left">Description</th> 24518</tr></thead> 24519<tbody> 24520<tr> 24521<td>XO_STYLE_TEXT</td> 24522<td>Traditional text output</td> --- 15 unchanged lines hidden (view full) --- 24538</div> 24539<div class="content"> 24540<h4 id="doc_section_3_1_4_2"> 24541<div class="self-section-number"> 24542<a href="#doc_section_3_1_4_2">3.1.4.2</a>�</div> 24543<a id="xo_set_style_name" href="#xo_set_style_name">xo_set_style_name</a> 24544</h4> 24545<p id="doc_section_3_1_4_2_p_1">The xo_set_style_name() can be used to set the style based on a name encoded as a string:</p> |
| 24420<div id="doc_figure_u.85"></div> <pre> | 24546<div id="doc_figure_u.90"></div> <pre> |
| 24421 int xo_set_style_name (xo_handle_t *xop, const char *style); 24422 </pre> <p id="doc_section_3_1_4_2_p_3">The name can be any of the styles: "text", "xml", "json", or "html".</p> | 24547 int xo_set_style_name (xo_handle_t *xop, const char *style); 24548 </pre> <p id="doc_section_3_1_4_2_p_3">The name can be any of the styles: "text", "xml", "json", or "html".</p> |
| 24423<div id="doc_figure_u.86"></div> <pre> | 24549<div id="doc_figure_u.91"></div> <pre> |
| 24424 EXAMPLE: 24425 xo_set_style_name(NULL, "html"); 24426 </pre> </div> 24427</div> 24428<div class="content"> 24429<h3 id="doc_section_3_1_5"> 24430<div class="self-section-number"> 24431<a href="#doc_section_3_1_5">3.1.5</a>�</div> 24432<a id="xo_set_flags" href="#xo_set_flags">xo_set_flags</a> 24433</h3> 24434<p id="doc_section_3_1_5_p_1">To set the flags, use the xo_set_flags() function:</p> | 24550 EXAMPLE: 24551 xo_set_style_name(NULL, "html"); 24552 </pre> </div> 24553</div> 24554<div class="content"> 24555<h3 id="doc_section_3_1_5"> 24556<div class="self-section-number"> 24557<a href="#doc_section_3_1_5">3.1.5</a>�</div> 24558<a id="xo_set_flags" href="#xo_set_flags">xo_set_flags</a> 24559</h3> 24560<p id="doc_section_3_1_5_p_1">To set the flags, use the xo_set_flags() function:</p> |
| 24435<div id="doc_figure_u.87"></div> <pre> | 24561<div id="doc_figure_u.92"></div> <pre> |
| 24436 void xo_set_flags(xo_handle_t *xop, unsigned flags); 24437 </pre> <p id="doc_section_3_1_5_p_3">To use the default handle, pass a NULL handle:</p> | 24562 void xo_set_flags(xo_handle_t *xop, unsigned flags); 24563 </pre> <p id="doc_section_3_1_5_p_3">To use the default handle, pass a NULL handle:</p> |
| 24438<div id="doc_figure_u.88"></div> <pre> | 24564<div id="doc_figure_u.93"></div> <pre> |
| 24439 xo_set_style(NULL, XO_STYLE_XML); 24440 </pre> <p id="doc_section_3_1_5_p_5">Section Contents: </p> 24441<ul> 24442<li><a href="#flags" title="Flags (XOF_*)">Section�3.1.5.1</a></li> 24443<li><a href="#xo_clear_flags" title="xo_clear_flags">Section�3.1.5.2</a></li> 24444<li><a href="#xo_set_options" title="xo_set_options">Section�3.1.5.3</a></li> 24445</ul> 24446<div class="content"> 24447<h4 id="doc_section_3_1_5_1"> 24448<div class="self-section-number"> 24449<a href="#doc_section_3_1_5_1">3.1.5.1</a>�</div> 24450<a id="flags" href="#flags">Flags (XOF_*)</a> 24451</h4> 24452<p id="doc_section_3_1_5_1_p_1">The set of valid flags include:</p> | 24565 xo_set_style(NULL, XO_STYLE_XML); 24566 </pre> <p id="doc_section_3_1_5_p_5">Section Contents: </p> 24567<ul> 24568<li><a href="#flags" title="Flags (XOF_*)">Section�3.1.5.1</a></li> 24569<li><a href="#xo_clear_flags" title="xo_clear_flags">Section�3.1.5.2</a></li> 24570<li><a href="#xo_set_options" title="xo_set_options">Section�3.1.5.3</a></li> 24571</ul> 24572<div class="content"> 24573<h4 id="doc_section_3_1_5_1"> 24574<div class="self-section-number"> 24575<a href="#doc_section_3_1_5_1">3.1.5.1</a>�</div> 24576<a id="flags" href="#flags">Flags (XOF_*)</a> 24577</h4> 24578<p id="doc_section_3_1_5_1_p_1">The set of valid flags include:</p> |
| 24453<div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24579<div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24454<thead><tr> 24455<th class="left">Flag</th> 24456<th class="left">Description</th> 24457</tr></thead> 24458<tbody> 24459<tr> 24460<td>XOF_CLOSE_FP</td> 24461<td>Close file pointer on xo_destroy()</td> --- 61 unchanged lines hidden (view full) --- 24523</tbody> 24524</table></div> 24525<p id="doc_section_3_1_5_1_p_2">The XOF_CLOSE_FP flag will trigger the call of the close_func (provided via xo_set_writer()) when the handle is destroyed.</p> 24526<p id="doc_section_3_1_5_1_p_3">The XOF_COLOR flag enables color and effects in output regardless of output device, while the XOF_COLOR_ALLOWED flag allows color and effects only if the output device is a terminal.</p> 24527<p id="doc_section_3_1_5_1_p_4">The XOF_PRETTY flag requests 'pretty printing', which will trigger the addition of indentation and newlines to enhance the readability of XML, JSON, and HTML output. Text output is not affected.</p> 24528<p id="doc_section_3_1_5_1_p_5">The XOF_WARN flag requests that warnings will trigger diagnostic output (on standard error) when the library notices errors during operations, or with arguments to functions. Without warnings enabled, such conditions are ignored.</p> 24529<p id="doc_section_3_1_5_1_p_6">Warnings allow developers to debug their interaction with libxo. The function "xo_failure" can used as a breakpoint for a debugger, regardless of whether warnings are enabled.</p> 24530<p id="doc_section_3_1_5_1_p_7">If the style is XO_STYLE_HTML, the following additional flags can be used:</p> | 24580<thead><tr> 24581<th class="left">Flag</th> 24582<th class="left">Description</th> 24583</tr></thead> 24584<tbody> 24585<tr> 24586<td>XOF_CLOSE_FP</td> 24587<td>Close file pointer on xo_destroy()</td> --- 61 unchanged lines hidden (view full) --- 24649</tbody> 24650</table></div> 24651<p id="doc_section_3_1_5_1_p_2">The XOF_CLOSE_FP flag will trigger the call of the close_func (provided via xo_set_writer()) when the handle is destroyed.</p> 24652<p id="doc_section_3_1_5_1_p_3">The XOF_COLOR flag enables color and effects in output regardless of output device, while the XOF_COLOR_ALLOWED flag allows color and effects only if the output device is a terminal.</p> 24653<p id="doc_section_3_1_5_1_p_4">The XOF_PRETTY flag requests 'pretty printing', which will trigger the addition of indentation and newlines to enhance the readability of XML, JSON, and HTML output. Text output is not affected.</p> 24654<p id="doc_section_3_1_5_1_p_5">The XOF_WARN flag requests that warnings will trigger diagnostic output (on standard error) when the library notices errors during operations, or with arguments to functions. Without warnings enabled, such conditions are ignored.</p> 24655<p id="doc_section_3_1_5_1_p_6">Warnings allow developers to debug their interaction with libxo. The function "xo_failure" can used as a breakpoint for a debugger, regardless of whether warnings are enabled.</p> 24656<p id="doc_section_3_1_5_1_p_7">If the style is XO_STYLE_HTML, the following additional flags can be used:</p> |
| 24531<div id="doc_table_u.11"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24657<div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24532<thead><tr> 24533<th class="left">Flag</th> 24534<th class="left">Description</th> 24535</tr></thead> 24536<tbody> 24537<tr> 24538<td>XOF_XPATH</td> 24539<td>Emit "data-xpath" attributes</td> 24540</tr> 24541<tr> 24542<td>XOF_INFO</td> 24543<td>Emit additional info fields</td> 24544</tr> 24545</tbody> 24546</table></div> 24547<p id="doc_section_3_1_5_1_p_8">The XOF_XPATH flag enables the emission of XPath expressions detailing the hierarchy of XML elements used to encode the data field, if the XPATH style of output were requested.</p> 24548<p id="doc_section_3_1_5_1_p_9">The XOF_INFO flag encodes additional informational fields for HTML output. See <a href="#info" title="Field Information (xo_info_t)">Section�3.4.4</a> for details.</p> 24549<p id="doc_section_3_1_5_1_p_10">If the style is XO_STYLE_XML, the following additional flags can be used:</p> | 24658<thead><tr> 24659<th class="left">Flag</th> 24660<th class="left">Description</th> 24661</tr></thead> 24662<tbody> 24663<tr> 24664<td>XOF_XPATH</td> 24665<td>Emit "data-xpath" attributes</td> 24666</tr> 24667<tr> 24668<td>XOF_INFO</td> 24669<td>Emit additional info fields</td> 24670</tr> 24671</tbody> 24672</table></div> 24673<p id="doc_section_3_1_5_1_p_8">The XOF_XPATH flag enables the emission of XPath expressions detailing the hierarchy of XML elements used to encode the data field, if the XPATH style of output were requested.</p> 24674<p id="doc_section_3_1_5_1_p_9">The XOF_INFO flag encodes additional informational fields for HTML output. See <a href="#info" title="Field Information (xo_info_t)">Section�3.4.4</a> for details.</p> 24675<p id="doc_section_3_1_5_1_p_10">If the style is XO_STYLE_XML, the following additional flags can be used:</p> |
| 24550<div id="doc_table_u.12"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 24676<div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24551<thead><tr> 24552<th class="left">Flag</th> 24553<th class="left">Description</th> 24554</tr></thead> 24555<tbody><tr> 24556<td>XOF_KEYS</td> 24557<td>Flag 'key' fields for xml</td> 24558</tr></tbody> 24559</table></div> 24560<p id="doc_section_3_1_5_1_p_11">The XOF_KEYS flag adds 'key' attribute to the XML encoding for field definitions that use the 'k' modifier. The key attribute has the value "key":</p> | 24677<thead><tr> 24678<th class="left">Flag</th> 24679<th class="left">Description</th> 24680</tr></thead> 24681<tbody><tr> 24682<td>XOF_KEYS</td> 24683<td>Flag 'key' fields for xml</td> 24684</tr></tbody> 24685</table></div> 24686<p id="doc_section_3_1_5_1_p_11">The XOF_KEYS flag adds 'key' attribute to the XML encoding for field definitions that use the 'k' modifier. The key attribute has the value "key":</p> |
| 24561<div id="doc_figure_u.89"></div> <pre> | 24687<div id="doc_figure_u.94"></div> <pre> |
| 24562 xo_emit("{k:name}", item); 24563 24564 XML: 24565 <name key="key">truck</name> 24566 </pre> </div> 24567<div class="content"> 24568<h4 id="doc_section_3_1_5_2"> 24569<div class="self-section-number"> 24570<a href="#doc_section_3_1_5_2">3.1.5.2</a>�</div> 24571<a id="xo_clear_flags" href="#xo_clear_flags">xo_clear_flags</a> 24572</h4> 24573<p id="doc_section_3_1_5_2_p_1">The xo_clear_flags() function turns off the given flags in a specific handle.</p> | 24688 xo_emit("{k:name}", item); 24689 24690 XML: 24691 <name key="key">truck</name> 24692 </pre> </div> 24693<div class="content"> 24694<h4 id="doc_section_3_1_5_2"> 24695<div class="self-section-number"> 24696<a href="#doc_section_3_1_5_2">3.1.5.2</a>�</div> 24697<a id="xo_clear_flags" href="#xo_clear_flags">xo_clear_flags</a> 24698</h4> 24699<p id="doc_section_3_1_5_2_p_1">The xo_clear_flags() function turns off the given flags in a specific handle.</p> |
| 24574<div id="doc_figure_u.90"></div> <pre> | 24700<div id="doc_figure_u.95"></div> <pre> |
| 24575 void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags); 24576 </pre> </div> 24577<div class="content"> 24578<h4 id="doc_section_3_1_5_3"> 24579<div class="self-section-number"> 24580<a href="#doc_section_3_1_5_3">3.1.5.3</a>�</div> 24581<a id="xo_set_options" href="#xo_set_options">xo_set_options</a> 24582</h4> 24583<p id="doc_section_3_1_5_3_p_1">The xo_set_options() function accepts a comma-separated list of styles and flags and enables them for a specific handle.</p> | 24701 void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags); 24702 </pre> </div> 24703<div class="content"> 24704<h4 id="doc_section_3_1_5_3"> 24705<div class="self-section-number"> 24706<a href="#doc_section_3_1_5_3">3.1.5.3</a>�</div> 24707<a id="xo_set_options" href="#xo_set_options">xo_set_options</a> 24708</h4> 24709<p id="doc_section_3_1_5_3_p_1">The xo_set_options() function accepts a comma-separated list of styles and flags and enables them for a specific handle.</p> |
| 24584<div id="doc_figure_u.91"></div> <pre> | 24710<div id="doc_figure_u.96"></div> <pre> |
| 24585 int xo_set_options (xo_handle_t *xop, const char *input); | 24711 int xo_set_options (xo_handle_t *xop, const char *input); |
| 24586 </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> | 24712 </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> |
| 24587</div> 24588</div> 24589<div class="content"> 24590<h3 id="doc_section_3_1_6"> 24591<div class="self-section-number"> 24592<a href="#doc_section_3_1_6">3.1.6</a>�</div> 24593<a id="xo_destroy" href="#xo_destroy">xo_destroy</a> 24594</h3> 24595<p id="doc_section_3_1_6_p_1">The xo_destroy function releases a handle and any resources it is using. Calling xo_destroy with a NULL handle will release any resources associated with the default handle.</p> | 24713</div> 24714</div> 24715<div class="content"> 24716<h3 id="doc_section_3_1_6"> 24717<div class="self-section-number"> 24718<a href="#doc_section_3_1_6">3.1.6</a>�</div> 24719<a id="xo_destroy" href="#xo_destroy">xo_destroy</a> 24720</h3> 24721<p id="doc_section_3_1_6_p_1">The xo_destroy function releases a handle and any resources it is using. Calling xo_destroy with a NULL handle will release any resources associated with the default handle.</p> |
| 24596<div id="doc_figure_u.92"></div> <pre> | 24722<div id="doc_figure_u.97"></div> <pre> |
| 24597 void xo_destroy(xo_handle_t *xop); 24598 </pre> </div> 24599</div> 24600<div class="content"> 24601<h2 id="doc_section_3_2"> 24602<div class="self-section-number"> 24603<a href="#doc_section_3_2">3.2</a>�</div> 24604<a id="emitting-content-xo_emit" href="#emitting-content-xo_emit">Emitting Content (xo_emit)</a> 24605</h2> 24606<p id="doc_section_3_2_p_1">The following functions are used to emit output:</p> | 24723 void xo_destroy(xo_handle_t *xop); 24724 </pre> </div> 24725</div> 24726<div class="content"> 24727<h2 id="doc_section_3_2"> 24728<div class="self-section-number"> 24729<a href="#doc_section_3_2">3.2</a>�</div> 24730<a id="emitting-content-xo_emit" href="#emitting-content-xo_emit">Emitting Content (xo_emit)</a> 24731</h2> 24732<p id="doc_section_3_2_p_1">The following functions are used to emit output:</p> |
| 24607<div id="doc_figure_u.93"></div> <pre> | 24733<div id="doc_figure_u.98"></div> <pre> |
| 24608 int xo_emit (const char *fmt, ...); 24609 int xo_emit_h (xo_handle_t *xop, const char *fmt, ...); 24610 int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap); | 24734 int xo_emit (const char *fmt, ...); 24735 int xo_emit_h (xo_handle_t *xop, const char *fmt, ...); 24736 int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap); |
| 24611 </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> | 24737 </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> |
| 24612<p id="doc_section_3_2_p_4">The remaining arguments to xo_emit() and xo_emit_h() are a set of arguments corresponding to the fields in the format string. Care must be taken to ensure the argument types match the fields in the format string, since an inappropriate cast can ruin your day. The vap argument to xo_emit_hv() points to a variable argument list that can be used to retrieve arguments via va_arg().</p> 24613<p id="doc_section_3_2_p_5">Section Contents: </p> 24614<ul> | 24738<p id="doc_section_3_2_p_4">The remaining arguments to xo_emit() and xo_emit_h() are a set of arguments corresponding to the fields in the format string. Care must be taken to ensure the argument types match the fields in the format string, since an inappropriate cast can ruin your day. The vap argument to xo_emit_hv() points to a variable argument list that can be used to retrieve arguments via va_arg().</p> 24739<p id="doc_section_3_2_p_5">Section Contents: </p> 24740<ul> |
| 24615<li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.1</a></li> 24616<li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.2</a></li> 24617<li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.3</a></li> | 24741<li><a href="#xo_emit_field" title="Single Field Emitting Functions (xo_emit_field)">Section�3.2.1</a></li> 24742<li><a href="#xo_attr" title="Attributes (xo_attr)">Section�3.2.2</a></li> 24743<li><a href="#flushing-output-xo_flush" title="Flushing Output (xo_flush)">Section�3.2.3</a></li> 24744<li><a href="#finishing-output-xo_finish" title="Finishing Output (xo_finish)">Section�3.2.4</a></li> |
| 24618</ul> 24619<div class="content"> 24620<h3 id="doc_section_3_2_1"> 24621<div class="self-section-number"> 24622<a href="#doc_section_3_2_1">3.2.1</a>�</div> | 24745</ul> 24746<div class="content"> 24747<h3 id="doc_section_3_2_1"> 24748<div class="self-section-number"> 24749<a href="#doc_section_3_2_1">3.2.1</a>�</div> |
| 24750<a id="xo_emit_field" href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a> 24751</h3> 24752<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> 24753<div id="doc_figure_u.99"></div> <pre> 24754 int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, 24755 const char *contents, const char *fmt, 24756 const char *efmt, va_list vap); 24757 24758 int xo_emit_field_h (xo_handle_t *xop, const char *rolmod, 24759 const char *contents, const char *fmt, 24760 const char *efmt, ...); 24761 24762 int xo_emit_field (const char *rolmod, const char *contents, 24763 const char *fmt, const char *efmt, ...); 24764 </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> 24765<div id="doc_figure_u.100"></div> <pre> 24766 xo_emit("T", "Host name is ", NULL, NULL); 24767 xo_emit("V", "host-name", NULL, NULL, host-name); 24768 </pre> </div> 24769<div class="content"> 24770<h3 id="doc_section_3_2_2"> 24771<div class="self-section-number"> 24772<a href="#doc_section_3_2_2">3.2.2</a>�</div> |
|
| 24623<a id="xo_attr" href="#xo_attr">Attributes (xo_attr)</a> 24624</h3> | 24773<a id="xo_attr" href="#xo_attr">Attributes (xo_attr)</a> 24774</h3> |
| 24625<p id="doc_section_3_2_1_p_1">The xo_attr() function emits attributes for the XML output style.</p> 24626<div id="doc_figure_u.94"></div> <pre> | 24775<p id="doc_section_3_2_2_p_1">The xo_attr() function emits attributes for the XML output style.</p> 24776<div id="doc_figure_u.101"></div> <pre> |
| 24627 int xo_attr (const char *name, const char *fmt, ...); 24628 int xo_attr_h (xo_handle_t *xop, const char *name, 24629 const char *fmt, ...); 24630 int xo_attr_hv (xo_handle_t *xop, const char *name, 24631 const char *fmt, va_list vap); | 24777 int xo_attr (const char *name, const char *fmt, ...); 24778 int xo_attr_h (xo_handle_t *xop, const char *name, 24779 const char *fmt, ...); 24780 int xo_attr_hv (xo_handle_t *xop, const char *name, 24781 const char *fmt, va_list vap); |
| 24632 </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> 24633<div id="doc_figure_u.95"></div> <pre> | 24782 </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> 24783<div id="doc_figure_u.102"></div> <pre> |
| 24634 EXAMPLE: 24635 xo_attr("seconds", "%ld", (unsigned long) login_time); 24636 struct tm *tmp = localtime(login_time); 24637 strftime(buf, sizeof(buf), "%R", tmp); 24638 xo_emit("Logged in at {:login-time}\n", buf); 24639 XML: 24640 <login-time seconds="1408336270">00:14</login-time> | 24784 EXAMPLE: 24785 xo_attr("seconds", "%ld", (unsigned long) login_time); 24786 struct tm *tmp = localtime(login_time); 24787 strftime(buf, sizeof(buf), "%R", tmp); 24788 xo_emit("Logged in at {:login-time}\n", buf); 24789 XML: 24790 <login-time seconds="1408336270">00:14</login-time> |
| 24641 </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> 24642<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> | 24791 </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> 24792<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> |
| 24643</div> 24644<div class="content"> | 24793</div> 24794<div class="content"> |
| 24645<h3 id="doc_section_3_2_2"> | 24795<h3 id="doc_section_3_2_3"> |
| 24646<div class="self-section-number"> | 24796<div class="self-section-number"> |
| 24647<a href="#doc_section_3_2_2">3.2.2</a>�</div> | 24797<a href="#doc_section_3_2_3">3.2.3</a>�</div> |
| 24648<a id="flushing-output-xo_flush" href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a> 24649</h3> | 24798<a id="flushing-output-xo_flush" href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a> 24799</h3> |
| 24650<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> 24651<div id="doc_figure_u.96"></div> <pre> | 24800<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> 24801<div id="doc_figure_u.103"></div> <pre> |
| 24652 void xo_flush (void); 24653 void xo_flush_h (xo_handle_t *xop); | 24802 void xo_flush (void); 24803 void xo_flush_h (xo_handle_t *xop); |
| 24654 </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> | 24804 </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> |
| 24655</div> 24656<div class="content"> | 24805</div> 24806<div class="content"> |
| 24657<h3 id="doc_section_3_2_3"> | 24807<h3 id="doc_section_3_2_4"> |
| 24658<div class="self-section-number"> | 24808<div class="self-section-number"> |
| 24659<a href="#doc_section_3_2_3">3.2.3</a>�</div> | 24809<a href="#doc_section_3_2_4">3.2.4</a>�</div> |
| 24660<a id="finishing-output-xo_finish" href="#finishing-output-xo_finish">Finishing Output (xo_finish)</a> 24661</h3> | 24810<a id="finishing-output-xo_finish" href="#finishing-output-xo_finish">Finishing Output (xo_finish)</a> 24811</h3> |
| 24662<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> 24663<div id="doc_figure_u.97"></div> <pre> | 24812<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> 24813<div id="doc_figure_u.104"></div> <pre> |
| 24664 int xo_finish (void); 24665 int xo_finish_h (xo_handle_t *xop); 24666 void xo_finish_atexit (void); | 24814 int xo_finish (void); 24815 int xo_finish_h (xo_handle_t *xop); 24816 void xo_finish_atexit (void); |
| 24667 </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> 24668<p id="doc_section_3_2_3_p_4">xo_finish_atexit is suitable for use with atexit(3).</p> | 24817 </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> 24818<p id="doc_section_3_2_4_p_4">xo_finish_atexit is suitable for use with atexit(3).</p> |
| 24669</div> 24670</div> 24671<div class="content"> 24672<h2 id="doc_section_3_3"> 24673<div class="self-section-number"> 24674<a href="#doc_section_3_3">3.3</a>�</div> 24675<a id="emitting-hierarchy" href="#emitting-hierarchy">Emitting Hierarchy</a> 24676</h2> 24677<p id="doc_section_3_3_p_1">libxo represents to types of hierarchy: containers and lists. A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope.</p> 24678<p id="doc_section_3_3_p_2">To create a container, use the xo_open_container and xo_close_container functions:</p> | 24819</div> 24820</div> 24821<div class="content"> 24822<h2 id="doc_section_3_3"> 24823<div class="self-section-number"> 24824<a href="#doc_section_3_3">3.3</a>�</div> 24825<a id="emitting-hierarchy" href="#emitting-hierarchy">Emitting Hierarchy</a> 24826</h2> 24827<p id="doc_section_3_3_p_1">libxo represents to types of hierarchy: containers and lists. A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope.</p> 24828<p id="doc_section_3_3_p_2">To create a container, use the xo_open_container and xo_close_container functions:</p> |
| 24679<div id="doc_figure_u.98"></div> <pre> | 24829<div id="doc_figure_u.105"></div> <pre> |
| 24680 int xo_open_container (const char *name); 24681 int xo_open_container_h (xo_handle_t *xop, const char *name); 24682 int xo_open_container_hd (xo_handle_t *xop, const char *name); 24683 int xo_open_container_d (const char *name); 24684 24685 int xo_close_container (const char *name); 24686 int xo_close_container_h (xo_handle_t *xop, const char *name); 24687 int xo_close_container_hd (xo_handle_t *xop); 24688 int xo_close_container_d (void); 24689 </pre> <p id="doc_section_3_3_p_4">The name parameter gives the name of the container, encoded in UTF-8. Since ASCII is a proper subset of UTF-8, traditional C strings can be used directly.</p> 24690<p id="doc_section_3_3_p_5">The close functions with the "_d" suffix are used in "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by libxo to allow the caller to avoid keeping track of the open container name.</p> 24691<p id="doc_section_3_3_p_6">Use the XOF_WARN flag to generate a warning if the name given on the close does not match the current open container.</p> 24692<p id="doc_section_3_3_p_7">For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the XOF_XPATH flag is set.</p> | 24830 int xo_open_container (const char *name); 24831 int xo_open_container_h (xo_handle_t *xop, const char *name); 24832 int xo_open_container_hd (xo_handle_t *xop, const char *name); 24833 int xo_open_container_d (const char *name); 24834 24835 int xo_close_container (const char *name); 24836 int xo_close_container_h (xo_handle_t *xop, const char *name); 24837 int xo_close_container_hd (xo_handle_t *xop); 24838 int xo_close_container_d (void); 24839 </pre> <p id="doc_section_3_3_p_4">The name parameter gives the name of the container, encoded in UTF-8. Since ASCII is a proper subset of UTF-8, traditional C strings can be used directly.</p> 24840<p id="doc_section_3_3_p_5">The close functions with the "_d" suffix are used in "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by libxo to allow the caller to avoid keeping track of the open container name.</p> 24841<p id="doc_section_3_3_p_6">Use the XOF_WARN flag to generate a warning if the name given on the close does not match the current open container.</p> 24842<p id="doc_section_3_3_p_7">For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the XOF_XPATH flag is set.</p> |
| 24693<div id="doc_figure_u.99"></div> <pre> | 24843<div id="doc_figure_u.106"></div> <pre> |
| 24694 EXAMPLE: 24695 xo_open_container("system"); 24696 xo_emit("The host name is {:host-name}\n", hn); 24697 xo_close_container("system"); 24698 XML: 24699 <system><host-name>foo</host-name></system> 24700 </pre> <p id="doc_section_3_3_p_9">Section Contents: </p> 24701<ul><li><a href="#lists-and-instances-2" title="Lists and Instances">Section�3.3.1</a></li></ul> 24702<div class="content"> 24703<h3 id="doc_section_3_3_1"> 24704<div class="self-section-number"> 24705<a href="#doc_section_3_3_1">3.3.1</a>�</div> 24706<a id="lists-and-instances-2" href="#lists-and-instances-2">Lists and Instances</a> 24707</h3> 24708<p id="doc_section_3_3_1_p_1">Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance.</p> 24709<p id="doc_section_3_3_1_p_2">The name given to all calls must be identical, and it is strongly suggested that the name be singular, not plural, as a matter of style and usage expectations.</p> | 24844 EXAMPLE: 24845 xo_open_container("system"); 24846 xo_emit("The host name is {:host-name}\n", hn); 24847 xo_close_container("system"); 24848 XML: 24849 <system><host-name>foo</host-name></system> 24850 </pre> <p id="doc_section_3_3_p_9">Section Contents: </p> 24851<ul><li><a href="#lists-and-instances-2" title="Lists and Instances">Section�3.3.1</a></li></ul> 24852<div class="content"> 24853<h3 id="doc_section_3_3_1"> 24854<div class="self-section-number"> 24855<a href="#doc_section_3_3_1">3.3.1</a>�</div> 24856<a id="lists-and-instances-2" href="#lists-and-instances-2">Lists and Instances</a> 24857</h3> 24858<p id="doc_section_3_3_1_p_1">Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance.</p> 24859<p id="doc_section_3_3_1_p_2">The name given to all calls must be identical, and it is strongly suggested that the name be singular, not plural, as a matter of style and usage expectations.</p> |
| 24710<div id="doc_figure_u.100"></div> <pre> | 24860<div id="doc_figure_u.107"></div> <pre> |
| 24711 EXAMPLE: 24712 xo_open_list("user"); 24713 for (i = 0; i < num_users; i++) { 24714 xo_open_instance("user"); 24715 xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n", 24716 pw[i].pw_name, pw[i].pw_uid, 24717 pw[i].pw_gid, pw[i].pw_dir); 24718 xo_close_instance("user"); --- 52 unchanged lines hidden (view full) --- 24771</ul> 24772<div class="content"> 24773<h3 id="doc_section_3_4_1"> 24774<div class="self-section-number"> 24775<a href="#doc_section_3_4_1">3.4.1</a>�</div> 24776<a id="xo_parse_args" href="#xo_parse_args">Parsing Command-line Arguments (xo_parse_args)</a> 24777</h3> 24778<p id="doc_section_3_4_1_p_1">The xo_parse_args() function is used to process a program's arguments. libxo-specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned.</p> | 24861 EXAMPLE: 24862 xo_open_list("user"); 24863 for (i = 0; i < num_users; i++) { 24864 xo_open_instance("user"); 24865 xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n", 24866 pw[i].pw_name, pw[i].pw_uid, 24867 pw[i].pw_gid, pw[i].pw_dir); 24868 xo_close_instance("user"); --- 52 unchanged lines hidden (view full) --- 24921</ul> 24922<div class="content"> 24923<h3 id="doc_section_3_4_1"> 24924<div class="self-section-number"> 24925<a href="#doc_section_3_4_1">3.4.1</a>�</div> 24926<a id="xo_parse_args" href="#xo_parse_args">Parsing Command-line Arguments (xo_parse_args)</a> 24927</h3> 24928<p id="doc_section_3_4_1_p_1">The xo_parse_args() function is used to process a program's arguments. libxo-specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned.</p> |
| 24779<div id="doc_figure_u.101"></div> <pre> | 24929<div id="doc_figure_u.108"></div> <pre> |
| 24780 argc = xo_parse_args(argc, argv); 24781 if (argc < 0) 24782 exit(EXIT_FAILURE); | 24930 argc = xo_parse_args(argc, argv); 24931 if (argc < 0) 24932 exit(EXIT_FAILURE); |
| 24783 </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> | 24933 </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> |
| 24784</div> 24785<div class="content"> 24786<h3 id="doc_section_3_4_2"> 24787<div class="self-section-number"> 24788<a href="#doc_section_3_4_2">3.4.2</a>�</div> 24789<a id="xo_set_program" href="#xo_set_program">xo_set_program</a> 24790</h3> 24791<p id="doc_section_3_4_2_p_1">The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value.</p> | 24934</div> 24935<div class="content"> 24936<h3 id="doc_section_3_4_2"> 24937<div class="self-section-number"> 24938<a href="#doc_section_3_4_2">3.4.2</a>�</div> 24939<a id="xo_set_program" href="#xo_set_program">xo_set_program</a> 24940</h3> 24941<p id="doc_section_3_4_2_p_1">The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value.</p> |
| 24792<div id="doc_figure_u.102"></div> <pre> | 24942<div id="doc_figure_u.109"></div> <pre> |
| 24793 xo_set_program(argv[0]); 24794 </pre> <p id="doc_section_3_4_2_p_3">Note that the value is not copied, so the memory passed to xo_set_program (and xo_parse_args) must be maintained by the caller.</p> 24795</div> 24796<div class="content"> 24797<h3 id="doc_section_3_4_3"> 24798<div class="self-section-number"> 24799<a href="#doc_section_3_4_3">3.4.3</a>�</div> 24800<a id="xo_set_version" href="#xo_set_version">xo_set_version</a> 24801</h3> 24802<p id="doc_section_3_4_3_p_1">The xo_set_version function records a version number to be emitted as part of the data for encoding styles (XML and JSON). This version number is suitable for tracking changes in the content, allowing a user of the data to discern which version of the data model is in use.</p> | 24943 xo_set_program(argv[0]); 24944 </pre> <p id="doc_section_3_4_2_p_3">Note that the value is not copied, so the memory passed to xo_set_program (and xo_parse_args) must be maintained by the caller.</p> 24945</div> 24946<div class="content"> 24947<h3 id="doc_section_3_4_3"> 24948<div class="self-section-number"> 24949<a href="#doc_section_3_4_3">3.4.3</a>�</div> 24950<a id="xo_set_version" href="#xo_set_version">xo_set_version</a> 24951</h3> 24952<p id="doc_section_3_4_3_p_1">The xo_set_version function records a version number to be emitted as part of the data for encoding styles (XML and JSON). This version number is suitable for tracking changes in the content, allowing a user of the data to discern which version of the data model is in use.</p> |
| 24803<div id="doc_figure_u.103"></div> <pre> | 24953<div id="doc_figure_u.110"></div> <pre> |
| 24804 void xo_set_version (const char *version); 24805 void xo_set_version_h (xo_handle_t *xop, const char *version); 24806 </pre> </div> 24807<div class="content"> 24808<h3 id="doc_section_3_4_4"> 24809<div class="self-section-number"> 24810<a href="#doc_section_3_4_4">3.4.4</a>�</div> 24811<a id="info" href="#info">Field Information (xo_info_t)</a> 24812</h3> 24813<p id="doc_section_3_4_4_p_1">HTML data can include additional information in attributes that begin with "data‑". To enable this, three things must occur:</p> 24814<p id="doc_section_3_4_4_p_2">First the application must build an array of xo_info_t structures, one per tag. The array must be sorted by name, since libxo uses a binary search to find the entry that matches names from format instructions.</p> 24815<p id="doc_section_3_4_4_p_3">Second, the application must inform libxo about this information using the xo_set_info() call:</p> | 24954 void xo_set_version (const char *version); 24955 void xo_set_version_h (xo_handle_t *xop, const char *version); 24956 </pre> </div> 24957<div class="content"> 24958<h3 id="doc_section_3_4_4"> 24959<div class="self-section-number"> 24960<a href="#doc_section_3_4_4">3.4.4</a>�</div> 24961<a id="info" href="#info">Field Information (xo_info_t)</a> 24962</h3> 24963<p id="doc_section_3_4_4_p_1">HTML data can include additional information in attributes that begin with "data‑". To enable this, three things must occur:</p> 24964<p id="doc_section_3_4_4_p_2">First the application must build an array of xo_info_t structures, one per tag. The array must be sorted by name, since libxo uses a binary search to find the entry that matches names from format instructions.</p> 24965<p id="doc_section_3_4_4_p_3">Second, the application must inform libxo about this information using the xo_set_info() call:</p> |
| 24816<div id="doc_figure_u.104"></div> <pre> | 24966<div id="doc_figure_u.111"></div> <pre> |
| 24817 typedef struct xo_info_s { 24818 const char *xi_name; /* Name of the element */ 24819 const char *xi_type; /* Type of field */ 24820 const char *xi_help; /* Description of field */ 24821 } xo_info_t; 24822 24823 void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count); 24824 </pre> <p id="doc_section_3_4_4_p_5">Like other libxo calls, passing NULL for the handle tells libxo to use the default handle.</p> 24825<p id="doc_section_3_4_4_p_6">If the count is -1, libxo will count the elements of infop, but there must be an empty element at the end. More typically, the number is known to the application:</p> | 24967 typedef struct xo_info_s { 24968 const char *xi_name; /* Name of the element */ 24969 const char *xi_type; /* Type of field */ 24970 const char *xi_help; /* Description of field */ 24971 } xo_info_t; 24972 24973 void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count); 24974 </pre> <p id="doc_section_3_4_4_p_5">Like other libxo calls, passing NULL for the handle tells libxo to use the default handle.</p> 24975<p id="doc_section_3_4_4_p_6">If the count is -1, libxo will count the elements of infop, but there must be an empty element at the end. More typically, the number is known to the application:</p> |
| 24826<div id="doc_figure_u.105"></div> <pre> | 24976<div id="doc_figure_u.112"></div> <pre> |
| 24827 xo_info_t info[] = { 24828 { "in-stock", "number", "Number of items in stock" }, 24829 { "name", "string", "Name of the item" }, 24830 { "on-order", "number", "Number of items on order" }, 24831 { "sku", "string", "Stock Keeping Unit" }, 24832 { "sold", "number", "Number of items sold" }, 24833 }; 24834 int info_count = (sizeof(info) / sizeof(info[0])); 24835 ... 24836 xo_set_info(NULL, info, info_count); 24837 </pre> <p id="doc_section_3_4_4_p_8">Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the "‑‑libxo=info" command line argument.</p> 24838<p id="doc_section_3_4_4_p_9">The type and help values, if present, are emitted as the "data‑type" and "data‑help" attributes:</p> | 24977 xo_info_t info[] = { 24978 { "in-stock", "number", "Number of items in stock" }, 24979 { "name", "string", "Name of the item" }, 24980 { "on-order", "number", "Number of items on order" }, 24981 { "sku", "string", "Stock Keeping Unit" }, 24982 { "sold", "number", "Number of items sold" }, 24983 }; 24984 int info_count = (sizeof(info) / sizeof(info[0])); 24985 ... 24986 xo_set_info(NULL, info, info_count); 24987 </pre> <p id="doc_section_3_4_4_p_8">Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the "‑‑libxo=info" command line argument.</p> 24988<p id="doc_section_3_4_4_p_9">The type and help values, if present, are emitted as the "data‑type" and "data‑help" attributes:</p> |
| 24839<div id="doc_figure_u.106"></div> <pre> | 24989<div id="doc_figure_u.113"></div> <pre> |
| 24840 <div class="data" data-tag="sku" data-type="string" 24841 data-help="Stock Keeping Unit">GRO-000-533</div> 24842 </pre> </div> 24843<div class="content"> 24844<h3 id="doc_section_3_4_5"> 24845<div class="self-section-number"> 24846<a href="#doc_section_3_4_5">3.4.5</a>�</div> 24847<a id="memory-allocation" href="#memory-allocation">Memory Allocation</a> 24848</h3> 24849<p id="doc_section_3_4_5_p_1">The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available.</p> | 24990 <div class="data" data-tag="sku" data-type="string" 24991 data-help="Stock Keeping Unit">GRO-000-533</div> 24992 </pre> </div> 24993<div class="content"> 24994<h3 id="doc_section_3_4_5"> 24995<div class="self-section-number"> 24996<a href="#doc_section_3_4_5">3.4.5</a>�</div> 24997<a id="memory-allocation" href="#memory-allocation">Memory Allocation</a> 24998</h3> 24999<p id="doc_section_3_4_5_p_1">The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available.</p> |
| 24850<div id="doc_figure_u.107"></div> <pre> | 25000<div id="doc_figure_u.114"></div> <pre> |
| 24851 void xo_set_allocator (xo_realloc_func_t realloc_func, 24852 xo_free_func_t free_func); 24853 </pre> <p id="doc_section_3_4_5_p_3">realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment.</p> 24854<p id="doc_section_3_4_5_p_4">By default, the standard realloc() and free() functions are used.</p> 24855</div> 24856<div class="content"> 24857<h3 id="doc_section_3_4_6"> 24858<div class="self-section-number"> 24859<a href="#doc_section_3_4_6">3.4.6</a>�</div> 24860<a id="LIBXO_OPTIONS" href="#LIBXO_OPTIONS">LIBXO_OPTIONS</a> 24861</h3> 24862<p id="doc_section_3_4_6_p_1">The environment variable "LIBXO_OPTIONS" can be set to a string of options:</p> | 25001 void xo_set_allocator (xo_realloc_func_t realloc_func, 25002 xo_free_func_t free_func); 25003 </pre> <p id="doc_section_3_4_5_p_3">realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment.</p> 25004<p id="doc_section_3_4_5_p_4">By default, the standard realloc() and free() functions are used.</p> 25005</div> 25006<div class="content"> 25007<h3 id="doc_section_3_4_6"> 25008<div class="self-section-number"> 25009<a href="#doc_section_3_4_6">3.4.6</a>�</div> 25010<a id="LIBXO_OPTIONS" href="#LIBXO_OPTIONS">LIBXO_OPTIONS</a> 25011</h3> 25012<p id="doc_section_3_4_6_p_1">The environment variable "LIBXO_OPTIONS" can be set to a string of options:</p> |
| 24863<div id="doc_table_u.13"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25013<div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 24864<thead><tr> 24865<th class="left">Option</th> 24866<th class="left">Action</th> 24867</tr></thead> 24868<tbody> 24869<tr> 24870<td>c</td> 24871<td>Enable color/effects for TEXT/HTML</td> --- 52 unchanged lines hidden (view full) --- 24924</tr> 24925<tr> 24926<td>x</td> 24927<td>Enable XPath data (XOF_XPATH)</td> 24928</tr> 24929</tbody> 24930</table></div> 24931<p id="doc_section_3_4_6_p_2">For example, warnings can be enabled by:</p> | 25014<thead><tr> 25015<th class="left">Option</th> 25016<th class="left">Action</th> 25017</tr></thead> 25018<tbody> 25019<tr> 25020<td>c</td> 25021<td>Enable color/effects for TEXT/HTML</td> --- 52 unchanged lines hidden (view full) --- 25074</tr> 25075<tr> 25076<td>x</td> 25077<td>Enable XPath data (XOF_XPATH)</td> 25078</tr> 25079</tbody> 25080</table></div> 25081<p id="doc_section_3_4_6_p_2">For example, warnings can be enabled by:</p> |
| 24932<div id="doc_figure_u.108"></div> <pre> | 25082<div id="doc_figure_u.115"></div> <pre> |
| 24933 % env LIBXO_OPTIONS=W my-app 24934 </pre> <p id="doc_section_3_4_6_p_4">Complete HTML output can be generated with:</p> | 25083 % env LIBXO_OPTIONS=W my-app 25084 </pre> <p id="doc_section_3_4_6_p_4">Complete HTML output can be generated with:</p> |
| 24935<div id="doc_figure_u.109"></div> <pre> | 25085<div id="doc_figure_u.116"></div> <pre> |
| 24936 % env LIBXO_OPTIONS=HXI my-app 24937 </pre> <p id="doc_section_3_4_6_p_6">Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "‑‑libxo" option is preferable in most situations.</p> 24938</div> 24939<div class="content"> 24940<h3 id="doc_section_3_4_7"> 24941<div class="self-section-number"> 24942<a href="#doc_section_3_4_7">3.4.7</a>�</div> 24943<a id="errors-warnings-and-messages" href="#errors-warnings-and-messages">Errors, Warnings, and Messages</a> 24944</h3> 24945<p id="doc_section_3_4_7_p_1">Many programs make use of the standard library functions err() and warn() to generate errors and warnings for the user. libxo wants to pass that information via the current output style, and provides compatible functions to allow this:</p> | 25086 % env LIBXO_OPTIONS=HXI my-app 25087 </pre> <p id="doc_section_3_4_6_p_6">Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "‑‑libxo" option is preferable in most situations.</p> 25088</div> 25089<div class="content"> 25090<h3 id="doc_section_3_4_7"> 25091<div class="self-section-number"> 25092<a href="#doc_section_3_4_7">3.4.7</a>�</div> 25093<a id="errors-warnings-and-messages" href="#errors-warnings-and-messages">Errors, Warnings, and Messages</a> 25094</h3> 25095<p id="doc_section_3_4_7_p_1">Many programs make use of the standard library functions err() and warn() to generate errors and warnings for the user. libxo wants to pass that information via the current output style, and provides compatible functions to allow this:</p> |
| 24946<div id="doc_figure_u.110"></div> <pre> | 25096<div id="doc_figure_u.117"></div> <pre> |
| 24947 void xo_warn (const char *fmt, ...); 24948 void xo_warnx (const char *fmt, ...); 24949 void xo_warn_c (int code, const char *fmt, ...); 24950 void xo_warn_hc (xo_handle_t *xop, int code, 24951 const char *fmt, ...); 24952 void xo_err (int eval, const char *fmt, ...); 24953 void xo_errc (int eval, int code, const char *fmt, ...); 24954 void xo_errx (int eval, const char *fmt, ...); 24955 void xo_message (const char *fmt, ...); 24956 void xo_message_c (int code, const char *fmt, ...); 24957 void xo_message_hc (xo_handle_t *xop, int code, 24958 const char *fmt, ...); 24959 void xo_message_hcv (xo_handle_t *xop, int code, 24960 const char *fmt, va_list vap); 24961 </pre> <p id="doc_section_3_4_7_p_3">These functions display the program name, a colon, a formatted message based on the arguments, and then optionally a colon and an error message associated with either "errno" or the "code" parameter.</p> | 25097 void xo_warn (const char *fmt, ...); 25098 void xo_warnx (const char *fmt, ...); 25099 void xo_warn_c (int code, const char *fmt, ...); 25100 void xo_warn_hc (xo_handle_t *xop, int code, 25101 const char *fmt, ...); 25102 void xo_err (int eval, const char *fmt, ...); 25103 void xo_errc (int eval, int code, const char *fmt, ...); 25104 void xo_errx (int eval, const char *fmt, ...); 25105 void xo_message (const char *fmt, ...); 25106 void xo_message_c (int code, const char *fmt, ...); 25107 void xo_message_hc (xo_handle_t *xop, int code, 25108 const char *fmt, ...); 25109 void xo_message_hcv (xo_handle_t *xop, int code, 25110 const char *fmt, va_list vap); 25111 </pre> <p id="doc_section_3_4_7_p_3">These functions display the program name, a colon, a formatted message based on the arguments, and then optionally a colon and an error message associated with either "errno" or the "code" parameter.</p> |
| 24962<div id="doc_figure_u.111"></div> <pre> | 25112<div id="doc_figure_u.118"></div> <pre> |
| 24963 EXAMPLE: 24964 if (open(filename, O_RDONLY) < 0) 24965 xo_err(1, "cannot open file '%s'", filename); 24966 </pre> </div> 24967<div class="content"> 24968<h3 id="doc_section_3_4_8"> 24969<div class="self-section-number"> 24970<a href="#doc_section_3_4_8">3.4.8</a>�</div> 24971<a id="xo_error" href="#xo_error">xo_error</a> 24972</h3> 24973<p id="doc_section_3_4_8_p_1">The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements:</p> | 25113 EXAMPLE: 25114 if (open(filename, O_RDONLY) < 0) 25115 xo_err(1, "cannot open file '%s'", filename); 25116 </pre> </div> 25117<div class="content"> 25118<h3 id="doc_section_3_4_8"> 25119<div class="self-section-number"> 25120<a href="#doc_section_3_4_8">3.4.8</a>�</div> 25121<a id="xo_error" href="#xo_error">xo_error</a> 25122</h3> 25123<p id="doc_section_3_4_8_p_1">The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements:</p> |
| 24974<div id="doc_figure_u.112"></div> <pre> | 25124<div id="doc_figure_u.119"></div> <pre> |
| 24975 EXAMPLE:: 24976 xo_error("Does not %s", "compute"); 24977 XML:: 24978 <error><message>Does not compute</message></error> 24979 JSON:: 24980 "error": { "message": "Does not compute" } 24981 </pre> </div> 24982<div class="content"> 24983<h3 id="doc_section_3_4_9"> 24984<div class="self-section-number"> 24985<a href="#doc_section_3_4_9">3.4.9</a>�</div> 24986<a id="xo_no_setlocale" href="#xo_no_setlocale">xo_no_setlocale</a> 24987</h3> 24988<p id="doc_section_3_4_9_p_1">libxo automatically initializes the locale based on setting of the environment variables LC_CTYPE, LANG, and LC_ALL. The first of this list of variables is used and if none of the variables, the locale defaults to "UTF‑8". The caller may wish to avoid this behavior, and can do so by calling the xo_no_setlocale() function.</p> | 25125 EXAMPLE:: 25126 xo_error("Does not %s", "compute"); 25127 XML:: 25128 <error><message>Does not compute</message></error> 25129 JSON:: 25130 "error": { "message": "Does not compute" } 25131 </pre> </div> 25132<div class="content"> 25133<h3 id="doc_section_3_4_9"> 25134<div class="self-section-number"> 25135<a href="#doc_section_3_4_9">3.4.9</a>�</div> 25136<a id="xo_no_setlocale" href="#xo_no_setlocale">xo_no_setlocale</a> 25137</h3> 25138<p id="doc_section_3_4_9_p_1">libxo automatically initializes the locale based on setting of the environment variables LC_CTYPE, LANG, and LC_ALL. The first of this list of variables is used and if none of the variables, the locale defaults to "UTF‑8". The caller may wish to avoid this behavior, and can do so by calling the xo_no_setlocale() function.</p> |
| 24989<div id="doc_figure_u.113"></div> <pre> | 25139<div id="doc_figure_u.120"></div> <pre> |
| 24990 void xo_no_setlocale (void); 24991 </pre> </div> 24992</div> 24993<div class="content"> 24994<h2 id="doc_section_3_5"> 24995<div class="self-section-number"> 24996<a href="#doc_section_3_5">3.5</a>�</div> 24997<a id="emitting-syslog-messages" href="#emitting-syslog-messages">Emitting syslog Messages</a> 24998</h2> 24999<p id="doc_section_3_5_p_1">syslog is the system logging facility used throughout the unix world. Messages are sent from commands, applications, and daemons to a hierarchy of servers, where they are filtered, saved, and forwarded based on configuration behaviors.</p> 25000<p id="doc_section_3_5_p_2">syslog is an older protocol, originally documented only in source code. By the time RFC 3164 published, variation and mutation left the leading "<pri>" string as only common content. RFC 5424 defines a new version (version 1) of syslog and introduces structured data into the messages. Structured data is a set of name/value pairs transmitted distinctly alongside the traditional text message, allowing filtering on precise values instead of regular expressions.</p> 25001<p id="doc_section_3_5_p_3">These name/value pairs are scoped by a two-part identifier; an enterprise identifier names the party responsible for the message catalog and a name identifying that message. Enterprise IDs are defined by IANA, the Internet Assigned Numbers Authority:</p> 25002<p id="doc_section_3_5_p_4">https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers</p> 25003<p id="doc_section_3_5_p_5">Use the <a href="#xo_set_syslog_enterprise_id" title="xo_set_syslog_enterprise_id">Section�3.5.3.5</a>() function to set the Enterprise ID, as needed.</p> 25004<p id="doc_section_3_5_p_6">The message name should follow the conventions in <a href="#good-field-names" title="What makes a good field name?">Section�8.1.3</a>, as should the fields within the message.</p> | 25140 void xo_no_setlocale (void); 25141 </pre> </div> 25142</div> 25143<div class="content"> 25144<h2 id="doc_section_3_5"> 25145<div class="self-section-number"> 25146<a href="#doc_section_3_5">3.5</a>�</div> 25147<a id="emitting-syslog-messages" href="#emitting-syslog-messages">Emitting syslog Messages</a> 25148</h2> 25149<p id="doc_section_3_5_p_1">syslog is the system logging facility used throughout the unix world. Messages are sent from commands, applications, and daemons to a hierarchy of servers, where they are filtered, saved, and forwarded based on configuration behaviors.</p> 25150<p id="doc_section_3_5_p_2">syslog is an older protocol, originally documented only in source code. By the time RFC 3164 published, variation and mutation left the leading "<pri>" string as only common content. RFC 5424 defines a new version (version 1) of syslog and introduces structured data into the messages. Structured data is a set of name/value pairs transmitted distinctly alongside the traditional text message, allowing filtering on precise values instead of regular expressions.</p> 25151<p id="doc_section_3_5_p_3">These name/value pairs are scoped by a two-part identifier; an enterprise identifier names the party responsible for the message catalog and a name identifying that message. Enterprise IDs are defined by IANA, the Internet Assigned Numbers Authority:</p> 25152<p id="doc_section_3_5_p_4">https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers</p> 25153<p id="doc_section_3_5_p_5">Use the <a href="#xo_set_syslog_enterprise_id" title="xo_set_syslog_enterprise_id">Section�3.5.3.5</a>() function to set the Enterprise ID, as needed.</p> 25154<p id="doc_section_3_5_p_6">The message name should follow the conventions in <a href="#good-field-names" title="What makes a good field name?">Section�8.1.3</a>, as should the fields within the message.</p> |
| 25005<div id="doc_figure_u.114"></div> <pre> | 25155<div id="doc_figure_u.121"></div> <pre> |
| 25006 /* Both of these calls are optional */ 25007 xo_set_syslog_enterprise_id(32473); 25008 xo_open_log("my-program", 0, LOG_DAEMON); 25009 25010 /* Generate a syslog message */ 25011 xo_syslog(LOG_ERR, "upload-failed", 25012 "error <%d> uploading file '{:filename}' " 25013 "as '{:target/%s:%s}'", --- 11 unchanged lines hidden (view full) --- 25025</ul> 25026<div class="content"> 25027<h3 id="doc_section_3_5_1"> 25028<div class="self-section-number"> 25029<a href="#doc_section_3_5_1">3.5.1</a>�</div> 25030<a id="priority" href="#priority">Priority, Facility, and Flags</a> 25031</h3> 25032<p id="doc_section_3_5_1_p_1">The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of flags which provide the priority of the message, the source facility, and some additional features. These values are OR'd together to create a single integer argument:</p> | 25156 /* Both of these calls are optional */ 25157 xo_set_syslog_enterprise_id(32473); 25158 xo_open_log("my-program", 0, LOG_DAEMON); 25159 25160 /* Generate a syslog message */ 25161 xo_syslog(LOG_ERR, "upload-failed", 25162 "error <%d> uploading file '{:filename}' " 25163 "as '{:target/%s:%s}'", --- 11 unchanged lines hidden (view full) --- 25175</ul> 25176<div class="content"> 25177<h3 id="doc_section_3_5_1"> 25178<div class="self-section-number"> 25179<a href="#doc_section_3_5_1">3.5.1</a>�</div> 25180<a id="priority" href="#priority">Priority, Facility, and Flags</a> 25181</h3> 25182<p id="doc_section_3_5_1_p_1">The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of flags which provide the priority of the message, the source facility, and some additional features. These values are OR'd together to create a single integer argument:</p> |
| 25033<div id="doc_figure_u.115"></div> <pre> | 25183<div id="doc_figure_u.122"></div> <pre> |
| 25034 xo_syslog(LOG_ERR | LOG_AUTH, "login-failed", 25035 "Login failed; user '{:user}' from host '{:address}'", 25036 user, addr); 25037 </pre> <p id="doc_section_3_5_1_p_3">These values are defined in <syslog.h>.</p> 25038<p id="doc_section_3_5_1_p_4">The priority value indicates the importance and potential impact of each message.</p> | 25184 xo_syslog(LOG_ERR | LOG_AUTH, "login-failed", 25185 "Login failed; user '{:user}' from host '{:address}'", 25186 user, addr); 25187 </pre> <p id="doc_section_3_5_1_p_3">These values are defined in <syslog.h>.</p> 25188<p id="doc_section_3_5_1_p_4">The priority value indicates the importance and potential impact of each message.</p> |
| 25039<div id="doc_table_u.14"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25189<div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25040<thead><tr> 25041<th class="left">Priority</th> 25042<th class="left">Description</th> 25043</tr></thead> 25044<tbody> 25045<tr> 25046<td>LOG_EMERG</td> 25047<td>A panic condition, normally broadcast to all users</td> --- 24 unchanged lines hidden (view full) --- 25072</tr> 25073<tr> 25074<td>LOG_DEBUG</td> 25075<td>Developer-oriented messages</td> 25076</tr> 25077</tbody> 25078</table></div> 25079<p id="doc_section_3_5_1_p_5">The facility value indicates the source of message, in fairly generic terms.</p> | 25190<thead><tr> 25191<th class="left">Priority</th> 25192<th class="left">Description</th> 25193</tr></thead> 25194<tbody> 25195<tr> 25196<td>LOG_EMERG</td> 25197<td>A panic condition, normally broadcast to all users</td> --- 24 unchanged lines hidden (view full) --- 25222</tr> 25223<tr> 25224<td>LOG_DEBUG</td> 25225<td>Developer-oriented messages</td> 25226</tr> 25227</tbody> 25228</table></div> 25229<p id="doc_section_3_5_1_p_5">The facility value indicates the source of message, in fairly generic terms.</p> |
| 25080<div id="doc_table_u.15"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25230<div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25081<thead><tr> 25082<th class="left">Facility</th> 25083<th class="left">Description</th> 25084</tr></thead> 25085<tbody> 25086<tr> 25087<td>LOG_AUTH</td> 25088<td>The authorization system (e.g. login(1))</td> --- 48 unchanged lines hidden (view full) --- 25137</tr> 25138<tr> 25139<td>LOG_LOCAL0..7</td> 25140<td>Reserved for local use</td> 25141</tr> 25142</tbody> 25143</table></div> 25144<p id="doc_section_3_5_1_p_6">In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific behaviors.</p> | 25231<thead><tr> 25232<th class="left">Facility</th> 25233<th class="left">Description</th> 25234</tr></thead> 25235<tbody> 25236<tr> 25237<td>LOG_AUTH</td> 25238<td>The authorization system (e.g. login(1))</td> --- 48 unchanged lines hidden (view full) --- 25287</tr> 25288<tr> 25289<td>LOG_LOCAL0..7</td> 25290<td>Reserved for local use</td> 25291</tr> 25292</tbody> 25293</table></div> 25294<p id="doc_section_3_5_1_p_6">In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific behaviors.</p> |
| 25145<div id="doc_table_u.16"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25295<div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25146<thead><tr> 25147<th class="left">Flag</th> 25148<th class="left">Description</th> 25149</tr></thead> 25150<tbody> 25151<tr> 25152<td>LOG_CONS</td> 25153<td>If syslogd fails, attempt to write to /dev/console</td> --- 16 unchanged lines hidden (view full) --- 25170<div class="content"> 25171<h3 id="doc_section_3_5_2"> 25172<div class="self-section-number"> 25173<a href="#doc_section_3_5_2">3.5.2</a>�</div> 25174<a id="xo_syslog" href="#xo_syslog">xo_syslog</a> 25175</h3> 25176<p id="doc_section_3_5_2_p_1">Use the xo_syslog function to generate syslog messages by calling it with a log priority and facility, a message name, a format string, and a set of arguments. The priority/facility argument are discussed above, as is the message name.</p> 25177<p id="doc_section_3_5_2_p_2">The format string follows the same conventions as xo_emit's format string, with each field being rendered as an SD-PARAM pair.</p> | 25296<thead><tr> 25297<th class="left">Flag</th> 25298<th class="left">Description</th> 25299</tr></thead> 25300<tbody> 25301<tr> 25302<td>LOG_CONS</td> 25303<td>If syslogd fails, attempt to write to /dev/console</td> --- 16 unchanged lines hidden (view full) --- 25320<div class="content"> 25321<h3 id="doc_section_3_5_2"> 25322<div class="self-section-number"> 25323<a href="#doc_section_3_5_2">3.5.2</a>�</div> 25324<a id="xo_syslog" href="#xo_syslog">xo_syslog</a> 25325</h3> 25326<p id="doc_section_3_5_2_p_1">Use the xo_syslog function to generate syslog messages by calling it with a log priority and facility, a message name, a format string, and a set of arguments. The priority/facility argument are discussed above, as is the message name.</p> 25327<p id="doc_section_3_5_2_p_2">The format string follows the same conventions as xo_emit's format string, with each field being rendered as an SD-PARAM pair.</p> |
| 25178<div id="doc_figure_u.116"></div> <pre> | 25328<div id="doc_figure_u.123"></div> <pre> |
| 25179 xo_syslog(LOG_ERR, "poofd-missing-file", 25180 "'{:filename}' not found: {:error/%m}", filename); 25181 25182 ... [poofd-missing-file@32473 filename="/etc/poofd.conf" 25183 error="Permission denied"] '/etc/poofd.conf' not 25184 found: Permission denied 25185 </pre> </div> 25186<div class="content"> --- 12 unchanged lines hidden (view full) --- 25199</ul> 25200<div class="content"> 25201<h4 id="doc_section_3_5_3_1"> 25202<div class="self-section-number"> 25203<a href="#doc_section_3_5_3_1">3.5.3.1</a>�</div> 25204<a id="xo_vsyslog" href="#xo_vsyslog">xo_vsyslog</a> 25205</h4> 25206<p id="doc_section_3_5_3_1_p_1">xo_vsyslog is identical in function to xo_syslog, but takes the set of arguments using a va_list.</p> | 25329 xo_syslog(LOG_ERR, "poofd-missing-file", 25330 "'{:filename}' not found: {:error/%m}", filename); 25331 25332 ... [poofd-missing-file@32473 filename="/etc/poofd.conf" 25333 error="Permission denied"] '/etc/poofd.conf' not 25334 found: Permission denied 25335 </pre> </div> 25336<div class="content"> --- 12 unchanged lines hidden (view full) --- 25349</ul> 25350<div class="content"> 25351<h4 id="doc_section_3_5_3_1"> 25352<div class="self-section-number"> 25353<a href="#doc_section_3_5_3_1">3.5.3.1</a>�</div> 25354<a id="xo_vsyslog" href="#xo_vsyslog">xo_vsyslog</a> 25355</h4> 25356<p id="doc_section_3_5_3_1_p_1">xo_vsyslog is identical in function to xo_syslog, but takes the set of arguments using a va_list.</p> |
| 25207<div id="doc_figure_u.117"></div> <pre> | 25357<div id="doc_figure_u.124"></div> <pre> |
| 25208 void my_log (const char *name, const char *fmt, ...) 25209 { 25210 va_list vap; 25211 va_start(vap, fmt); 25212 xo_vsyslog(LOG_ERR, name, fmt, vap); 25213 va_end(vap); 25214 } 25215 </pre> </div> 25216<div class="content"> 25217<h4 id="doc_section_3_5_3_2"> 25218<div class="self-section-number"> 25219<a href="#doc_section_3_5_3_2">3.5.3.2</a>�</div> 25220<a id="xo_open_log" href="#xo_open_log">xo_open_log</a> 25221</h4> 25222<p id="doc_section_3_5_3_2_p_1">xo_open_log functions similar to openlog(3), allowing customization of the program name, the log facility number, and the additional option flags described in <a href="#priority" title="Priority, Facility, and Flags">Section�3.5.1</a>.</p> | 25358 void my_log (const char *name, const char *fmt, ...) 25359 { 25360 va_list vap; 25361 va_start(vap, fmt); 25362 xo_vsyslog(LOG_ERR, name, fmt, vap); 25363 va_end(vap); 25364 } 25365 </pre> </div> 25366<div class="content"> 25367<h4 id="doc_section_3_5_3_2"> 25368<div class="self-section-number"> 25369<a href="#doc_section_3_5_3_2">3.5.3.2</a>�</div> 25370<a id="xo_open_log" href="#xo_open_log">xo_open_log</a> 25371</h4> 25372<p id="doc_section_3_5_3_2_p_1">xo_open_log functions similar to openlog(3), allowing customization of the program name, the log facility number, and the additional option flags described in <a href="#priority" title="Priority, Facility, and Flags">Section�3.5.1</a>.</p> |
| 25223<div id="doc_figure_u.118"></div> <pre> | 25373<div id="doc_figure_u.125"></div> <pre> |
| 25224 void 25225 xo_open_log (const char *ident, int logopt, int facility); 25226 </pre> </div> 25227<div class="content"> 25228<h4 id="doc_section_3_5_3_3"> 25229<div class="self-section-number"> 25230<a href="#doc_section_3_5_3_3">3.5.3.3</a>�</div> 25231<a id="xo_close_log" href="#xo_close_log">xo_close_log</a> 25232</h4> 25233<p id="doc_section_3_5_3_3_p_1">xo_close_log functions similar to closelog(3), closing the log file and releasing any associated resources.</p> | 25374 void 25375 xo_open_log (const char *ident, int logopt, int facility); 25376 </pre> </div> 25377<div class="content"> 25378<h4 id="doc_section_3_5_3_3"> 25379<div class="self-section-number"> 25380<a href="#doc_section_3_5_3_3">3.5.3.3</a>�</div> 25381<a id="xo_close_log" href="#xo_close_log">xo_close_log</a> 25382</h4> 25383<p id="doc_section_3_5_3_3_p_1">xo_close_log functions similar to closelog(3), closing the log file and releasing any associated resources.</p> |
| 25234<div id="doc_figure_u.119"></div> <pre> | 25384<div id="doc_figure_u.126"></div> <pre> |
| 25235 void 25236 xo_close_log (void); 25237 </pre> </div> 25238<div class="content"> 25239<h4 id="doc_section_3_5_3_4"> 25240<div class="self-section-number"> 25241<a href="#doc_section_3_5_3_4">3.5.3.4</a>�</div> 25242<a id="xo_set_logmask" href="#xo_set_logmask">xo_set_logmask</a> 25243</h4> 25244<p id="doc_section_3_5_3_4_p_1">xo_set_logmask function similar to setlogmask(3), restricting the set of generated log event to those whose associated bit is set in maskpri. Use LOG_MASK(pri) to find the appropriate bit, or LOG_UPTO(toppri) to create a mask for all priorities up to and including toppri.</p> | 25385 void 25386 xo_close_log (void); 25387 </pre> </div> 25388<div class="content"> 25389<h4 id="doc_section_3_5_3_4"> 25390<div class="self-section-number"> 25391<a href="#doc_section_3_5_3_4">3.5.3.4</a>�</div> 25392<a id="xo_set_logmask" href="#xo_set_logmask">xo_set_logmask</a> 25393</h4> 25394<p id="doc_section_3_5_3_4_p_1">xo_set_logmask function similar to setlogmask(3), restricting the set of generated log event to those whose associated bit is set in maskpri. Use LOG_MASK(pri) to find the appropriate bit, or LOG_UPTO(toppri) to create a mask for all priorities up to and including toppri.</p> |
| 25245<div id="doc_figure_u.120"></div> <pre> | 25395<div id="doc_figure_u.127"></div> <pre> |
| 25246 int 25247 xo_set_logmask (int maskpri); 25248 25249 Example: 25250 setlogmask(LOG_UPTO(LOG_WARN)); 25251 </pre> </div> 25252<div class="content"> 25253<h4 id="doc_section_3_5_3_5"> 25254<div class="self-section-number"> 25255<a href="#doc_section_3_5_3_5">3.5.3.5</a>�</div> 25256<a id="xo_set_syslog_enterprise_id" href="#xo_set_syslog_enterprise_id">xo_set_syslog_enterprise_id</a> 25257</h4> 25258<p id="doc_section_3_5_3_5_p_1">Use the xo_set_syslog_enterprise_id to supply a platform- or application-specific enterprise id. This value is used in any future syslog messages.</p> 25259<p id="doc_section_3_5_3_5_p_2">Ideally, the operating system should supply a default value via the "kern.syslog.enterprise_id" sysctl value. Lacking that, the application should provide a suitable value.</p> | 25396 int 25397 xo_set_logmask (int maskpri); 25398 25399 Example: 25400 setlogmask(LOG_UPTO(LOG_WARN)); 25401 </pre> </div> 25402<div class="content"> 25403<h4 id="doc_section_3_5_3_5"> 25404<div class="self-section-number"> 25405<a href="#doc_section_3_5_3_5">3.5.3.5</a>�</div> 25406<a id="xo_set_syslog_enterprise_id" href="#xo_set_syslog_enterprise_id">xo_set_syslog_enterprise_id</a> 25407</h4> 25408<p id="doc_section_3_5_3_5_p_1">Use the xo_set_syslog_enterprise_id to supply a platform- or application-specific enterprise id. This value is used in any future syslog messages.</p> 25409<p id="doc_section_3_5_3_5_p_2">Ideally, the operating system should supply a default value via the "kern.syslog.enterprise_id" sysctl value. Lacking that, the application should provide a suitable value.</p> |
| 25260<div id="doc_figure_u.121"></div> <pre> | 25410<div id="doc_figure_u.128"></div> <pre> |
| 25261 void 25262 xo_set_syslog_enterprise_id (unsigned short eid); 25263 </pre> <p id="doc_section_3_5_3_5_p_4">Enterprise IDs are administered by IANA, the Internet Assigned Number Authority. The complete list is EIDs on their web site:</p> 25264<p id="doc_section_3_5_3_5_p_5"> <a href="https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers">https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers</a></p> 25265<p id="doc_section_3_5_3_5_p_6">New EIDs can be requested from IANA using the following page:</p> 25266<p id="doc_section_3_5_3_5_p_7"> <a href="http://pen.iana.org/pen/PenApplication.page">http://pen.iana.org/pen/PenApplication.page</a></p> 25267<p id="doc_section_3_5_3_5_p_8">Each software development organization that defines a set of syslog messages should register their own EID and use that value in their software to ensure that messages can be uniquely identified by the combination of EID + message name.</p> 25268</div> --- 25 unchanged lines hidden (view full) --- 25294</ul> 25295<div class="content"> 25296<h3 id="doc_section_3_6_1"> 25297<div class="self-section-number"> 25298<a href="#doc_section_3_6_1">3.6.1</a>�</div> 25299<a id="loading-encoders" href="#loading-encoders">Loading Encoders</a> 25300</h3> 25301<p id="doc_section_3_6_1_p_1">Encoders can be registered statically or discovered dynamically. Applications can choose to call the xo_encoder_register() function to explicitly register encoders, but more typically they are built as shared libraries, placed in the libxo/extensions directory, and loaded based on name. libxo looks for a file with the name of the encoder and an extension of ".enc". This can be a file or a symlink to the shared library file that supports the encoder.</p> | 25411 void 25412 xo_set_syslog_enterprise_id (unsigned short eid); 25413 </pre> <p id="doc_section_3_5_3_5_p_4">Enterprise IDs are administered by IANA, the Internet Assigned Number Authority. The complete list is EIDs on their web site:</p> 25414<p id="doc_section_3_5_3_5_p_5"> <a href="https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers">https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers</a></p> 25415<p id="doc_section_3_5_3_5_p_6">New EIDs can be requested from IANA using the following page:</p> 25416<p id="doc_section_3_5_3_5_p_7"> <a href="http://pen.iana.org/pen/PenApplication.page">http://pen.iana.org/pen/PenApplication.page</a></p> 25417<p id="doc_section_3_5_3_5_p_8">Each software development organization that defines a set of syslog messages should register their own EID and use that value in their software to ensure that messages can be uniquely identified by the combination of EID + message name.</p> 25418</div> --- 25 unchanged lines hidden (view full) --- 25444</ul> 25445<div class="content"> 25446<h3 id="doc_section_3_6_1"> 25447<div class="self-section-number"> 25448<a href="#doc_section_3_6_1">3.6.1</a>�</div> 25449<a id="loading-encoders" href="#loading-encoders">Loading Encoders</a> 25450</h3> 25451<p id="doc_section_3_6_1_p_1">Encoders can be registered statically or discovered dynamically. Applications can choose to call the xo_encoder_register() function to explicitly register encoders, but more typically they are built as shared libraries, placed in the libxo/extensions directory, and loaded based on name. libxo looks for a file with the name of the encoder and an extension of ".enc". This can be a file or a symlink to the shared library file that supports the encoder.</p> |
| 25302<div id="doc_figure_u.122"></div> <pre> | 25452<div id="doc_figure_u.129"></div> <pre> |
| 25303 % ls -1 lib/libxo/extensions/*.enc 25304 lib/libxo/extensions/cbor.enc 25305 lib/libxo/extensions/test.enc 25306 </pre> </div> 25307<div class="content"> 25308<h3 id="doc_section_3_6_2"> 25309<div class="self-section-number"> 25310<a href="#doc_section_3_6_2">3.6.2</a>�</div> 25311<a id="encoder-initialization" href="#encoder-initialization">Encoder Initialization</a> 25312</h3> 25313<p id="doc_section_3_6_2_p_1">Each encoder must export a symbol used to access the library, which must have the following signature:</p> | 25453 % ls -1 lib/libxo/extensions/*.enc 25454 lib/libxo/extensions/cbor.enc 25455 lib/libxo/extensions/test.enc 25456 </pre> </div> 25457<div class="content"> 25458<h3 id="doc_section_3_6_2"> 25459<div class="self-section-number"> 25460<a href="#doc_section_3_6_2">3.6.2</a>�</div> 25461<a id="encoder-initialization" href="#encoder-initialization">Encoder Initialization</a> 25462</h3> 25463<p id="doc_section_3_6_2_p_1">Each encoder must export a symbol used to access the library, which must have the following signature:</p> |
| 25314<div id="doc_figure_u.123"></div> <pre> | 25464<div id="doc_figure_u.130"></div> <pre> |
| 25315 int xo_encoder_library_init (XO_ENCODER_INIT_ARGS); 25316 </pre> <p id="doc_section_3_6_2_p_3">XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines an argument called "arg", a pointer of the type xo_encoder_init_args_t. This structure contains two fields:</p> 25317<p id="doc_section_3_6_2_p_4"> </p> 25318<ul> 25319<li>xei_version is the version number of the API as implemented within libxo. This version is currently as 1 using XO_ENCODER_VERSION. This number can be checked to ensure compatibility. The working assumption is that all versions should be backward compatible, but each side may need to accurately know the version supported by the other side. xo_encoder_library_init can optionally check this value, and must then set it to the version number used by the encoder, allowing libxo to detect version differences and react accordingly. For example, if version 2 adds new operations, then libxo will know that an encoding library that set xei_version to 1 cannot be expected to handle those new operations.</li> 25320<li>xei_handler must be set to a pointer to a function of type xo_encoder_func_t, as defined in xo_encoder.h. This function takes a set of parameters: -- xop is a pointer to the opaque xo_handle_t structure -- op is an integer representing the current operation -- name is a string whose meaning differs by operation -- value is a string whose meaning differs by operation -- private is an opaque structure provided by the encoder</li> 25321</ul> 25322<p id="doc_section_3_6_2_p_5">Additional arguments may be added in the future, so handler functions should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate "extern" declaration is provided to help catch errors.</p> 25323<p id="doc_section_3_6_2_p_6">Once the encoder initialization function has completed processing, it should return zero to indicate that no error has occurred. A non-zero return code will cause the handle initialization to fail.</p> 25324</div> 25325<div class="content"> 25326<h3 id="doc_section_3_6_3"> 25327<div class="self-section-number"> 25328<a href="#doc_section_3_6_3">3.6.3</a>�</div> 25329<a id="operations" href="#operations">Operations</a> 25330</h3> 25331<p id="doc_section_3_6_3_p_1">The encoder API defines a set of operations representing the processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed.</p> | 25465 int xo_encoder_library_init (XO_ENCODER_INIT_ARGS); 25466 </pre> <p id="doc_section_3_6_2_p_3">XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines an argument called "arg", a pointer of the type xo_encoder_init_args_t. This structure contains two fields:</p> 25467<p id="doc_section_3_6_2_p_4"> </p> 25468<ul> 25469<li>xei_version is the version number of the API as implemented within libxo. This version is currently as 1 using XO_ENCODER_VERSION. This number can be checked to ensure compatibility. The working assumption is that all versions should be backward compatible, but each side may need to accurately know the version supported by the other side. xo_encoder_library_init can optionally check this value, and must then set it to the version number used by the encoder, allowing libxo to detect version differences and react accordingly. For example, if version 2 adds new operations, then libxo will know that an encoding library that set xei_version to 1 cannot be expected to handle those new operations.</li> 25470<li>xei_handler must be set to a pointer to a function of type xo_encoder_func_t, as defined in xo_encoder.h. This function takes a set of parameters: -- xop is a pointer to the opaque xo_handle_t structure -- op is an integer representing the current operation -- name is a string whose meaning differs by operation -- value is a string whose meaning differs by operation -- private is an opaque structure provided by the encoder</li> 25471</ul> 25472<p id="doc_section_3_6_2_p_5">Additional arguments may be added in the future, so handler functions should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate "extern" declaration is provided to help catch errors.</p> 25473<p id="doc_section_3_6_2_p_6">Once the encoder initialization function has completed processing, it should return zero to indicate that no error has occurred. A non-zero return code will cause the handle initialization to fail.</p> 25474</div> 25475<div class="content"> 25476<h3 id="doc_section_3_6_3"> 25477<div class="self-section-number"> 25478<a href="#doc_section_3_6_3">3.6.3</a>�</div> 25479<a id="operations" href="#operations">Operations</a> 25480</h3> 25481<p id="doc_section_3_6_3_p_1">The encoder API defines a set of operations representing the processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed.</p> |
| 25332<div id="doc_table_u.17"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25482<div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25333<thead><tr> 25334<th class="left">Operation</th> 25335<th class="left">Meaning (Base function)</th> 25336</tr></thead> 25337<tbody> 25338<tr> 25339<td>XO_OP_CREATE</td> 25340<td>Called when the handle is created</td> --- 70 unchanged lines hidden (view full) --- 25411<h1 id="doc_section_4" class="np"> 25412<div class="self-section-number"> 25413<a href="#doc_section_4">4_</a>�</div> 25414<a id="the-xo-utility" href="#the-xo-utility">The "xo" Utility</a> 25415</h1> 25416<p id="doc_section_4_p_1">The "xo" utility allows command line access to the functionality of the libxo library. Using "xo", shell scripts can emit XML, JSON, and HTML using the same commands that emit text output.</p> 25417<p id="doc_section_4_p_2">The style of output can be selected using a specific option: "‑X" for XML, "‑J" for JSON, "‑H" for HTML, or "‑T" for TEXT, which is the default. The "--style <style>" option can also be used. The LIBXO_OPTIONS environment variable can also be used to set the style, as well as other flags.</p> 25418<p id="doc_section_4_p_3">The "xo" utility accepts a format string suitable for xo_emit() and a set of zero or more arguments used to supply data for that string.</p> | 25483<thead><tr> 25484<th class="left">Operation</th> 25485<th class="left">Meaning (Base function)</th> 25486</tr></thead> 25487<tbody> 25488<tr> 25489<td>XO_OP_CREATE</td> 25490<td>Called when the handle is created</td> --- 70 unchanged lines hidden (view full) --- 25561<h1 id="doc_section_4" class="np"> 25562<div class="self-section-number"> 25563<a href="#doc_section_4">4_</a>�</div> 25564<a id="the-xo-utility" href="#the-xo-utility">The "xo" Utility</a> 25565</h1> 25566<p id="doc_section_4_p_1">The "xo" utility allows command line access to the functionality of the libxo library. Using "xo", shell scripts can emit XML, JSON, and HTML using the same commands that emit text output.</p> 25567<p id="doc_section_4_p_2">The style of output can be selected using a specific option: "‑X" for XML, "‑J" for JSON, "‑H" for HTML, or "‑T" for TEXT, which is the default. The "--style <style>" option can also be used. The LIBXO_OPTIONS environment variable can also be used to set the style, as well as other flags.</p> 25568<p id="doc_section_4_p_3">The "xo" utility accepts a format string suitable for xo_emit() and a set of zero or more arguments used to supply data for that string.</p> |
| 25419<div id="doc_figure_u.124"></div> <pre> | 25569<div id="doc_figure_u.131"></div> <pre> |
| 25420 xo "The {k:name} weighs {:weight/%d} pounds.\n" fish 6 25421 25422 TEXT: 25423 The fish weighs 6 pounds. 25424 XML: 25425 <name>fish</name> 25426 <weight>6</weight> 25427 JSON: 25428 "name": "fish", 25429 "weight": 6 25430 HTML: 25431 <div class="line"> 25432 <div class="text">The </div> 25433 <div class="data" data-tag="name">fish</div> 25434 <div class="text"> weighs </div> 25435 <div class="data" data-tag="weight">6</div> 25436 <div class="text"> pounds.</div> 25437 </div> 25438 </pre> <p id="doc_section_4_p_5">The "--wrap <path>" option can be used to wrap emitted content in a specific hierarchy. The path is a set of hierarchical names separated by the '/' character.</p> | 25570 xo "The {k:name} weighs {:weight/%d} pounds.\n" fish 6 25571 25572 TEXT: 25573 The fish weighs 6 pounds. 25574 XML: 25575 <name>fish</name> 25576 <weight>6</weight> 25577 JSON: 25578 "name": "fish", 25579 "weight": 6 25580 HTML: 25581 <div class="line"> 25582 <div class="text">The </div> 25583 <div class="data" data-tag="name">fish</div> 25584 <div class="text"> weighs </div> 25585 <div class="data" data-tag="weight">6</div> 25586 <div class="text"> pounds.</div> 25587 </div> 25588 </pre> <p id="doc_section_4_p_5">The "--wrap <path>" option can be used to wrap emitted content in a specific hierarchy. The path is a set of hierarchical names separated by the '/' character.</p> |
| 25439<div id="doc_figure_u.125"></div> <pre> | 25589<div id="doc_figure_u.132"></div> <pre> |
| 25440 xo --wrap top/a/b/c '{:tag}' value 25441 25442 XML: 25443 <top> 25444 <a> 25445 <b> 25446 <c> 25447 <tag>value</tag> --- 7 unchanged lines hidden (view full) --- 25455 "b": { 25456 "c": { 25457 "tag": "value" 25458 } 25459 } 25460 } 25461 } 25462 </pre> <p id="doc_section_4_p_7">The "--open <path>" and "--close <path>" can be used to emit hierarchical information without the matching close and open tag. This allows a shell script to emit open tags, data, and then close tags. The "‑‑depth" option may be used to set the depth for indentation. The "‑‑leading‑xpath" may be used to prepend data to the XPath values used for HTML output style.</p> | 25590 xo --wrap top/a/b/c '{:tag}' value 25591 25592 XML: 25593 <top> 25594 <a> 25595 <b> 25596 <c> 25597 <tag>value</tag> --- 7 unchanged lines hidden (view full) --- 25605 "b": { 25606 "c": { 25607 "tag": "value" 25608 } 25609 } 25610 } 25611 } 25612 </pre> <p id="doc_section_4_p_7">The "--open <path>" and "--close <path>" can be used to emit hierarchical information without the matching close and open tag. This allows a shell script to emit open tags, data, and then close tags. The "‑‑depth" option may be used to set the depth for indentation. The "‑‑leading‑xpath" may be used to prepend data to the XPath values used for HTML output style.</p> |
| 25463<div id="doc_figure_u.126"></div> <pre> | 25613<div id="doc_figure_u.133"></div> <pre> |
| 25464 #!/bin/sh 25465 xo --open top/data 25466 xo --depth 2 '{tag}' value 25467 xo --close top/data 25468 XML: 25469 <top> 25470 <data> 25471 <tag>value</tag> --- 12 unchanged lines hidden (view full) --- 25484</ul> 25485<div class="content"> 25486<h2 id="doc_section_4_1"> 25487<div class="self-section-number"> 25488<a href="#doc_section_4_1">4.1</a>�</div> 25489<a id="command-line-options" href="#command-line-options">Command Line Options</a> 25490</h2> 25491<p id="doc_section_4_1_p_1">Usage: xo [options] format [fields]</p> | 25614 #!/bin/sh 25615 xo --open top/data 25616 xo --depth 2 '{tag}' value 25617 xo --close top/data 25618 XML: 25619 <top> 25620 <data> 25621 <tag>value</tag> --- 12 unchanged lines hidden (view full) --- 25634</ul> 25635<div class="content"> 25636<h2 id="doc_section_4_1"> 25637<div class="self-section-number"> 25638<a href="#doc_section_4_1">4.1</a>�</div> 25639<a id="command-line-options" href="#command-line-options">Command Line Options</a> 25640</h2> 25641<p id="doc_section_4_1_p_1">Usage: xo [options] format [fields]</p> |
| 25492<div id="doc_figure_u.127"></div> <pre> | 25642<div id="doc_figure_u.134"></div> <pre> |
| 25493 --close <path> Close tags for the given path 25494 --depth <num> Set the depth for pretty printing 25495 --help Display this help text 25496 --html OR -H Generate HTML output 25497 --json OR -J Generate JSON output 25498 --leading-xpath <path> Add a prefix to generated XPaths (HTML) 25499 --open <path> Open tags for the given path 25500 --pretty OR -p Make 'pretty' output (add indent, newlines) --- 7 unchanged lines hidden (view full) --- 25508 --xpath Add XPath data to HTML output); 25509 </pre> </div> 25510<div class="content"> 25511<h2 id="doc_section_4_2"> 25512<div class="self-section-number"> 25513<a href="#doc_section_4_2">4.2</a>�</div> 25514<a id="example-2" href="#example-2">Example</a> 25515</h2> | 25643 --close <path> Close tags for the given path 25644 --depth <num> Set the depth for pretty printing 25645 --help Display this help text 25646 --html OR -H Generate HTML output 25647 --json OR -J Generate JSON output 25648 --leading-xpath <path> Add a prefix to generated XPaths (HTML) 25649 --open <path> Open tags for the given path 25650 --pretty OR -p Make 'pretty' output (add indent, newlines) --- 7 unchanged lines hidden (view full) --- 25658 --xpath Add XPath data to HTML output); 25659 </pre> </div> 25660<div class="content"> 25661<h2 id="doc_section_4_2"> 25662<div class="self-section-number"> 25663<a href="#doc_section_4_2">4.2</a>�</div> 25664<a id="example-2" href="#example-2">Example</a> 25665</h2> |
| 25516<div id="doc_figure_u.128"></div> <pre> | 25666<div id="doc_figure_u.135"></div> <pre> |
| 25517 % xo 'The {:product} is {:status}\n' stereo "in route" 25518 The stereo is in route 25519 % ./xo/xo -p -X 'The {:product} is {:status}\n' stereo "in route" 25520 <product>stereo</product> 25521 <status>in route</status> 25522 </pre> </div> 25523</div> 25524<hr class="noprint"> 25525<div class="content"> 25526<h1 id="doc_section_5" class="np"> 25527<div class="self-section-number"> 25528<a href="#doc_section_5">5_</a>�</div> 25529<a id="xolint" href="#xolint">xolint</a> 25530</h1> 25531<p id="doc_section_5_p_1">xolint is a tool for reporting common mistakes in format strings in source code that invokes xo_emit(). It allows these errors to be diagnosed at build time, rather than waiting until runtime.</p> 25532<p id="doc_section_5_p_2">xolint takes the one or more C files as arguments, and reports and errors, warning, or informational messages as needed.</p> | 25667 % xo 'The {:product} is {:status}\n' stereo "in route" 25668 The stereo is in route 25669 % ./xo/xo -p -X 'The {:product} is {:status}\n' stereo "in route" 25670 <product>stereo</product> 25671 <status>in route</status> 25672 </pre> </div> 25673</div> 25674<hr class="noprint"> 25675<div class="content"> 25676<h1 id="doc_section_5" class="np"> 25677<div class="self-section-number"> 25678<a href="#doc_section_5">5_</a>�</div> 25679<a id="xolint" href="#xolint">xolint</a> 25680</h1> 25681<p id="doc_section_5_p_1">xolint is a tool for reporting common mistakes in format strings in source code that invokes xo_emit(). It allows these errors to be diagnosed at build time, rather than waiting until runtime.</p> 25682<p id="doc_section_5_p_2">xolint takes the one or more C files as arguments, and reports and errors, warning, or informational messages as needed.</p> |
| 25533<div id="doc_table_u.18"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25683<div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25534<thead><tr> 25535<th class="left">Option</th> 25536<th class="left">Meaning</th> 25537</tr></thead> 25538<tbody> 25539<tr> 25540<td>-c</td> 25541<td>Invoke 'cpp' against the input file</td> --- 24 unchanged lines hidden (view full) --- 25566</tr> 25567<tr> 25568<td>-X</td> 25569<td>Extract samples from xolint, suitable for testing</td> 25570</tr> 25571</tbody> 25572</table></div> 25573<p id="doc_section_5_p_3">The output message will contain the source filename and line number, the class of the message, the message, and, if -p is given, the line that contains the error:</p> | 25684<thead><tr> 25685<th class="left">Option</th> 25686<th class="left">Meaning</th> 25687</tr></thead> 25688<tbody> 25689<tr> 25690<td>-c</td> 25691<td>Invoke 'cpp' against the input file</td> --- 24 unchanged lines hidden (view full) --- 25716</tr> 25717<tr> 25718<td>-X</td> 25719<td>Extract samples from xolint, suitable for testing</td> 25720</tr> 25721</tbody> 25722</table></div> 25723<p id="doc_section_5_p_3">The output message will contain the source filename and line number, the class of the message, the message, and, if -p is given, the line that contains the error:</p> |
| 25574<div id="doc_figure_u.129"></div> <pre> | 25724<div id="doc_figure_u.136"></div> <pre> |
| 25575 % xolint.pl -t xolint.c 25576 xolint.c: 16: error: anchor format should be "%d" 25577 16 xo_emit("{[:/%s}"); 25578 </pre> <p id="doc_section_5_p_5">The "‑I" option will generate a table of xo_info_t structures ,</p> 25579<p id="doc_section_5_p_6">The "‑V" option does not report errors, but prints a complete list of all field names, sorted alphabetically. The output can help spot inconsistencies and spelling errors.</p> 25580</div> 25581<hr class="noprint"> 25582<div class="content"> 25583<h1 id="doc_section_6" class="np"> 25584<div class="self-section-number"> 25585<a href="#doc_section_6">6_</a>�</div> 25586<a id="xohtml" href="#xohtml">xohtml</a> 25587</h1> 25588<p id="doc_section_6_p_1">xohtml is a tool for turning the output of libxo-enabled commands into html files suitable for display in modern HTML web browsers. It can be used to test and debug HTML output, as well as to make the user ache to escape the world of 70s terminal devices.</p> 25589<p id="doc_section_6_p_2">xohtml is given a command, either on the command line or via the "‑c" option. If not command is given, standard input is used. The command's output is wrapped in HTML tags, with references to supporting CSS and Javascript files, and written to standard output or the file given in the "‑f" option. The "‑b" option can be used to provide an alternative base path for the support files.</p> | 25725 % xolint.pl -t xolint.c 25726 xolint.c: 16: error: anchor format should be "%d" 25727 16 xo_emit("{[:/%s}"); 25728 </pre> <p id="doc_section_5_p_5">The "‑I" option will generate a table of xo_info_t structures ,</p> 25729<p id="doc_section_5_p_6">The "‑V" option does not report errors, but prints a complete list of all field names, sorted alphabetically. The output can help spot inconsistencies and spelling errors.</p> 25730</div> 25731<hr class="noprint"> 25732<div class="content"> 25733<h1 id="doc_section_6" class="np"> 25734<div class="self-section-number"> 25735<a href="#doc_section_6">6_</a>�</div> 25736<a id="xohtml" href="#xohtml">xohtml</a> 25737</h1> 25738<p id="doc_section_6_p_1">xohtml is a tool for turning the output of libxo-enabled commands into html files suitable for display in modern HTML web browsers. It can be used to test and debug HTML output, as well as to make the user ache to escape the world of 70s terminal devices.</p> 25739<p id="doc_section_6_p_2">xohtml is given a command, either on the command line or via the "‑c" option. If not command is given, standard input is used. The command's output is wrapped in HTML tags, with references to supporting CSS and Javascript files, and written to standard output or the file given in the "‑f" option. The "‑b" option can be used to provide an alternative base path for the support files.</p> |
| 25590<div id="doc_table_u.19"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25740<div id="doc_table_u.21"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25591<thead><tr> 25592<th class="left">Option</th> 25593<th class="left">Meaning</th> 25594</tr></thead> 25595<tbody> 25596<tr> 25597<td>-b <base></td> 25598<td>Base path for finding css/javascript files</td> --- 15 unchanged lines hidden (view full) --- 25614<h1 id="doc_section_7" class="np"> 25615<div class="self-section-number"> 25616<a href="#doc_section_7">7_</a>�</div> 25617<a id="xopo" href="#xopo">xopo</a> 25618</h1> 25619<p id="doc_section_7_p_1">The "xopo" utility filters ".pot" files generated by the "xgettext" utility to remove formatting information suitable for use with the "{G:}" modifier. This means that when the developer changes the formatting portion of the field definitions, or the fields modifiers, the string passed to gettext(3) is unchanged, avoiding the expense of updating any existing translation files (".po" files).</p> 25620<p id="doc_section_7_p_2">The syntax for the xopo command is one of two forms; it can be used as a filter for processing a .po or .pot file, rewriting the "msgid" strings with a simplified message string. In this mode, the input is either standard input or a file given by the "‑f" option, and the output is either standard output or a file given by the "‑o" option.</p> 25621<p id="doc_section_7_p_3">In the second mode, a simple message given using the "‑s" option on the command, and the simplified version of that message is printed on stdout.</p> | 25741<thead><tr> 25742<th class="left">Option</th> 25743<th class="left">Meaning</th> 25744</tr></thead> 25745<tbody> 25746<tr> 25747<td>-b <base></td> 25748<td>Base path for finding css/javascript files</td> --- 15 unchanged lines hidden (view full) --- 25764<h1 id="doc_section_7" class="np"> 25765<div class="self-section-number"> 25766<a href="#doc_section_7">7_</a>�</div> 25767<a id="xopo" href="#xopo">xopo</a> 25768</h1> 25769<p id="doc_section_7_p_1">The "xopo" utility filters ".pot" files generated by the "xgettext" utility to remove formatting information suitable for use with the "{G:}" modifier. This means that when the developer changes the formatting portion of the field definitions, or the fields modifiers, the string passed to gettext(3) is unchanged, avoiding the expense of updating any existing translation files (".po" files).</p> 25770<p id="doc_section_7_p_2">The syntax for the xopo command is one of two forms; it can be used as a filter for processing a .po or .pot file, rewriting the "msgid" strings with a simplified message string. In this mode, the input is either standard input or a file given by the "‑f" option, and the output is either standard output or a file given by the "‑o" option.</p> 25771<p id="doc_section_7_p_3">In the second mode, a simple message given using the "‑s" option on the command, and the simplified version of that message is printed on stdout.</p> |
| 25622<div id="doc_table_u.20"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> | 25772<div id="doc_table_u.22"><table summary="" class="tt full" cellpadding="3" cellspacing="0"> |
| 25623<thead><tr> 25624<th class="left">Option</th> 25625<th class="left">Meaning</th> 25626</tr></thead> 25627<tbody> 25628<tr> 25629<td>-o <file></td> 25630<td>Output file name</td> 25631</tr> 25632<tr> 25633<td>-f <file></td> 25634<td>Use the given .po file as input</td> 25635</tr> 25636<tr> 25637<td>-s <text></td> 25638<td>Simplify a format string</td> 25639</tr> 25640</tbody> 25641</table></div> | 25773<thead><tr> 25774<th class="left">Option</th> 25775<th class="left">Meaning</th> 25776</tr></thead> 25777<tbody> 25778<tr> 25779<td>-o <file></td> 25780<td>Output file name</td> 25781</tr> 25782<tr> 25783<td>-f <file></td> 25784<td>Use the given .po file as input</td> 25785</tr> 25786<tr> 25787<td>-s <text></td> 25788<td>Simplify a format string</td> 25789</tr> 25790</tbody> 25791</table></div> |
| 25642<div id="doc_figure_u.130"></div> <pre> | 25792<div id="doc_figure_u.137"></div> <pre> |
| 25643 EXAMPLE: 25644 % xopo -s "There are {:count/%u} {:event/%.6s} events\n" 25645 There are {:count} {:event} events\n 25646 25647 % xgettext --default-domain=foo --no-wrap \ 25648 --add-comments --keyword=xo_emit --keyword=xo_emit_h \ 25649 --keyword=xo_emit_warn -C -E -n --foreign-user \ 25650 -o foo.pot.raw foo.c --- 31 unchanged lines hidden (view full) --- 25682<li><a href="#good-field-names" title="What makes a good field name?">Section�8.1.3</a></li> 25683</ul> 25684<div class="content"> 25685<h3 id="doc_section_8_1_1"> 25686<div class="self-section-number"> 25687<a href="#doc_section_8_1_1">8.1.1</a>�</div> 25688<a id="can-you-share-the-history-of-libxo" href="#can-you-share-the-history-of-libxo">Can you share the history of libxo?</a> 25689</h3> | 25793 EXAMPLE: 25794 % xopo -s "There are {:count/%u} {:event/%.6s} events\n" 25795 There are {:count} {:event} events\n 25796 25797 % xgettext --default-domain=foo --no-wrap \ 25798 --add-comments --keyword=xo_emit --keyword=xo_emit_h \ 25799 --keyword=xo_emit_warn -C -E -n --foreign-user \ 25800 -o foo.pot.raw foo.c --- 31 unchanged lines hidden (view full) --- 25832<li><a href="#good-field-names" title="What makes a good field name?">Section�8.1.3</a></li> 25833</ul> 25834<div class="content"> 25835<h3 id="doc_section_8_1_1"> 25836<div class="self-section-number"> 25837<a href="#doc_section_8_1_1">8.1.1</a>�</div> 25838<a id="can-you-share-the-history-of-libxo" href="#can-you-share-the-history-of-libxo">Can you share the history of libxo?</a> 25839</h3> |
| 25690 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. 25691 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. 25692<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> | 25840<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> 25841<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> 25842<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> |
| 25693</div> 25694<div class="content"> 25695<h3 id="doc_section_8_1_2"> 25696<div class="self-section-number"> 25697<a href="#doc_section_8_1_2">8.1.2</a>�</div> 25698<a id="did-the-complex-semantics-of-format-strings-evolve-over-time" href="#did-the-complex-semantics-of-format-strings-evolve-over-time">Did the complex semantics of format strings evolve over time?</a> 25699</h3> 25700<p id="doc_section_8_1_2_p_1">The history is both long and short: libxo's functionality is based on what JUNOS does in a data modeling language called ODL (output definition language). In JUNOS, all subcomponents generate XML, which is feed to the CLI, where data from the ODL files tell is how to render that XML into text. ODL might had a set of tags like:</p> | 25843</div> 25844<div class="content"> 25845<h3 id="doc_section_8_1_2"> 25846<div class="self-section-number"> 25847<a href="#doc_section_8_1_2">8.1.2</a>�</div> 25848<a id="did-the-complex-semantics-of-format-strings-evolve-over-time" href="#did-the-complex-semantics-of-format-strings-evolve-over-time">Did the complex semantics of format strings evolve over time?</a> 25849</h3> 25850<p id="doc_section_8_1_2_p_1">The history is both long and short: libxo's functionality is based on what JUNOS does in a data modeling language called ODL (output definition language). In JUNOS, all subcomponents generate XML, which is feed to the CLI, where data from the ODL files tell is how to render that XML into text. ODL might had a set of tags like:</p> |
| 25701<div id="doc_figure_u.131"></div> <pre> | 25851<div id="doc_figure_u.138"></div> <pre> |
| 25702 tag docsis-state { 25703 help "State of the DOCSIS interface"; 25704 type string; 25705 } 25706 25707 tag docsis-mode { 25708 help "DOCSIS mode (2.0/3.0) of the DOCSIS interface"; 25709 type string; --- 62 unchanged lines hidden (view full) --- 25772<dd>Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.</dd> 25773<dt>Use full words</dt> 25774<dd>Don't abbreviate especially when the abbreviation is not obvious or not widely used. Use "data‑size", not "dsz" or "dsize". Use "interface" instead of "ifname", "if‑name", "iface", "if", or "intf".</dd> 25775<dt>Use <verb>-<units></dt> 25776<dd>Using the form <verb>-<units> or <verb>-<classifier>-<units> helps in making consistent, useful names, avoiding the situation where one app uses "sent‑packet" and another "packets‑sent" and another "packets‑we‑have‑sent". The <units> can be dropped when it is obvious, as can obvious words in the classification. Use "receive‑after‑window‑packets" instead of "received‑packets‑of‑data‑after‑window".</dd> 25777<dt>Reuse existing field names</dt> 25778<dd>Nothing's worse than writing expressions like:</dd> 25779</dl> | 25852 tag docsis-state { 25853 help "State of the DOCSIS interface"; 25854 type string; 25855 } 25856 25857 tag docsis-mode { 25858 help "DOCSIS mode (2.0/3.0) of the DOCSIS interface"; 25859 type string; --- 62 unchanged lines hidden (view full) --- 25922<dd>Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.</dd> 25923<dt>Use full words</dt> 25924<dd>Don't abbreviate especially when the abbreviation is not obvious or not widely used. Use "data‑size", not "dsz" or "dsize". Use "interface" instead of "ifname", "if‑name", "iface", "if", or "intf".</dd> 25925<dt>Use <verb>-<units></dt> 25926<dd>Using the form <verb>-<units> or <verb>-<classifier>-<units> helps in making consistent, useful names, avoiding the situation where one app uses "sent‑packet" and another "packets‑sent" and another "packets‑we‑have‑sent". The <units> can be dropped when it is obvious, as can obvious words in the classification. Use "receive‑after‑window‑packets" instead of "received‑packets‑of‑data‑after‑window".</dd> 25927<dt>Reuse existing field names</dt> 25928<dd>Nothing's worse than writing expressions like:</dd> 25929</dl> |
| 25780<div id="doc_figure_u.132"></div> <pre> | 25930<div id="doc_figure_u.139"></div> <pre> |
| 25781 if ($src1/process[pid == $pid]/name == 25782 $src2/proc-table/proc-list 25783 /proc-entry[process-id == $pid]/proc-name) { 25784 ... 25785 } 25786 </pre> <p id="doc_section_8_1_3_p_4">Find someone else who is expressing similar data and follow their fields and hierarchy. Remember the quote is not "Consistency is the hobgoblin of little minds", but "A foolish consistency is the hobgoblin of little minds".</p> 25787<p id="doc_section_8_1_3_p_5"> </p> 25788<dl> 25789<dt>Use containment as scoping</dt> 25790<dd>In the previous example, all the names are prefixed with "proc‑", which is redundant given that they are nested under the process table.</dd> 25791<dt>Think about your users</dt> | 25931 if ($src1/process[pid == $pid]/name == 25932 $src2/proc-table/proc-list 25933 /proc-entry[process-id == $pid]/proc-name) { 25934 ... 25935 } 25936 </pre> <p id="doc_section_8_1_3_p_4">Find someone else who is expressing similar data and follow their fields and hierarchy. Remember the quote is not "Consistency is the hobgoblin of little minds", but "A foolish consistency is the hobgoblin of little minds".</p> 25937<p id="doc_section_8_1_3_p_5"> </p> 25938<dl> 25939<dt>Use containment as scoping</dt> 25940<dd>In the previous example, all the names are prefixed with "proc‑", which is redundant given that they are nested under the process table.</dd> 25941<dt>Think about your users</dt> |
| 25792<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> | 25942<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> |
| 25793<dt>Don't use an arbitrary number postfix</dt> 25794<dd>What does "errors2" mean? No one will know. "errors‑after‑restart" would be a better choice. Think of your users, and think of the future. If you make "errors2", the next guy will happily make "errors3" and before you know it, someone will be asking what's the difference between errors37 and errors63.</dd> 25795<dt>Be consistent, uniform, unsurprising, and predictable</dt> 25796<dd>Think of your field vocabulary as an API. You want it useful, expressive, meaningful, direct, and obvious. You want the client application's programmer to move between without the need to understand a variety of opinions on how fields are named. They should see the system as a single cohesive whole, not a sack of cats.</dd> 25797</dl> 25798<p id="doc_section_8_1_3_p_6">Field names constitute the means by which client programmers interact with our system. By choosing wise names now, you are making their lives better.</p> 25799<p id="doc_section_8_1_3_p_7">After using "xolint" to find errors in your field descriptors, use "xolint -V" to spell check your field names and to detect different names for the same data. "dropped‑short" and "dropped‑too‑short" are both reasonable names, but using them both will lead users to ask the difference between the two fields. If there is no difference, use only one of the field names. If there is a difference, change the names to make that difference more obvious.</p> 25800</div> --- 32 unchanged lines hidden (view full) --- 25833</ul> 25834<div class="content"> 25835<h3 id="doc_section_8_2_1"> 25836<div class="self-section-number"> 25837<a href="#doc_section_8_2_1">8.2.1</a>�</div> 25838<a id="a-percent-sign-appearing-in-text-is-a-literal" href="#a-percent-sign-appearing-in-text-is-a-literal">'A percent sign appearing in text is a literal'</a> 25839</h3> 25840<p id="doc_section_8_2_1_p_1">The message "A percent sign appearing in text is a literal" can be caused by code like:</p> | 25943<dt>Don't use an arbitrary number postfix</dt> 25944<dd>What does "errors2" mean? No one will know. "errors‑after‑restart" would be a better choice. Think of your users, and think of the future. If you make "errors2", the next guy will happily make "errors3" and before you know it, someone will be asking what's the difference between errors37 and errors63.</dd> 25945<dt>Be consistent, uniform, unsurprising, and predictable</dt> 25946<dd>Think of your field vocabulary as an API. You want it useful, expressive, meaningful, direct, and obvious. You want the client application's programmer to move between without the need to understand a variety of opinions on how fields are named. They should see the system as a single cohesive whole, not a sack of cats.</dd> 25947</dl> 25948<p id="doc_section_8_1_3_p_6">Field names constitute the means by which client programmers interact with our system. By choosing wise names now, you are making their lives better.</p> 25949<p id="doc_section_8_1_3_p_7">After using "xolint" to find errors in your field descriptors, use "xolint -V" to spell check your field names and to detect different names for the same data. "dropped‑short" and "dropped‑too‑short" are both reasonable names, but using them both will lead users to ask the difference between the two fields. If there is no difference, use only one of the field names. If there is a difference, change the names to make that difference more obvious.</p> 25950</div> --- 32 unchanged lines hidden (view full) --- 25983</ul> 25984<div class="content"> 25985<h3 id="doc_section_8_2_1"> 25986<div class="self-section-number"> 25987<a href="#doc_section_8_2_1">8.2.1</a>�</div> 25988<a id="a-percent-sign-appearing-in-text-is-a-literal" href="#a-percent-sign-appearing-in-text-is-a-literal">'A percent sign appearing in text is a literal'</a> 25989</h3> 25990<p id="doc_section_8_2_1_p_1">The message "A percent sign appearing in text is a literal" can be caused by code like:</p> |
| 25841<div id="doc_figure_u.133"></div> <pre> | 25991<div id="doc_figure_u.140"></div> <pre> |
| 25842 xo_emit("cost: %d", cost); 25843 </pre> <p id="doc_section_8_2_1_p_3">This code should be replaced with code like:</p> | 25992 xo_emit("cost: %d", cost); 25993 </pre> <p id="doc_section_8_2_1_p_3">This code should be replaced with code like:</p> |
| 25844<div id="doc_figure_u.134"></div> <pre> | 25994<div id="doc_figure_u.141"></div> <pre> |
| 25845 xo_emit("{L:cost}: {:cost/%d}", cost); 25846 </pre> <p id="doc_section_8_2_1_p_5">This can be a bit surprising and could be a field that was not properly converted to a libxo-style format string.</p> 25847</div> 25848<div class="content"> 25849<h3 id="doc_section_8_2_2"> 25850<div class="self-section-number"> 25851<a href="#doc_section_8_2_2">8.2.2</a>�</div> 25852<a id="unknown-long-name-for-rolemodifier" href="#unknown-long-name-for-rolemodifier">'Unknown long name for role/modifier'</a> 25853</h3> 25854<p id="doc_section_8_2_2_p_1">The message "Unknown long name for role/modifier" can be caused by code like:</p> | 25995 xo_emit("{L:cost}: {:cost/%d}", cost); 25996 </pre> <p id="doc_section_8_2_1_p_5">This can be a bit surprising and could be a field that was not properly converted to a libxo-style format string.</p> 25997</div> 25998<div class="content"> 25999<h3 id="doc_section_8_2_2"> 26000<div class="self-section-number"> 26001<a href="#doc_section_8_2_2">8.2.2</a>�</div> 26002<a id="unknown-long-name-for-rolemodifier" href="#unknown-long-name-for-rolemodifier">'Unknown long name for role/modifier'</a> 26003</h3> 26004<p id="doc_section_8_2_2_p_1">The message "Unknown long name for role/modifier" can be caused by code like:</p> |
| 25855<div id="doc_figure_u.135"></div> <pre> | 26005<div id="doc_figure_u.142"></div> <pre> |
| 25856 xo_emit("{,humanization:value}", value); 25857 </pre> <p id="doc_section_8_2_2_p_3">This code should be replaced with code like:</p> | 26006 xo_emit("{,humanization:value}", value); 26007 </pre> <p id="doc_section_8_2_2_p_3">This code should be replaced with code like:</p> |
| 25858<div id="doc_figure_u.136"></div> <pre> | 26008<div id="doc_figure_u.143"></div> <pre> |
| 25859 xo_emit("{,humanize:value}", value); 25860 </pre> <p id="doc_section_8_2_2_p_5">The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.</p> 25861</div> 25862<div class="content"> 25863<h3 id="doc_section_8_2_3"> 25864<div class="self-section-number"> 25865<a href="#doc_section_8_2_3">8.2.3</a>�</div> 25866<a id="last-character-before-field-definition-is-a-field-type" href="#last-character-before-field-definition-is-a-field-type">'Last character before field definition is a field type'</a> 25867</h3> 25868<p id="doc_section_8_2_3_p_1">The message "Last character before field definition is a field type" can be caused by code like:</p> 25869<p id="doc_section_8_2_3_p_2">A common typo:</p> | 26009 xo_emit("{,humanize:value}", value); 26010 </pre> <p id="doc_section_8_2_2_p_5">The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.</p> 26011</div> 26012<div class="content"> 26013<h3 id="doc_section_8_2_3"> 26014<div class="self-section-number"> 26015<a href="#doc_section_8_2_3">8.2.3</a>�</div> 26016<a id="last-character-before-field-definition-is-a-field-type" href="#last-character-before-field-definition-is-a-field-type">'Last character before field definition is a field type'</a> 26017</h3> 26018<p id="doc_section_8_2_3_p_1">The message "Last character before field definition is a field type" can be caused by code like:</p> 26019<p id="doc_section_8_2_3_p_2">A common typo:</p> |
| 25870<div id="doc_figure_u.137"></div> <pre> | 26020<div id="doc_figure_u.144"></div> <pre> |
| 25871 xo_emit("{T:Min} T{:Max}"); 25872 </pre> <p id="doc_section_8_2_3_p_4">This code should be replaced with code like:</p> | 26021 xo_emit("{T:Min} T{:Max}"); 26022 </pre> <p id="doc_section_8_2_3_p_4">This code should be replaced with code like:</p> |
| 25873<div id="doc_figure_u.138"></div> <pre> | 26023<div id="doc_figure_u.145"></div> <pre> |
| 25874 xo_emit("{T:Min} {T:Max}"); 25875 </pre> <p id="doc_section_8_2_3_p_6">Twiddling the "{" and the field role is a common typo.</p> 25876</div> 25877<div class="content"> 25878<h3 id="doc_section_8_2_4"> 25879<div class="self-section-number"> 25880<a href="#doc_section_8_2_4">8.2.4</a>�</div> 25881<a id="encoding-format-uses-different-number-of-arguments" href="#encoding-format-uses-different-number-of-arguments">'Encoding format uses different number of arguments'</a> 25882</h3> 25883<p id="doc_section_8_2_4_p_1">The message "Encoding format uses different number of arguments" can be caused by code like:</p> | 26024 xo_emit("{T:Min} {T:Max}"); 26025 </pre> <p id="doc_section_8_2_3_p_6">Twiddling the "{" and the field role is a common typo.</p> 26026</div> 26027<div class="content"> 26028<h3 id="doc_section_8_2_4"> 26029<div class="self-section-number"> 26030<a href="#doc_section_8_2_4">8.2.4</a>�</div> 26031<a id="encoding-format-uses-different-number-of-arguments" href="#encoding-format-uses-different-number-of-arguments">'Encoding format uses different number of arguments'</a> 26032</h3> 26033<p id="doc_section_8_2_4_p_1">The message "Encoding format uses different number of arguments" can be caused by code like:</p> |
| 25884<div id="doc_figure_u.139"></div> <pre> | 26034<div id="doc_figure_u.146"></div> <pre> |
| 25885 xo_emit("{:name/%6.6s %%04d/%s}", name, number); 25886 </pre> <p id="doc_section_8_2_4_p_3">This code should be replaced with code like:</p> | 26035 xo_emit("{:name/%6.6s %%04d/%s}", name, number); 26036 </pre> <p id="doc_section_8_2_4_p_3">This code should be replaced with code like:</p> |
| 25887<div id="doc_figure_u.140"></div> <pre> | 26037<div id="doc_figure_u.147"></div> <pre> |
| 25888 xo_emit("{:name/%6.6s %04d/%s-%d}", name, number); 25889 </pre> <p id="doc_section_8_2_4_p_5">Both format should consume the same number of arguments off the stack</p> 25890</div> 25891<div class="content"> 25892<h3 id="doc_section_8_2_5"> 25893<div class="self-section-number"> 25894<a href="#doc_section_8_2_5">8.2.5</a>�</div> 25895<a id="only-one-field-role-can-be-used" href="#only-one-field-role-can-be-used">'Only one field role can be used'</a> 25896</h3> 25897<p id="doc_section_8_2_5_p_1">The message "Only one field role can be used" can be caused by code like:</p> | 26038 xo_emit("{:name/%6.6s %04d/%s-%d}", name, number); 26039 </pre> <p id="doc_section_8_2_4_p_5">Both format should consume the same number of arguments off the stack</p> 26040</div> 26041<div class="content"> 26042<h3 id="doc_section_8_2_5"> 26043<div class="self-section-number"> 26044<a href="#doc_section_8_2_5">8.2.5</a>�</div> 26045<a id="only-one-field-role-can-be-used" href="#only-one-field-role-can-be-used">'Only one field role can be used'</a> 26046</h3> 26047<p id="doc_section_8_2_5_p_1">The message "Only one field role can be used" can be caused by code like:</p> |
| 25898<div id="doc_figure_u.141"></div> <pre> | 26048<div id="doc_figure_u.148"></div> <pre> |
| 25899 xo_emit("{LT:Max}"); 25900 </pre> <p id="doc_section_8_2_5_p_3">This code should be replaced with code like:</p> | 26049 xo_emit("{LT:Max}"); 26050 </pre> <p id="doc_section_8_2_5_p_3">This code should be replaced with code like:</p> |
| 25901<div id="doc_figure_u.142"></div> <pre> | 26051<div id="doc_figure_u.149"></div> <pre> |
| 25902 xo_emit("{T:Max}"); 25903 </pre> </div> 25904<div class="content"> 25905<h3 id="doc_section_8_2_6"> 25906<div class="self-section-number"> 25907<a href="#doc_section_8_2_6">8.2.6</a>�</div> 25908<a id="potential-missing-slash-after-c-d-n-l-or-t-with-format" href="#potential-missing-slash-after-c-d-n-l-or-t-with-format">'Potential missing slash after C, D, N, L, or T with format'</a> 25909</h3> 25910<p id="doc_section_8_2_6_p_1">The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:</p> | 26052 xo_emit("{T:Max}"); 26053 </pre> </div> 26054<div class="content"> 26055<h3 id="doc_section_8_2_6"> 26056<div class="self-section-number"> 26057<a href="#doc_section_8_2_6">8.2.6</a>�</div> 26058<a id="potential-missing-slash-after-c-d-n-l-or-t-with-format" href="#potential-missing-slash-after-c-d-n-l-or-t-with-format">'Potential missing slash after C, D, N, L, or T with format'</a> 26059</h3> 26060<p id="doc_section_8_2_6_p_1">The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:</p> |
| 25911<div id="doc_figure_u.143"></div> <pre> | 26061<div id="doc_figure_u.150"></div> <pre> |
| 25912 xo_emit("{T:%6.6s}\n", "Max"); 25913 </pre> <p id="doc_section_8_2_6_p_3">This code should be replaced with code like:</p> | 26062 xo_emit("{T:%6.6s}\n", "Max"); 26063 </pre> <p id="doc_section_8_2_6_p_3">This code should be replaced with code like:</p> |
| 25914<div id="doc_figure_u.144"></div> <pre> | 26064<div id="doc_figure_u.151"></div> <pre> |
| 25915 xo_emit("{T:/%6.6s}\n", "Max"); 25916 </pre> <p id="doc_section_8_2_6_p_5">The "%6.6s" will be a literal, not a field format. While it's possibly valid, it's likely a missing "/".</p> 25917</div> 25918<div class="content"> 25919<h3 id="doc_section_8_2_7"> 25920<div class="self-section-number"> 25921<a href="#doc_section_8_2_7">8.2.7</a>�</div> 25922<a id="an-encoding-format-cannot-be-given-roles-dnlt" href="#an-encoding-format-cannot-be-given-roles-dnlt">'An encoding format cannot be given (roles: DNLT)'</a> 25923</h3> 25924<p id="doc_section_8_2_7_p_1">The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:</p> | 26065 xo_emit("{T:/%6.6s}\n", "Max"); 26066 </pre> <p id="doc_section_8_2_6_p_5">The "%6.6s" will be a literal, not a field format. While it's possibly valid, it's likely a missing "/".</p> 26067</div> 26068<div class="content"> 26069<h3 id="doc_section_8_2_7"> 26070<div class="self-section-number"> 26071<a href="#doc_section_8_2_7">8.2.7</a>�</div> 26072<a id="an-encoding-format-cannot-be-given-roles-dnlt" href="#an-encoding-format-cannot-be-given-roles-dnlt">'An encoding format cannot be given (roles: DNLT)'</a> 26073</h3> 26074<p id="doc_section_8_2_7_p_1">The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:</p> |
| 25925<div id="doc_figure_u.145"></div> <pre> | 26075<div id="doc_figure_u.152"></div> <pre> |
| 25926 xo_emit("{T:Max//%s}", "Max"); 25927 </pre> <p id="doc_section_8_2_7_p_3">Fields with the C, D, N, L, and T roles are not emitted in the 'encoding' style (JSON, XML), so an encoding format would make no sense.</p> 25928</div> 25929<div class="content"> 25930<h3 id="doc_section_8_2_8"> 25931<div class="self-section-number"> 25932<a href="#doc_section_8_2_8">8.2.8</a>�</div> 25933<a id="format-cannot-be-given-when-content-is-present-roles-cdln" href="#format-cannot-be-given-when-content-is-present-roles-cdln">'Format cannot be given when content is present (roles: CDLN)'</a> 25934</h3> 25935<p id="doc_section_8_2_8_p_1">The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:</p> | 26076 xo_emit("{T:Max//%s}", "Max"); 26077 </pre> <p id="doc_section_8_2_7_p_3">Fields with the C, D, N, L, and T roles are not emitted in the 'encoding' style (JSON, XML), so an encoding format would make no sense.</p> 26078</div> 26079<div class="content"> 26080<h3 id="doc_section_8_2_8"> 26081<div class="self-section-number"> 26082<a href="#doc_section_8_2_8">8.2.8</a>�</div> 26083<a id="format-cannot-be-given-when-content-is-present-roles-cdln" href="#format-cannot-be-given-when-content-is-present-roles-cdln">'Format cannot be given when content is present (roles: CDLN)'</a> 26084</h3> 26085<p id="doc_section_8_2_8_p_1">The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:</p> |
| 25936<div id="doc_figure_u.146"></div> <pre> | 26086<div id="doc_figure_u.153"></div> <pre> |
| 25937 xo_emit("{N:Max/%6.6s}", "Max"); 25938 </pre> <p id="doc_section_8_2_8_p_3">Fields with the C, D, L, or N roles can't have both static literal content ("{L:Label}") and a format ("{L:/%s}"). This error will also occur when the content has a backslash in it, like "{N:Type of I/O}"; backslashes should be escaped, like "{N:Type of I\\/O}". Note the double backslash, one for handling 'C' strings, and one for libxo.</p> 25939</div> 25940<div class="content"> 25941<h3 id="doc_section_8_2_9"> 25942<div class="self-section-number"> 25943<a href="#doc_section_8_2_9">8.2.9</a>�</div> 25944<a id="field-has-color-without-fg--or-bg--role-c" href="#field-has-color-without-fg--or-bg--role-c">'Field has color without fg- or bg- (role: C)'</a> 25945</h3> 25946<p id="doc_section_8_2_9_p_1">The message "Field has color without fg- or bg- (role: C)" can be caused by code like:</p> | 26087 xo_emit("{N:Max/%6.6s}", "Max"); 26088 </pre> <p id="doc_section_8_2_8_p_3">Fields with the C, D, L, or N roles can't have both static literal content ("{L:Label}") and a format ("{L:/%s}"). This error will also occur when the content has a backslash in it, like "{N:Type of I/O}"; backslashes should be escaped, like "{N:Type of I\\/O}". Note the double backslash, one for handling 'C' strings, and one for libxo.</p> 26089</div> 26090<div class="content"> 26091<h3 id="doc_section_8_2_9"> 26092<div class="self-section-number"> 26093<a href="#doc_section_8_2_9">8.2.9</a>�</div> 26094<a id="field-has-color-without-fg--or-bg--role-c" href="#field-has-color-without-fg--or-bg--role-c">'Field has color without fg- or bg- (role: C)'</a> 26095</h3> 26096<p id="doc_section_8_2_9_p_1">The message "Field has color without fg- or bg- (role: C)" can be caused by code like:</p> |
| 25947<div id="doc_figure_u.147"></div> <pre> | 26097<div id="doc_figure_u.154"></div> <pre> |
| 25948 xo_emit("{C:green}{:foo}{C:}", x); 25949 </pre> <p id="doc_section_8_2_9_p_3">This code should be replaced with code like:</p> | 26098 xo_emit("{C:green}{:foo}{C:}", x); 26099 </pre> <p id="doc_section_8_2_9_p_3">This code should be replaced with code like:</p> |
| 25950<div id="doc_figure_u.148"></div> <pre> | 26100<div id="doc_figure_u.155"></div> <pre> |
| 25951 xo_emit("{C:fg-green}{:foo}{C:}", x); 25952 </pre> <p id="doc_section_8_2_9_p_5">Colors must be prefixed by either "fg‑" or "bg‑".</p> 25953</div> 25954<div class="content"> 25955<h3 id="doc_section_8_2_10"> 25956<div class="self-section-number"> 25957<a href="#doc_section_8_2_10">8.2.10</a>�</div> 25958<a id="field-has-invalid-color-or-effect-role-c" href="#field-has-invalid-color-or-effect-role-c">'Field has invalid color or effect (role: C)'</a> 25959</h3> 25960<p id="doc_section_8_2_10_p_1">The message "Field has invalid color or effect (role: C)" can be caused by code like:</p> | 26101 xo_emit("{C:fg-green}{:foo}{C:}", x); 26102 </pre> <p id="doc_section_8_2_9_p_5">Colors must be prefixed by either "fg‑" or "bg‑".</p> 26103</div> 26104<div class="content"> 26105<h3 id="doc_section_8_2_10"> 26106<div class="self-section-number"> 26107<a href="#doc_section_8_2_10">8.2.10</a>�</div> 26108<a id="field-has-invalid-color-or-effect-role-c" href="#field-has-invalid-color-or-effect-role-c">'Field has invalid color or effect (role: C)'</a> 26109</h3> 26110<p id="doc_section_8_2_10_p_1">The message "Field has invalid color or effect (role: C)" can be caused by code like:</p> |
| 25961<div id="doc_figure_u.149"></div> <pre> | 26111<div id="doc_figure_u.156"></div> <pre> |
| 25962 xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x); 25963 </pre> <p id="doc_section_8_2_10_p_3">This code should be replaced with code like:</p> | 26112 xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x); 26113 </pre> <p id="doc_section_8_2_10_p_3">This code should be replaced with code like:</p> |
| 25964<div id="doc_figure_u.150"></div> <pre> | 26114<div id="doc_figure_u.157"></div> <pre> |
| 25965 xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x); 25966 </pre> <p id="doc_section_8_2_10_p_5">The list of colors and effects are limited. The set of colors includes default, black, red, green, yellow, blue, magenta, cyan, and white, which must be prefixed by either "fg‑" or "bg‑". Effects are limited to bold, no-bold, underline, no-underline, inverse, no-inverse, normal, and reset. Values must be separated by commas.</p> 25967</div> 25968<div class="content"> 25969<h3 id="doc_section_8_2_11"> 25970<div class="self-section-number"> 25971<a href="#doc_section_8_2_11">8.2.11</a>�</div> 25972<a id="field-has-humanize-modifier-but-no-format-string" href="#field-has-humanize-modifier-but-no-format-string">'Field has humanize modifier but no format string'</a> 25973</h3> 25974<p id="doc_section_8_2_11_p_1">The message "Field has humanize modifier but no format string" can be caused by code like:</p> | 26115 xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x); 26116 </pre> <p id="doc_section_8_2_10_p_5">The list of colors and effects are limited. The set of colors includes default, black, red, green, yellow, blue, magenta, cyan, and white, which must be prefixed by either "fg‑" or "bg‑". Effects are limited to bold, no-bold, underline, no-underline, inverse, no-inverse, normal, and reset. Values must be separated by commas.</p> 26117</div> 26118<div class="content"> 26119<h3 id="doc_section_8_2_11"> 26120<div class="self-section-number"> 26121<a href="#doc_section_8_2_11">8.2.11</a>�</div> 26122<a id="field-has-humanize-modifier-but-no-format-string" href="#field-has-humanize-modifier-but-no-format-string">'Field has humanize modifier but no format string'</a> 26123</h3> 26124<p id="doc_section_8_2_11_p_1">The message "Field has humanize modifier but no format string" can be caused by code like:</p> |
| 25975<div id="doc_figure_u.151"></div> <pre> | 26125<div id="doc_figure_u.158"></div> <pre> |
| 25976 xo_emit("{h:value}", value); 25977 </pre> <p id="doc_section_8_2_11_p_3">This code should be replaced with code like:</p> | 26126 xo_emit("{h:value}", value); 26127 </pre> <p id="doc_section_8_2_11_p_3">This code should be replaced with code like:</p> |
| 25978<div id="doc_figure_u.152"></div> <pre> | 26128<div id="doc_figure_u.159"></div> <pre> |
| 25979 xo_emit("{h:value/%d}", value); 25980 </pre> <p id="doc_section_8_2_11_p_5">Humanization is only value for numbers, which are not likely to use the default format ("%s").</p> 25981</div> 25982<div class="content"> 25983<h3 id="doc_section_8_2_12"> 25984<div class="self-section-number"> 25985<a href="#doc_section_8_2_12">8.2.12</a>�</div> 25986<a id="field-has-hn--modifier-but-not-h-modifier" href="#field-has-hn--modifier-but-not-h-modifier">'Field has hn-* modifier but not 'h' modifier'</a> 25987</h3> 25988<p id="doc_section_8_2_12_p_1">The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:</p> | 26129 xo_emit("{h:value/%d}", value); 26130 </pre> <p id="doc_section_8_2_11_p_5">Humanization is only value for numbers, which are not likely to use the default format ("%s").</p> 26131</div> 26132<div class="content"> 26133<h3 id="doc_section_8_2_12"> 26134<div class="self-section-number"> 26135<a href="#doc_section_8_2_12">8.2.12</a>�</div> 26136<a id="field-has-hn--modifier-but-not-h-modifier" href="#field-has-hn--modifier-but-not-h-modifier">'Field has hn-* modifier but not 'h' modifier'</a> 26137</h3> 26138<p id="doc_section_8_2_12_p_1">The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:</p> |
| 25989<div id="doc_figure_u.153"></div> <pre> | 26139<div id="doc_figure_u.160"></div> <pre> |
| 25990 xo_emit("{,hn-1000:value}", value); 25991 </pre> <p id="doc_section_8_2_12_p_3">This code should be replaced with code like:</p> | 26140 xo_emit("{,hn-1000:value}", value); 26141 </pre> <p id="doc_section_8_2_12_p_3">This code should be replaced with code like:</p> |
| 25992<div id="doc_figure_u.154"></div> <pre> | 26142<div id="doc_figure_u.161"></div> <pre> |
| 25993 xo_emit("{h,hn-1000:value}", value); 25994 </pre> <p id="doc_section_8_2_12_p_5">The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.</p> 25995</div> 25996<div class="content"> 25997<h3 id="doc_section_8_2_13"> 25998<div class="self-section-number"> 25999<a href="#doc_section_8_2_13">8.2.13</a>�</div> 26000<a id="value-field-must-have-a-name-as-content" href="#value-field-must-have-a-name-as-content">'Value field must have a name (as content)")'</a> 26001</h3> 26002<p id="doc_section_8_2_13_p_1">The message "Value field must have a name (as content)")" can be caused by code like:</p> | 26143 xo_emit("{h,hn-1000:value}", value); 26144 </pre> <p id="doc_section_8_2_12_p_5">The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.</p> 26145</div> 26146<div class="content"> 26147<h3 id="doc_section_8_2_13"> 26148<div class="self-section-number"> 26149<a href="#doc_section_8_2_13">8.2.13</a>�</div> 26150<a id="value-field-must-have-a-name-as-content" href="#value-field-must-have-a-name-as-content">'Value field must have a name (as content)")'</a> 26151</h3> 26152<p id="doc_section_8_2_13_p_1">The message "Value field must have a name (as content)")" can be caused by code like:</p> |
| 26003<div id="doc_figure_u.155"></div> <pre> | 26153<div id="doc_figure_u.162"></div> <pre> |
| 26004 xo_emit("{:/%s}", "value"); 26005 </pre> <p id="doc_section_8_2_13_p_3">This code should be replaced with code like:</p> | 26154 xo_emit("{:/%s}", "value"); 26155 </pre> <p id="doc_section_8_2_13_p_3">This code should be replaced with code like:</p> |
| 26006<div id="doc_figure_u.156"></div> <pre> | 26156<div id="doc_figure_u.163"></div> <pre> |
| 26007 xo_emit("{:tag-name/%s}", "value"); 26008 </pre> <p id="doc_section_8_2_13_p_5">The field name is used for XML and JSON encodings. These tags names are static and must appear directly in the field descriptor.</p> 26009</div> 26010<div class="content"> 26011<h3 id="doc_section_8_2_14"> 26012<div class="self-section-number"> 26013<a href="#doc_section_8_2_14">8.2.14</a>�</div> 26014<a id="use-hyphens-not-underscores-for-value-field-name" href="#use-hyphens-not-underscores-for-value-field-name">'Use hyphens, not underscores, for value field name'</a> 26015</h3> 26016<p id="doc_section_8_2_14_p_1">The message "Use hyphens, not underscores, for value field name" can be caused by code like:</p> | 26157 xo_emit("{:tag-name/%s}", "value"); 26158 </pre> <p id="doc_section_8_2_13_p_5">The field name is used for XML and JSON encodings. These tags names are static and must appear directly in the field descriptor.</p> 26159</div> 26160<div class="content"> 26161<h3 id="doc_section_8_2_14"> 26162<div class="self-section-number"> 26163<a href="#doc_section_8_2_14">8.2.14</a>�</div> 26164<a id="use-hyphens-not-underscores-for-value-field-name" href="#use-hyphens-not-underscores-for-value-field-name">'Use hyphens, not underscores, for value field name'</a> 26165</h3> 26166<p id="doc_section_8_2_14_p_1">The message "Use hyphens, not underscores, for value field name" can be caused by code like:</p> |
| 26017<div id="doc_figure_u.157"></div> <pre> | 26167<div id="doc_figure_u.164"></div> <pre> |
| 26018 xo_emit("{:no_under_scores}", "bad"); 26019 </pre> <p id="doc_section_8_2_14_p_3">This code should be replaced with code like:</p> | 26168 xo_emit("{:no_under_scores}", "bad"); 26169 </pre> <p id="doc_section_8_2_14_p_3">This code should be replaced with code like:</p> |
| 26020<div id="doc_figure_u.158"></div> <pre> | 26170<div id="doc_figure_u.165"></div> <pre> |
| 26021 xo_emit("{:no-under-scores}", "bad"); 26022 </pre> <p id="doc_section_8_2_14_p_5">Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.</p> 26023</div> 26024<div class="content"> 26025<h3 id="doc_section_8_2_15"> 26026<div class="self-section-number"> 26027<a href="#doc_section_8_2_15">8.2.15</a>�</div> 26028<a id="value-field-name-cannot-start-with-digit" href="#value-field-name-cannot-start-with-digit">'Value field name cannot start with digit'</a> 26029</h3> 26030<p id="doc_section_8_2_15_p_1">The message "Value field name cannot start with digit" can be caused by code like:</p> | 26171 xo_emit("{:no-under-scores}", "bad"); 26172 </pre> <p id="doc_section_8_2_14_p_5">Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.</p> 26173</div> 26174<div class="content"> 26175<h3 id="doc_section_8_2_15"> 26176<div class="self-section-number"> 26177<a href="#doc_section_8_2_15">8.2.15</a>�</div> 26178<a id="value-field-name-cannot-start-with-digit" href="#value-field-name-cannot-start-with-digit">'Value field name cannot start with digit'</a> 26179</h3> 26180<p id="doc_section_8_2_15_p_1">The message "Value field name cannot start with digit" can be caused by code like:</p> |
| 26031<div id="doc_figure_u.159"></div> <pre> | 26181<div id="doc_figure_u.166"></div> <pre> |
| 26032 xo_emit("{:10-gig/}"); 26033 </pre> <p id="doc_section_8_2_15_p_3">This code should be replaced with code like:</p> | 26182 xo_emit("{:10-gig/}"); 26183 </pre> <p id="doc_section_8_2_15_p_3">This code should be replaced with code like:</p> |
| 26034<div id="doc_figure_u.160"></div> <pre> | 26184<div id="doc_figure_u.167"></div> <pre> |
| 26035 xo_emit("{:ten-gig/}"); 26036 </pre> <p id="doc_section_8_2_15_p_5">XML element names cannot start with a digit.</p> 26037</div> 26038<div class="content"> 26039<h3 id="doc_section_8_2_16"> 26040<div class="self-section-number"> 26041<a href="#doc_section_8_2_16">8.2.16</a>�</div> 26042<a id="value-field-name-should-be-lower-case" href="#value-field-name-should-be-lower-case">'Value field name should be lower case'</a> 26043</h3> 26044<p id="doc_section_8_2_16_p_1">The message "Value field name should be lower case" can be caused by code like:</p> | 26185 xo_emit("{:ten-gig/}"); 26186 </pre> <p id="doc_section_8_2_15_p_5">XML element names cannot start with a digit.</p> 26187</div> 26188<div class="content"> 26189<h3 id="doc_section_8_2_16"> 26190<div class="self-section-number"> 26191<a href="#doc_section_8_2_16">8.2.16</a>�</div> 26192<a id="value-field-name-should-be-lower-case" href="#value-field-name-should-be-lower-case">'Value field name should be lower case'</a> 26193</h3> 26194<p id="doc_section_8_2_16_p_1">The message "Value field name should be lower case" can be caused by code like:</p> |
| 26045<div id="doc_figure_u.161"></div> <pre> | 26195<div id="doc_figure_u.168"></div> <pre> |
| 26046 xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON"); 26047 </pre> <p id="doc_section_8_2_16_p_3">This code should be replaced with code like:</p> | 26196 xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON"); 26197 </pre> <p id="doc_section_8_2_16_p_3">This code should be replaced with code like:</p> |
| 26048<div id="doc_figure_u.162"></div> <pre> | 26198<div id="doc_figure_u.169"></div> <pre> |
| 26049 xo_emit("{:why-are-you-shouting}", "no reason"); 26050 </pre> <p id="doc_section_8_2_16_p_5">Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Lower case rules the seas.</p> 26051</div> 26052<div class="content"> 26053<h3 id="doc_section_8_2_17"> 26054<div class="self-section-number"> 26055<a href="#doc_section_8_2_17">8.2.17</a>�</div> 26056<a id="value-field-name-should-be-longer-than-two-characters" href="#value-field-name-should-be-longer-than-two-characters">'Value field name should be longer than two characters'</a> 26057</h3> 26058<p id="doc_section_8_2_17_p_1">The message "Value field name should be longer than two characters" can be caused by code like:</p> | 26199 xo_emit("{:why-are-you-shouting}", "no reason"); 26200 </pre> <p id="doc_section_8_2_16_p_5">Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Lower case rules the seas.</p> 26201</div> 26202<div class="content"> 26203<h3 id="doc_section_8_2_17"> 26204<div class="self-section-number"> 26205<a href="#doc_section_8_2_17">8.2.17</a>�</div> 26206<a id="value-field-name-should-be-longer-than-two-characters" href="#value-field-name-should-be-longer-than-two-characters">'Value field name should be longer than two characters'</a> 26207</h3> 26208<p id="doc_section_8_2_17_p_1">The message "Value field name should be longer than two characters" can be caused by code like:</p> |
| 26059<div id="doc_figure_u.163"></div> <pre> | 26209<div id="doc_figure_u.170"></div> <pre> |
| 26060 xo_emit("{:x}", "mumble"); 26061 </pre> <p id="doc_section_8_2_17_p_3">This code should be replaced with code like:</p> | 26210 xo_emit("{:x}", "mumble"); 26211 </pre> <p id="doc_section_8_2_17_p_3">This code should be replaced with code like:</p> |
| 26062<div id="doc_figure_u.164"></div> <pre> | 26212<div id="doc_figure_u.171"></div> <pre> |
| 26063 xo_emit("{:something-meaningful}", "mumble"); 26064 </pre> <p id="doc_section_8_2_17_p_5">Field names should be descriptive, and it's hard to be descriptive in less than two characters. Consider your users and try to make something more useful. Note that this error often occurs when the field type is placed after the colon ("{:T/%20s}"), instead of before it ("{T:/20s}").</p> 26065</div> 26066<div class="content"> 26067<h3 id="doc_section_8_2_18"> 26068<div class="self-section-number"> 26069<a href="#doc_section_8_2_18">8.2.18</a>�</div> 26070<a id="value-field-name-contains-invalid-character" href="#value-field-name-contains-invalid-character">'Value field name contains invalid character'</a> 26071</h3> 26072<p id="doc_section_8_2_18_p_1">The message "Value field name contains invalid character" can be caused by code like:</p> | 26213 xo_emit("{:something-meaningful}", "mumble"); 26214 </pre> <p id="doc_section_8_2_17_p_5">Field names should be descriptive, and it's hard to be descriptive in less than two characters. Consider your users and try to make something more useful. Note that this error often occurs when the field type is placed after the colon ("{:T/%20s}"), instead of before it ("{T:/20s}").</p> 26215</div> 26216<div class="content"> 26217<h3 id="doc_section_8_2_18"> 26218<div class="self-section-number"> 26219<a href="#doc_section_8_2_18">8.2.18</a>�</div> 26220<a id="value-field-name-contains-invalid-character" href="#value-field-name-contains-invalid-character">'Value field name contains invalid character'</a> 26221</h3> 26222<p id="doc_section_8_2_18_p_1">The message "Value field name contains invalid character" can be caused by code like:</p> |
| 26073<div id="doc_figure_u.165"></div> <pre> | 26223<div id="doc_figure_u.172"></div> <pre> |
| 26074 xo_emit("{:cost-in-$$/%u}", 15); 26075 </pre> <p id="doc_section_8_2_18_p_3">This code should be replaced with code like:</p> | 26224 xo_emit("{:cost-in-$$/%u}", 15); 26225 </pre> <p id="doc_section_8_2_18_p_3">This code should be replaced with code like:</p> |
| 26076<div id="doc_figure_u.166"></div> <pre> | 26226<div id="doc_figure_u.173"></div> <pre> |
| 26077 xo_emit("{:cost-in-dollars/%u}", 15); 26078 </pre> <p id="doc_section_8_2_18_p_5">An invalid character is often a sign of a typo, like "{:]}" instead of "{]:}". Field names are restricted to lower-case characters, digits, and hyphens.</p> 26079</div> 26080<div class="content"> 26081<h3 id="doc_section_8_2_19"> 26082<div class="self-section-number"> 26083<a href="#doc_section_8_2_19">8.2.19</a>�</div> 26084<a id="decoration-field-contains-invalid-character" href="#decoration-field-contains-invalid-character">'decoration field contains invalid character'</a> 26085</h3> 26086<p id="doc_section_8_2_19_p_1">The message "decoration field contains invalid character" can be caused by code like:</p> | 26227 xo_emit("{:cost-in-dollars/%u}", 15); 26228 </pre> <p id="doc_section_8_2_18_p_5">An invalid character is often a sign of a typo, like "{:]}" instead of "{]:}". Field names are restricted to lower-case characters, digits, and hyphens.</p> 26229</div> 26230<div class="content"> 26231<h3 id="doc_section_8_2_19"> 26232<div class="self-section-number"> 26233<a href="#doc_section_8_2_19">8.2.19</a>�</div> 26234<a id="decoration-field-contains-invalid-character" href="#decoration-field-contains-invalid-character">'decoration field contains invalid character'</a> 26235</h3> 26236<p id="doc_section_8_2_19_p_1">The message "decoration field contains invalid character" can be caused by code like:</p> |
| 26087<div id="doc_figure_u.167"></div> <pre> | 26237<div id="doc_figure_u.174"></div> <pre> |
| 26088 xo_emit("{D:not good}"); 26089 </pre> <p id="doc_section_8_2_19_p_3">This code should be replaced with code like:</p> | 26238 xo_emit("{D:not good}"); 26239 </pre> <p id="doc_section_8_2_19_p_3">This code should be replaced with code like:</p> |
| 26090<div id="doc_figure_u.168"></div> <pre> | 26240<div id="doc_figure_u.175"></div> <pre> |
| 26091 xo_emit("{D:((}{:good}{D:))}", "yes"); 26092 </pre> <p id="doc_section_8_2_19_p_5">This is minor, but fields should use proper roles. Decoration fields are meant to hold punctuation and other characters used to decorate the content, typically to make it more readable to human readers.</p> 26093</div> 26094<div class="content"> 26095<h3 id="doc_section_8_2_20"> 26096<div class="self-section-number"> 26097<a href="#doc_section_8_2_20">8.2.20</a>�</div> 26098<a id="anchor-content-should-be-decimal-width" href="#anchor-content-should-be-decimal-width">'Anchor content should be decimal width'</a> 26099</h3> 26100<p id="doc_section_8_2_20_p_1">The message "Anchor content should be decimal width" can be caused by code like:</p> | 26241 xo_emit("{D:((}{:good}{D:))}", "yes"); 26242 </pre> <p id="doc_section_8_2_19_p_5">This is minor, but fields should use proper roles. Decoration fields are meant to hold punctuation and other characters used to decorate the content, typically to make it more readable to human readers.</p> 26243</div> 26244<div class="content"> 26245<h3 id="doc_section_8_2_20"> 26246<div class="self-section-number"> 26247<a href="#doc_section_8_2_20">8.2.20</a>�</div> 26248<a id="anchor-content-should-be-decimal-width" href="#anchor-content-should-be-decimal-width">'Anchor content should be decimal width'</a> 26249</h3> 26250<p id="doc_section_8_2_20_p_1">The message "Anchor content should be decimal width" can be caused by code like:</p> |
| 26101<div id="doc_figure_u.169"></div> <pre> | 26251<div id="doc_figure_u.176"></div> <pre> |
| 26102 xo_emit("{[:mumble}"); 26103 </pre> <p id="doc_section_8_2_20_p_3">This code should be replaced with code like:</p> | 26252 xo_emit("{[:mumble}"); 26253 </pre> <p id="doc_section_8_2_20_p_3">This code should be replaced with code like:</p> |
| 26104<div id="doc_figure_u.170"></div> <pre> | 26254<div id="doc_figure_u.177"></div> <pre> |
| 26105 xo_emit("{[:32}"); 26106 </pre> <p id="doc_section_8_2_20_p_5">Anchors need an integer value to specify the width of the set of anchored fields. The value can be positive (for left padding/right justification) or negative (for right padding/left justification) and can appear in either the start or stop anchor field descriptor.</p> 26107</div> 26108<div class="content"> 26109<h3 id="doc_section_8_2_21"> 26110<div class="self-section-number"> 26111<a href="#doc_section_8_2_21">8.2.21</a>�</div> 26112<a id="anchor-format-should-be-d" href="#anchor-format-should-be-d">'Anchor format should be "%d"'</a> 26113</h3> 26114<p id="doc_section_8_2_21_p_1">The message "Anchor format should be "%d"" can be caused by code like:</p> | 26255 xo_emit("{[:32}"); 26256 </pre> <p id="doc_section_8_2_20_p_5">Anchors need an integer value to specify the width of the set of anchored fields. The value can be positive (for left padding/right justification) or negative (for right padding/left justification) and can appear in either the start or stop anchor field descriptor.</p> 26257</div> 26258<div class="content"> 26259<h3 id="doc_section_8_2_21"> 26260<div class="self-section-number"> 26261<a href="#doc_section_8_2_21">8.2.21</a>�</div> 26262<a id="anchor-format-should-be-d" href="#anchor-format-should-be-d">'Anchor format should be "%d"'</a> 26263</h3> 26264<p id="doc_section_8_2_21_p_1">The message "Anchor format should be "%d"" can be caused by code like:</p> |
| 26115<div id="doc_figure_u.171"></div> <pre> | 26265<div id="doc_figure_u.178"></div> <pre> |
| 26116 xo_emit("{[:/%s}"); 26117 </pre> <p id="doc_section_8_2_21_p_3">This code should be replaced with code like:</p> | 26266 xo_emit("{[:/%s}"); 26267 </pre> <p id="doc_section_8_2_21_p_3">This code should be replaced with code like:</p> |
| 26118<div id="doc_figure_u.172"></div> <pre> | 26268<div id="doc_figure_u.179"></div> <pre> |
| 26119 xo_emit("{[:/%d}"); 26120 </pre> <p id="doc_section_8_2_21_p_5">Anchors only grok integer values, and if the value is not static, if must be in an 'int' argument, represented by the "%d" format. Anything else is an error.</p> 26121</div> 26122<div class="content"> 26123<h3 id="doc_section_8_2_22"> 26124<div class="self-section-number"> 26125<a href="#doc_section_8_2_22">8.2.22</a>�</div> 26126<a id="anchor-cannot-have-both-format-and-encoding-format" href="#anchor-cannot-have-both-format-and-encoding-format">'Anchor cannot have both format and encoding format")'</a> 26127</h3> 26128<p id="doc_section_8_2_22_p_1">The message "Anchor cannot have both format and encoding format")" can be caused by code like:</p> | 26269 xo_emit("{[:/%d}"); 26270 </pre> <p id="doc_section_8_2_21_p_5">Anchors only grok integer values, and if the value is not static, if must be in an 'int' argument, represented by the "%d" format. Anything else is an error.</p> 26271</div> 26272<div class="content"> 26273<h3 id="doc_section_8_2_22"> 26274<div class="self-section-number"> 26275<a href="#doc_section_8_2_22">8.2.22</a>�</div> 26276<a id="anchor-cannot-have-both-format-and-encoding-format" href="#anchor-cannot-have-both-format-and-encoding-format">'Anchor cannot have both format and encoding format")'</a> 26277</h3> 26278<p id="doc_section_8_2_22_p_1">The message "Anchor cannot have both format and encoding format")" can be caused by code like:</p> |
| 26129<div id="doc_figure_u.173"></div> <pre> | 26279<div id="doc_figure_u.180"></div> <pre> |
| 26130 xo_emit("{[:32/%d}"); 26131 </pre> <p id="doc_section_8_2_22_p_3">This code should be replaced with code like:</p> | 26280 xo_emit("{[:32/%d}"); 26281 </pre> <p id="doc_section_8_2_22_p_3">This code should be replaced with code like:</p> |
| 26132<div id="doc_figure_u.174"></div> <pre> | 26282<div id="doc_figure_u.181"></div> <pre> |
| 26133 xo_emit("{[:32}"); 26134 </pre> <p id="doc_section_8_2_22_p_5">Anchors can have a static value or argument for the width, but cannot have both.</p> 26135</div> 26136<div class="content"> 26137<h3 id="doc_section_8_2_23"> 26138<div class="self-section-number"> 26139<a href="#doc_section_8_2_23">8.2.23</a>�</div> 26140<a id="max-width-only-valid-for-strings" href="#max-width-only-valid-for-strings">'Max width only valid for strings'</a> 26141</h3> 26142<p id="doc_section_8_2_23_p_1">The message "Max width only valid for strings" can be caused by code like:</p> | 26283 xo_emit("{[:32}"); 26284 </pre> <p id="doc_section_8_2_22_p_5">Anchors can have a static value or argument for the width, but cannot have both.</p> 26285</div> 26286<div class="content"> 26287<h3 id="doc_section_8_2_23"> 26288<div class="self-section-number"> 26289<a href="#doc_section_8_2_23">8.2.23</a>�</div> 26290<a id="max-width-only-valid-for-strings" href="#max-width-only-valid-for-strings">'Max width only valid for strings'</a> 26291</h3> 26292<p id="doc_section_8_2_23_p_1">The message "Max width only valid for strings" can be caused by code like:</p> |
| 26143<div id="doc_figure_u.175"></div> <pre> | 26293<div id="doc_figure_u.182"></div> <pre> |
| 26144 xo_emit("{:tag/%2.4.6d}", 55); 26145 </pre> <p id="doc_section_8_2_23_p_3">This code should be replaced with code like:</p> | 26294 xo_emit("{:tag/%2.4.6d}", 55); 26295 </pre> <p id="doc_section_8_2_23_p_3">This code should be replaced with code like:</p> |
| 26146<div id="doc_figure_u.176"></div> <pre> | 26296<div id="doc_figure_u.183"></div> <pre> |
| 26147 xo_emit("{:tag/%2.6d}", 55); 26148 </pre> <p id="doc_section_8_2_23_p_5">libxo allows a true 'max width' in addition to the traditional printf-style 'max number of bytes to use for input'. But this is supported only for string values, since it makes no sense for non-strings. This error may occur from a typo, like "{:tag/%6..6d}" where only one period should be used.</p> 26149</div> 26150</div> 26151</div> 26152<hr class="noprint"> 26153<div class="content"> 26154<h1 id="doc_section_9" class="np"> --- 23 unchanged lines hidden (view full) --- 26178<h2 id="doc_section_9_2"> 26179<div class="self-section-number"> 26180<a href="#doc_section_9_2">9.2</a>�</div> 26181<a id="howto-install-libxo" href="#howto-install-libxo">Howto: Install libxo</a> 26182</h2> 26183<p id="doc_section_9_2_p_1">libxo is open source, under a new BSD license. Source code is available on github, as are recent releases. To get the most current release, please visit:</p> 26184<p id="doc_section_9_2_p_2"> <a href="https://github.com/Juniper/libxo/releases">https://github.com/Juniper/libxo/releases</a></p> 26185<p id="doc_section_9_2_p_3">After downloading and untarring the source code, building involves the following steps:</p> | 26297 xo_emit("{:tag/%2.6d}", 55); 26298 </pre> <p id="doc_section_8_2_23_p_5">libxo allows a true 'max width' in addition to the traditional printf-style 'max number of bytes to use for input'. But this is supported only for string values, since it makes no sense for non-strings. This error may occur from a typo, like "{:tag/%6..6d}" where only one period should be used.</p> 26299</div> 26300</div> 26301</div> 26302<hr class="noprint"> 26303<div class="content"> 26304<h1 id="doc_section_9" class="np"> --- 23 unchanged lines hidden (view full) --- 26328<h2 id="doc_section_9_2"> 26329<div class="self-section-number"> 26330<a href="#doc_section_9_2">9.2</a>�</div> 26331<a id="howto-install-libxo" href="#howto-install-libxo">Howto: Install libxo</a> 26332</h2> 26333<p id="doc_section_9_2_p_1">libxo is open source, under a new BSD license. Source code is available on github, as are recent releases. To get the most current release, please visit:</p> 26334<p id="doc_section_9_2_p_2"> <a href="https://github.com/Juniper/libxo/releases">https://github.com/Juniper/libxo/releases</a></p> 26335<p id="doc_section_9_2_p_3">After downloading and untarring the source code, building involves the following steps:</p> |
| 26186<div id="doc_figure_u.177"></div> <pre> | 26336<div id="doc_figure_u.184"></div> <pre> |
| 26187 sh bin/setup.sh 26188 cd build 26189 ../configure 26190 make 26191 make test 26192 sudo make install 26193 </pre> <p id="doc_section_9_2_p_5">libxo uses a distinct "build" directory to keep generated files separated from source files.</p> 26194<p id="doc_section_9_2_p_6">Use "../configure --help" to display available configuration options, which include the following:</p> | 26337 sh bin/setup.sh 26338 cd build 26339 ../configure 26340 make 26341 make test 26342 sudo make install 26343 </pre> <p id="doc_section_9_2_p_5">libxo uses a distinct "build" directory to keep generated files separated from source files.</p> 26344<p id="doc_section_9_2_p_6">Use "../configure --help" to display available configuration options, which include the following:</p> |
| 26195<div id="doc_figure_u.178"></div> <pre> | 26345<div id="doc_figure_u.185"></div> <pre> |
| 26196 --enable-warnings Turn on compiler warnings 26197 --enable-debug Turn on debugging 26198 --enable-text-only Turn on text-only rendering 26199 --enable-printflike Enable use of GCC __printflike attribute 26200 --disable-libxo-options Turn off support for LIBXO_OPTIONS 26201 --with-gettext=PFX Specify location of gettext installation 26202 --with-libslax-prefix=PFX Specify location of libslax config 26203 </pre> <p id="doc_section_9_2_p_8">Compiler warnings are a very good thing, but recent compiler version have added some very pedantic checks. While every attempt is made to keep libxo code warning-free, warnings are now optional. If you are doing development work on libxo, it is required that you use --enable-warnings to keep the code warning free, but most users need not use this option.</p> 26204<p id="doc_section_9_2_p_9">libxo provides the --enable-text-only option to reduce the footprint of the library for smaller installations. XML, JSON, and HTML rendering logic is removed.</p> 26205<p id="doc_section_9_2_p_10">The gettext library does not provide a simple means of learning its location, but libxo will look for it in /usr and /opt/local. If installed elsewhere, the installer will need to provide this information using the --with-gettext=/dir/path option.</p> 26206<p id="doc_section_9_2_p_11">libslax is not required by libxo; it contains the "oxtradoc" program used to format documentation.</p> 26207<p id="doc_section_9_2_p_12">For additional information, see <a href="#building-libxo" title="Building libxo">Section�1.1.2</a>.</p> 26208</div> 26209<div class="content"> 26210<h2 id="doc_section_9_3"> 26211<div class="self-section-number"> 26212<a href="#doc_section_9_3">9.3</a>�</div> 26213<a id="howto-convert-command-line-applications" href="#howto-convert-command-line-applications">Howto: Convert command line applications</a> 26214</h2> | 26346 --enable-warnings Turn on compiler warnings 26347 --enable-debug Turn on debugging 26348 --enable-text-only Turn on text-only rendering 26349 --enable-printflike Enable use of GCC __printflike attribute 26350 --disable-libxo-options Turn off support for LIBXO_OPTIONS 26351 --with-gettext=PFX Specify location of gettext installation 26352 --with-libslax-prefix=PFX Specify location of libslax config 26353 </pre> <p id="doc_section_9_2_p_8">Compiler warnings are a very good thing, but recent compiler version have added some very pedantic checks. While every attempt is made to keep libxo code warning-free, warnings are now optional. If you are doing development work on libxo, it is required that you use --enable-warnings to keep the code warning free, but most users need not use this option.</p> 26354<p id="doc_section_9_2_p_9">libxo provides the --enable-text-only option to reduce the footprint of the library for smaller installations. XML, JSON, and HTML rendering logic is removed.</p> 26355<p id="doc_section_9_2_p_10">The gettext library does not provide a simple means of learning its location, but libxo will look for it in /usr and /opt/local. If installed elsewhere, the installer will need to provide this information using the --with-gettext=/dir/path option.</p> 26356<p id="doc_section_9_2_p_11">libslax is not required by libxo; it contains the "oxtradoc" program used to format documentation.</p> 26357<p id="doc_section_9_2_p_12">For additional information, see <a href="#building-libxo" title="Building libxo">Section�1.1.2</a>.</p> 26358</div> 26359<div class="content"> 26360<h2 id="doc_section_9_3"> 26361<div class="self-section-number"> 26362<a href="#doc_section_9_3">9.3</a>�</div> 26363<a id="howto-convert-command-line-applications" href="#howto-convert-command-line-applications">Howto: Convert command line applications</a> 26364</h2> |
| 26215<div id="doc_figure_u.179"></div> <pre> | 26365<div id="doc_figure_u.186"></div> <pre> |
| 26216 How do I convert an existing command line application? 26217 </pre> <p id="doc_section_9_3_p_2">There are three basic steps for converting command line application to use libxo.</p> 26218<p id="doc_section_9_3_p_3"> </p> 26219<ul> 26220<li>Setting up the context</li> 26221<li>Converting printf calls</li> 26222<li>Creating hierarchy</li> 26223<li>Converting error functions</li> --- 7 unchanged lines hidden (view full) --- 26231</ul> 26232<div class="content"> 26233<h3 id="doc_section_9_3_1"> 26234<div class="self-section-number"> 26235<a href="#doc_section_9_3_1">9.3.1</a>�</div> 26236<a id="setting-up-the-context" href="#setting-up-the-context">Setting up the context</a> 26237</h3> 26238<p id="doc_section_9_3_1_p_1">To use libxo, you'll need to include the "xo.h" header file in your source code files:</p> | 26366 How do I convert an existing command line application? 26367 </pre> <p id="doc_section_9_3_p_2">There are three basic steps for converting command line application to use libxo.</p> 26368<p id="doc_section_9_3_p_3"> </p> 26369<ul> 26370<li>Setting up the context</li> 26371<li>Converting printf calls</li> 26372<li>Creating hierarchy</li> 26373<li>Converting error functions</li> --- 7 unchanged lines hidden (view full) --- 26381</ul> 26382<div class="content"> 26383<h3 id="doc_section_9_3_1"> 26384<div class="self-section-number"> 26385<a href="#doc_section_9_3_1">9.3.1</a>�</div> 26386<a id="setting-up-the-context" href="#setting-up-the-context">Setting up the context</a> 26387</h3> 26388<p id="doc_section_9_3_1_p_1">To use libxo, you'll need to include the "xo.h" header file in your source code files:</p> |
| 26239<div id="doc_figure_u.180"></div> <pre> | 26389<div id="doc_figure_u.187"></div> <pre> |
| 26240 #include <libxo/xo.h> 26241 </pre> <p id="doc_section_9_3_1_p_3">In your main() function, you'll need to call xo_parse_args to handling argument parsing (<a href="#xo_parse_args" title="Parsing Command-line Arguments (xo_parse_args)">Section�3.4.1</a>). This function removes libxo-specific arguments the program's argv and returns either the number of remaining arguments or -1 to indicate an error.</p> | 26390 #include <libxo/xo.h> 26391 </pre> <p id="doc_section_9_3_1_p_3">In your main() function, you'll need to call xo_parse_args to handling argument parsing (<a href="#xo_parse_args" title="Parsing Command-line Arguments (xo_parse_args)">Section�3.4.1</a>). This function removes libxo-specific arguments the program's argv and returns either the number of remaining arguments or -1 to indicate an error.</p> |
| 26242<div id="doc_figure_u.181"></div> <pre> | 26392<div id="doc_figure_u.188"></div> <pre> |
| 26243 int main (int argc, char **argv) 26244 { 26245 argc = xo_parse_args(argc, argv); 26246 if (argc < 0) 26247 return argc; 26248 .... 26249 } | 26393 int main (int argc, char **argv) 26394 { 26395 argc = xo_parse_args(argc, argv); 26396 if (argc < 0) 26397 return argc; 26398 .... 26399 } |
| 26250 </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> 26251<div id="doc_figure_u.182"></div> <pre> | 26400 </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> 26401<div id="doc_figure_u.189"></div> <pre> |
| 26252 atexit(xo_finish_atexit); 26253 </pre> </div> 26254<div class="content"> 26255<h3 id="doc_section_9_3_2"> 26256<div class="self-section-number"> 26257<a href="#doc_section_9_3_2">9.3.2</a>�</div> 26258<a id="converting-printf-calls" href="#converting-printf-calls">Converting printf Calls</a> 26259</h3> 26260<p id="doc_section_9_3_2_p_1">The second task is inspecting code for printf(3) calls and replacing them with xo_emit() calls. The format strings are similar in task, but libxo format strings wrap output fields in braces. The following two calls produce identical text output:</p> | 26402 atexit(xo_finish_atexit); 26403 </pre> </div> 26404<div class="content"> 26405<h3 id="doc_section_9_3_2"> 26406<div class="self-section-number"> 26407<a href="#doc_section_9_3_2">9.3.2</a>�</div> 26408<a id="converting-printf-calls" href="#converting-printf-calls">Converting printf Calls</a> 26409</h3> 26410<p id="doc_section_9_3_2_p_1">The second task is inspecting code for printf(3) calls and replacing them with xo_emit() calls. The format strings are similar in task, but libxo format strings wrap output fields in braces. The following two calls produce identical text output:</p> |
| 26261<div id="doc_figure_u.183"></div> <pre> | 26411<div id="doc_figure_u.190"></div> <pre> |
| 26262 printf("There are %d %s events\n", count, etype); 26263 xo_emit("There are {:count/%d} {:event} events\n", count, etype); 26264 </pre> <p id="doc_section_9_3_2_p_3">"count" and "event" are used as names for JSON and XML output. The "count" field uses the format "%d" and "event" uses the default "%s" format. Both are "value" roles, which is the default role.</p> 26265<p id="doc_section_9_3_2_p_4">Since text outside of output fields is passed verbatim, other roles are less important, but their proper use can help make output more useful. The "note" and "label" roles allow HTML output to recognize the relationship between text and the associated values, allowing appropriate "hover" and "onclick" behavior. Using the "units" role allows the presentation layer to perform conversions when needed. The "warning" and "error" roles allows use of color and font to draw attention to warnings. The "padding" role makes the use of vital whitespace more clear (<a href="#padding-role" title="The Padding Role ({P:})">Section�2.2.1.6</a>).</p> 26266<p id="doc_section_9_3_2_p_5">The "title" role indicates the headings of table and sections. This allows HTML output to use CSS to make this relationship more obvious.</p> | 26412 printf("There are %d %s events\n", count, etype); 26413 xo_emit("There are {:count/%d} {:event} events\n", count, etype); 26414 </pre> <p id="doc_section_9_3_2_p_3">"count" and "event" are used as names for JSON and XML output. The "count" field uses the format "%d" and "event" uses the default "%s" format. Both are "value" roles, which is the default role.</p> 26415<p id="doc_section_9_3_2_p_4">Since text outside of output fields is passed verbatim, other roles are less important, but their proper use can help make output more useful. The "note" and "label" roles allow HTML output to recognize the relationship between text and the associated values, allowing appropriate "hover" and "onclick" behavior. Using the "units" role allows the presentation layer to perform conversions when needed. The "warning" and "error" roles allows use of color and font to draw attention to warnings. The "padding" role makes the use of vital whitespace more clear (<a href="#padding-role" title="The Padding Role ({P:})">Section�2.2.1.6</a>).</p> 26416<p id="doc_section_9_3_2_p_5">The "title" role indicates the headings of table and sections. This allows HTML output to use CSS to make this relationship more obvious.</p> |
| 26267<div id="doc_figure_u.184"></div> <pre> | 26417<div id="doc_figure_u.191"></div> <pre> |
| 26268 printf("Statistics:\n"); 26269 xo_emit("{T:Statistics}:\n"); 26270 </pre> <p id="doc_section_9_3_2_p_7">The "color" roles controls foreground and background colors, as well as effects like bold and underline (see <a href="#color-role" title="The Color Role ({C:})">Section�2.2.1.1</a>).</p> | 26418 printf("Statistics:\n"); 26419 xo_emit("{T:Statistics}:\n"); 26420 </pre> <p id="doc_section_9_3_2_p_7">The "color" roles controls foreground and background colors, as well as effects like bold and underline (see <a href="#color-role" title="The Color Role ({C:})">Section�2.2.1.1</a>).</p> |
| 26271<div id="doc_figure_u.185"></div> <pre> | 26421<div id="doc_figure_u.192"></div> <pre> |
| 26272 xo_emit("{C:bold}required{C:}\n"); 26273 </pre> <p id="doc_section_9_3_2_p_9">Finally, the start- and stop-anchor roles allow justification and padding over multiple fields (see <a href="#anchor-role" title="The Anchor Roles ({[:} and {]:})">Section�2.2.1.10</a>).</p> | 26422 xo_emit("{C:bold}required{C:}\n"); 26423 </pre> <p id="doc_section_9_3_2_p_9">Finally, the start- and stop-anchor roles allow justification and padding over multiple fields (see <a href="#anchor-role" title="The Anchor Roles ({[:} and {]:})">Section�2.2.1.10</a>).</p> |
| 26274<div id="doc_figure_u.186"></div> <pre> | 26424<div id="doc_figure_u.193"></div> <pre> |
| 26275 snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max); 26276 printf("%30s", buf); 26277 26278 xo_emit("{[:30}({:minimum/%u}/{:average/%u}/{:maximum/%u}{]:}", 26279 min, ave, max); 26280 </pre> </div> 26281<div class="content"> 26282<h3 id="doc_section_9_3_3"> 26283<div class="self-section-number"> 26284<a href="#doc_section_9_3_3">9.3.3</a>�</div> 26285<a id="creating-hierarchy" href="#creating-hierarchy">Creating Hierarchy</a> 26286</h3> 26287<p id="doc_section_9_3_3_p_1">Text output doesn't have any sort of hierarchy, but XML and JSON require this. Typically applications use indentation to represent these relationship:</p> | 26425 snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max); 26426 printf("%30s", buf); 26427 26428 xo_emit("{[:30}({:minimum/%u}/{:average/%u}/{:maximum/%u}{]:}", 26429 min, ave, max); 26430 </pre> </div> 26431<div class="content"> 26432<h3 id="doc_section_9_3_3"> 26433<div class="self-section-number"> 26434<a href="#doc_section_9_3_3">9.3.3</a>�</div> 26435<a id="creating-hierarchy" href="#creating-hierarchy">Creating Hierarchy</a> 26436</h3> 26437<p id="doc_section_9_3_3_p_1">Text output doesn't have any sort of hierarchy, but XML and JSON require this. Typically applications use indentation to represent these relationship:</p> |
| 26288<div id="doc_figure_u.187"></div> <pre> | 26438<div id="doc_figure_u.194"></div> <pre> |
| 26289 printf("table %d\n", tnum); 26290 for (i = 0; i < tmax; i++) { 26291 printf(" %s %d\n", table[i].name, table[i].size); 26292 } 26293 26294 xo_emit("{T:/table %d}\n", tnum); 26295 xo_open_list("table"); 26296 for (i = 0; i < tmax; i++) { 26297 xo_open_instance("table"); 26298 xo_emit("{P: }{k:name} {:size/%d}\n", 26299 table[i].name, table[i].size); 26300 xo_close_instance("table"); 26301 } 26302 xo_close_list("table"); 26303 </pre> <p id="doc_section_9_3_3_p_3">The open and close list functions are used before and after the list, and the open and close instance functions are used before and after each instance with in the list.</p> 26304<p id="doc_section_9_3_3_p_4">Typically these developer looks for a "for" loop as an indication of where to put these calls.</p> 26305<p id="doc_section_9_3_3_p_5">In addition, the open and close container functions allow for organization levels of hierarchy.</p> | 26439 printf("table %d\n", tnum); 26440 for (i = 0; i < tmax; i++) { 26441 printf(" %s %d\n", table[i].name, table[i].size); 26442 } 26443 26444 xo_emit("{T:/table %d}\n", tnum); 26445 xo_open_list("table"); 26446 for (i = 0; i < tmax; i++) { 26447 xo_open_instance("table"); 26448 xo_emit("{P: }{k:name} {:size/%d}\n", 26449 table[i].name, table[i].size); 26450 xo_close_instance("table"); 26451 } 26452 xo_close_list("table"); 26453 </pre> <p id="doc_section_9_3_3_p_3">The open and close list functions are used before and after the list, and the open and close instance functions are used before and after each instance with in the list.</p> 26454<p id="doc_section_9_3_3_p_4">Typically these developer looks for a "for" loop as an indication of where to put these calls.</p> 26455<p id="doc_section_9_3_3_p_5">In addition, the open and close container functions allow for organization levels of hierarchy.</p> |
| 26306<div id="doc_figure_u.188"></div> <pre> | 26456<div id="doc_figure_u.195"></div> <pre> |
| 26307 printf("Paging information:\n"); 26308 printf(" Free: %lu\n", free); 26309 printf(" Active: %lu\n", active); 26310 printf(" Inactive: %lu\n", inactive); 26311 26312 xo_open_container("paging-information"); 26313 xo_emit("{P: }{L:Free: }{:free/%lu}\n", free); 26314 xo_emit("{P: }{L:Active: }{:active/%lu}\n", active); 26315 xo_emit("{P: }{L:Inactive: }{:inactive/%lu}\n", inactive); 26316 xo_close_container("paging-information"); 26317 </pre> </div> 26318<div class="content"> 26319<h3 id="doc_section_9_3_4"> 26320<div class="self-section-number"> 26321<a href="#doc_section_9_3_4">9.3.4</a>�</div> 26322<a id="converting-error-functions" href="#converting-error-functions">Converting Error Functions</a> 26323</h3> 26324<p id="doc_section_9_3_4_p_1">libxo provides variants of the standard error and warning functions, err(3) and warn(3). There are two variants, one for putting the errors on standard error, and the other writes the errors and warnings to the handle using the appropriate encoding style:</p> | 26457 printf("Paging information:\n"); 26458 printf(" Free: %lu\n", free); 26459 printf(" Active: %lu\n", active); 26460 printf(" Inactive: %lu\n", inactive); 26461 26462 xo_open_container("paging-information"); 26463 xo_emit("{P: }{L:Free: }{:free/%lu}\n", free); 26464 xo_emit("{P: }{L:Active: }{:active/%lu}\n", active); 26465 xo_emit("{P: }{L:Inactive: }{:inactive/%lu}\n", inactive); 26466 xo_close_container("paging-information"); 26467 </pre> </div> 26468<div class="content"> 26469<h3 id="doc_section_9_3_4"> 26470<div class="self-section-number"> 26471<a href="#doc_section_9_3_4">9.3.4</a>�</div> 26472<a id="converting-error-functions" href="#converting-error-functions">Converting Error Functions</a> 26473</h3> 26474<p id="doc_section_9_3_4_p_1">libxo provides variants of the standard error and warning functions, err(3) and warn(3). There are two variants, one for putting the errors on standard error, and the other writes the errors and warnings to the handle using the appropriate encoding style:</p> |
| 26325<div id="doc_figure_u.189"></div> <pre> | 26475<div id="doc_figure_u.196"></div> <pre> |
| 26326 err(1, "cannot open output file: %s", file); 26327 26328 xo_err(1, "cannot open output file: %s", file); 26329 xo_emit_err(1, "cannot open output file: {:filename}", file); 26330 </pre> </div> 26331</div> 26332<div class="content"><h2 id="doc_section_9_4"> 26333<div class="self-section-number"> 26334<a href="#doc_section_9_4">9.4</a>�</div> 26335<a id="howto-use-xo-in-shell-scripts" href="#howto-use-xo-in-shell-scripts">Howto: Use "xo" in Shell Scripts</a> 26336</h2></div> 26337<div class="content"> 26338<h2 id="doc_section_9_5"> 26339<div class="self-section-number"> 26340<a href="#doc_section_9_5">9.5</a>�</div> 26341<a id="howto-i18n" href="#howto-i18n">Howto: Internationalization (i18n)</a> 26342</h2> | 26476 err(1, "cannot open output file: %s", file); 26477 26478 xo_err(1, "cannot open output file: %s", file); 26479 xo_emit_err(1, "cannot open output file: {:filename}", file); 26480 </pre> </div> 26481</div> 26482<div class="content"><h2 id="doc_section_9_4"> 26483<div class="self-section-number"> 26484<a href="#doc_section_9_4">9.4</a>�</div> 26485<a id="howto-use-xo-in-shell-scripts" href="#howto-use-xo-in-shell-scripts">Howto: Use "xo" in Shell Scripts</a> 26486</h2></div> 26487<div class="content"> 26488<h2 id="doc_section_9_5"> 26489<div class="self-section-number"> 26490<a href="#doc_section_9_5">9.5</a>�</div> 26491<a id="howto-i18n" href="#howto-i18n">Howto: Internationalization (i18n)</a> 26492</h2> |
| 26343<div id="doc_figure_u.190"></div> <pre> | 26493<div id="doc_figure_u.197"></div> <pre> |
| 26344 How do I use libxo to support internationalization? 26345 </pre> <p id="doc_section_9_5_p_2">libxo allows format and field strings to be used a keys into message catalogs to enable translation into a user's native language by invoking the standard gettext(3) functions.</p> 26346<p id="doc_section_9_5_p_3">gettext setup is a bit complicated: text strings are extracted from source files into "portable object template" (.pot) files using the "xgettext" command. For each language, this template file is used as the source for a message catalog in the "portable object" (.po) format, which are translated by hand and compiled into "machine object" (.mo) files using the "msgfmt" command. The .mo files are then typically installed in the /usr/share/locale or /opt/local/share/locale directories. At run time, the user's language settings are used to select a .mo file which is searched for matching messages. Text strings in the source code are used as keys to look up the native language strings in the .mo file.</p> 26347<p id="doc_section_9_5_p_4">Since the xo_emit format string is used as the key into the message catalog, libxo removes unimportant field formatting and modifiers from the format string before use so that minor formatting changes will not impact the expensive translation process. We don't want a developer change such as changing "/%06d" to "/%08d" to force hand inspection of all .po files. The simplified version can be generated for a single message using the "xopo -s <text>" command, or an entire .pot can be translated using the "xopo -f <input> -o <output>" command.</p> | 26494 How do I use libxo to support internationalization? 26495 </pre> <p id="doc_section_9_5_p_2">libxo allows format and field strings to be used a keys into message catalogs to enable translation into a user's native language by invoking the standard gettext(3) functions.</p> 26496<p id="doc_section_9_5_p_3">gettext setup is a bit complicated: text strings are extracted from source files into "portable object template" (.pot) files using the "xgettext" command. For each language, this template file is used as the source for a message catalog in the "portable object" (.po) format, which are translated by hand and compiled into "machine object" (.mo) files using the "msgfmt" command. The .mo files are then typically installed in the /usr/share/locale or /opt/local/share/locale directories. At run time, the user's language settings are used to select a .mo file which is searched for matching messages. Text strings in the source code are used as keys to look up the native language strings in the .mo file.</p> 26497<p id="doc_section_9_5_p_4">Since the xo_emit format string is used as the key into the message catalog, libxo removes unimportant field formatting and modifiers from the format string before use so that minor formatting changes will not impact the expensive translation process. We don't want a developer change such as changing "/%06d" to "/%08d" to force hand inspection of all .po files. The simplified version can be generated for a single message using the "xopo -s <text>" command, or an entire .pot can be translated using the "xopo -f <input> -o <output>" command.</p> |
| 26348<div id="doc_figure_u.191"></div> <pre> | 26498<div id="doc_figure_u.198"></div> <pre> |
| 26349 EXAMPLE: 26350 % xopo -s "There are {:count/%u} {:event/%.6s} events\n" 26351 There are {:count} {:event} events\n 26352 26353 Recommended workflow: 26354 # Extract text messages 26355 xgettext --default-domain=foo --no-wrap \ 26356 --add-comments --keyword=xo_emit --keyword=xo_emit_h \ --- 16 unchanged lines hidden (view full) --- 26373 # Compile the finished file; Use of msgfmt's "-v" option is 26374 # strongly encouraged, so that "fuzzy" entries are reported. 26375 msgfmt -v -o po/my_lang/LC_MESSAGES/foo.mo po/my_lang/foo.po 26376 26377 # Install the .mo file 26378 sudo cp po/my_lang/LC_MESSAGES/foo.mo \ 26379 /opt/local/share/locale/my_lang/LC_MESSAGE/ 26380 </pre> <p id="doc_section_9_5_p_6">Once these steps are complete, you can use the "gettext" command to test the message catalog:</p> | 26499 EXAMPLE: 26500 % xopo -s "There are {:count/%u} {:event/%.6s} events\n" 26501 There are {:count} {:event} events\n 26502 26503 Recommended workflow: 26504 # Extract text messages 26505 xgettext --default-domain=foo --no-wrap \ 26506 --add-comments --keyword=xo_emit --keyword=xo_emit_h \ --- 16 unchanged lines hidden (view full) --- 26523 # Compile the finished file; Use of msgfmt's "-v" option is 26524 # strongly encouraged, so that "fuzzy" entries are reported. 26525 msgfmt -v -o po/my_lang/LC_MESSAGES/foo.mo po/my_lang/foo.po 26526 26527 # Install the .mo file 26528 sudo cp po/my_lang/LC_MESSAGES/foo.mo \ 26529 /opt/local/share/locale/my_lang/LC_MESSAGE/ 26530 </pre> <p id="doc_section_9_5_p_6">Once these steps are complete, you can use the "gettext" command to test the message catalog:</p> |
| 26381<div id="doc_figure_u.192"></div> <pre> | 26531<div id="doc_figure_u.199"></div> <pre> |
| 26382 gettext -d foo -e "some text" 26383 </pre> <p id="doc_section_9_5_p_8">Section Contents: </p> 26384<ul><li><a href="#i18n-and-xo_emit" title="i18n and xo_emit">Section�9.5.1</a></li></ul> 26385<div class="content"> 26386<h3 id="doc_section_9_5_1"> 26387<div class="self-section-number"> 26388<a href="#doc_section_9_5_1">9.5.1</a>�</div> 26389<a id="i18n-and-xo_emit" href="#i18n-and-xo_emit">i18n and xo_emit</a> 26390</h3> 26391<p id="doc_section_9_5_1_p_1">There are three features used in libxo used to support i18n:</p> 26392<p id="doc_section_9_5_1_p_2"> </p> 26393<ul> 26394<li>The "{G:}" role looks for a translation of the format string.</li> 26395<li>The "{g:}" modifier looks for a translation of the field.</li> 26396<li>The "{p:}" modifier looks for a pluralized version of the field.</li> 26397</ul> 26398<p id="doc_section_9_5_1_p_3">Together these three flags allows a single function call to give native language support, as well as libxo's normal XML, JSON, and HTML support.</p> | 26532 gettext -d foo -e "some text" 26533 </pre> <p id="doc_section_9_5_p_8">Section Contents: </p> 26534<ul><li><a href="#i18n-and-xo_emit" title="i18n and xo_emit">Section�9.5.1</a></li></ul> 26535<div class="content"> 26536<h3 id="doc_section_9_5_1"> 26537<div class="self-section-number"> 26538<a href="#doc_section_9_5_1">9.5.1</a>�</div> 26539<a id="i18n-and-xo_emit" href="#i18n-and-xo_emit">i18n and xo_emit</a> 26540</h3> 26541<p id="doc_section_9_5_1_p_1">There are three features used in libxo used to support i18n:</p> 26542<p id="doc_section_9_5_1_p_2"> </p> 26543<ul> 26544<li>The "{G:}" role looks for a translation of the format string.</li> 26545<li>The "{g:}" modifier looks for a translation of the field.</li> 26546<li>The "{p:}" modifier looks for a pluralized version of the field.</li> 26547</ul> 26548<p id="doc_section_9_5_1_p_3">Together these three flags allows a single function call to give native language support, as well as libxo's normal XML, JSON, and HTML support.</p> |
| 26399<div id="doc_figure_u.193"></div> <pre> | 26549<div id="doc_figure_u.200"></div> <pre> |
| 26400 printf(gettext("Received %zu %s from {g:server} server\n"), 26401 counter, ngettext("byte", "bytes", counter), 26402 gettext("web")); 26403 26404 xo_emit("{G:}Received {:received/%zu} {Ngp:byte,bytes} " 26405 "from {g:server} server\n", counter, "web"); 26406 </pre> <p id="doc_section_9_5_1_p_5">libxo will see the "{G:}" role and will first simplify the format string, removing field formats and modifiers.</p> | 26550 printf(gettext("Received %zu %s from {g:server} server\n"), 26551 counter, ngettext("byte", "bytes", counter), 26552 gettext("web")); 26553 26554 xo_emit("{G:}Received {:received/%zu} {Ngp:byte,bytes} " 26555 "from {g:server} server\n", counter, "web"); 26556 </pre> <p id="doc_section_9_5_1_p_5">libxo will see the "{G:}" role and will first simplify the format string, removing field formats and modifiers.</p> |
| 26407<div id="doc_figure_u.194"></div> <pre> | 26557<div id="doc_figure_u.201"></div> <pre> |
| 26408 "Received {:received} {N:byte,bytes} from {:server} server\n" 26409 </pre> <p id="doc_section_9_5_1_p_7">libxo calls gettext(3) with that string to get a localized version. If your language were Pig Latin, the result might look like:</p> | 26558 "Received {:received} {N:byte,bytes} from {:server} server\n" 26559 </pre> <p id="doc_section_9_5_1_p_7">libxo calls gettext(3) with that string to get a localized version. If your language were Pig Latin, the result might look like:</p> |
| 26410<div id="doc_figure_u.195"></div> <pre> | 26560<div id="doc_figure_u.202"></div> <pre> |
| 26411 "Eceivedray {:received} {N:byte,bytes} omfray " 26412 "{:server} erversay\n" 26413 </pre> <p id="doc_section_9_5_1_p_9">Note the field names do not change and they should not be translated. The contents of the note ("byte,bytes") should also not be translated, since the "g" modifier will need the untranslated value as the key for the message catalog.</p> 26414<p id="doc_section_9_5_1_p_10">The field "{g:server}" requests the rendered value of the field be translated using gettext(3). In this example, "web" would be used.</p> 26415<p id="doc_section_9_5_1_p_11">The field "{Ngp:byte,bytes}" shows an example of plural form using the "p" modifier with the "g" modifier. The base singular and plural forms appear inside the field, separated by a comma. At run time, libxo uses the previous field's numeric value to decide which form to use by calling ngettext(3).</p> 26416<p id="doc_section_9_5_1_p_12">If a domain name is needed, it can be supplied as the content of the {G:} role. Domain names remain in use throughout the format string until cleared with another domain name.</p> | 26561 "Eceivedray {:received} {N:byte,bytes} omfray " 26562 "{:server} erversay\n" 26563 </pre> <p id="doc_section_9_5_1_p_9">Note the field names do not change and they should not be translated. The contents of the note ("byte,bytes") should also not be translated, since the "g" modifier will need the untranslated value as the key for the message catalog.</p> 26564<p id="doc_section_9_5_1_p_10">The field "{g:server}" requests the rendered value of the field be translated using gettext(3). In this example, "web" would be used.</p> 26565<p id="doc_section_9_5_1_p_11">The field "{Ngp:byte,bytes}" shows an example of plural form using the "p" modifier with the "g" modifier. The base singular and plural forms appear inside the field, separated by a comma. At run time, libxo uses the previous field's numeric value to decide which form to use by calling ngettext(3).</p> 26566<p id="doc_section_9_5_1_p_12">If a domain name is needed, it can be supplied as the content of the {G:} role. Domain names remain in use throughout the format string until cleared with another domain name.</p> |
| 26417<div id="doc_figure_u.196"></div> <pre> | 26567<div id="doc_figure_u.203"></div> <pre> |
| 26418 printf(dgettext("dns", "Host %s not found: %d(%s)\n"), 26419 name, errno, dgettext("strerror", strerror(errno))); 26420 26421 xo_emit("{G:dns}Host {:hostname} not found: " 26422 "%d({G:strerror}{g:%m})\n", name, errno); 26423 </pre> </div> 26424</div> 26425</div> --- 8 unchanged lines hidden (view full) --- 26434<ul><li><a href="#unit-test" title="Unit Test">Section�10.1</a></li></ul> 26435<div class="content"> 26436<h2 id="doc_section_10_1"> 26437<div class="self-section-number"> 26438<a href="#doc_section_10_1">10.1</a>�</div> 26439<a id="unit-test" href="#unit-test">Unit Test</a> 26440</h2> 26441<p id="doc_section_10_1_p_1">Here is the unit test example:</p> | 26568 printf(dgettext("dns", "Host %s not found: %d(%s)\n"), 26569 name, errno, dgettext("strerror", strerror(errno))); 26570 26571 xo_emit("{G:dns}Host {:hostname} not found: " 26572 "%d({G:strerror}{g:%m})\n", name, errno); 26573 </pre> </div> 26574</div> 26575</div> --- 8 unchanged lines hidden (view full) --- 26584<ul><li><a href="#unit-test" title="Unit Test">Section�10.1</a></li></ul> 26585<div class="content"> 26586<h2 id="doc_section_10_1"> 26587<div class="self-section-number"> 26588<a href="#doc_section_10_1">10.1</a>�</div> 26589<a id="unit-test" href="#unit-test">Unit Test</a> 26590</h2> 26591<p id="doc_section_10_1_p_1">Here is the unit test example:</p> |
| 26442<div id="doc_figure_u.197"></div> <pre> | 26592<div id="doc_figure_u.204"></div> <pre> |
| 26443 int 26444 main (int argc, char **argv) 26445 { 26446 static char base_grocery[] = "GRO"; 26447 static char base_hardware[] = "HRD"; 26448 struct item { 26449 const char *i_title; 26450 int i_sold; --- 76 unchanged lines hidden (view full) --- 26527 xo_close_list("item"); 26528 xo_close_container("data"); 26529 26530 xo_close_container_h(NULL, "top"); 26531 26532 return 0; 26533 } 26534 </pre> <p id="doc_section_10_1_p_3">Text output:</p> | 26593 int 26594 main (int argc, char **argv) 26595 { 26596 static char base_grocery[] = "GRO"; 26597 static char base_hardware[] = "HRD"; 26598 struct item { 26599 const char *i_title; 26600 int i_sold; --- 76 unchanged lines hidden (view full) --- 26677 xo_close_list("item"); 26678 xo_close_container("data"); 26679 26680 xo_close_container_h(NULL, "top"); 26681 26682 return 0; 26683 } 26684 </pre> <p id="doc_section_10_1_p_3">Text output:</p> |
| 26535<div id="doc_figure_u.198"></div> <pre> | 26685<div id="doc_figure_u.205"></div> <pre> |
| 26536 % ./testxo --libxo text 26537 Item 'gum': 26538 Total sold: 1412.0 26539 In stock: 54 26540 On order: 10 26541 SKU: GRO-000-415 26542 Item 'rope': 26543 Total sold: 85.0 --- 16 unchanged lines hidden (view full) --- 26560 On order: 2 26561 SKU: GRO-000-2331 26562 Item 'fish': 26563 Total sold: 1321.0 26564 In stock: 45 26565 On order: 1 26566 SKU: GRO-000-533 26567 </pre> <p id="doc_section_10_1_p_5">JSON output:</p> | 26686 % ./testxo --libxo text 26687 Item 'gum': 26688 Total sold: 1412.0 26689 In stock: 54 26690 On order: 10 26691 SKU: GRO-000-415 26692 Item 'rope': 26693 Total sold: 85.0 --- 16 unchanged lines hidden (view full) --- 26710 On order: 2 26711 SKU: GRO-000-2331 26712 Item 'fish': 26713 Total sold: 1321.0 26714 In stock: 45 26715 On order: 1 26716 SKU: GRO-000-533 26717 </pre> <p id="doc_section_10_1_p_5">JSON output:</p> |
| 26568<div id="doc_figure_u.199"></div> <pre> | 26718<div id="doc_figure_u.206"></div> <pre> |
| 26569 % ./testxo --libxo json,pretty 26570 "top": { 26571 "data": { 26572 "item": [ 26573 { 26574 "name": "gum", 26575 "sold": 1412.0, 26576 "in-stock": 54, --- 38 unchanged lines hidden (view full) --- 26615 "in-stock": 45, 26616 "on-order": 1, 26617 "sku": "GRO-000-533" 26618 } 26619 ] 26620 } 26621 } 26622 </pre> <p id="doc_section_10_1_p_7">XML output:</p> | 26719 % ./testxo --libxo json,pretty 26720 "top": { 26721 "data": { 26722 "item": [ 26723 { 26724 "name": "gum", 26725 "sold": 1412.0, 26726 "in-stock": 54, --- 38 unchanged lines hidden (view full) --- 26765 "in-stock": 45, 26766 "on-order": 1, 26767 "sku": "GRO-000-533" 26768 } 26769 ] 26770 } 26771 } 26772 </pre> <p id="doc_section_10_1_p_7">XML output:</p> |
| 26623<div id="doc_figure_u.200"></div> <pre> | 26773<div id="doc_figure_u.207"></div> <pre> |
| 26624 % ./testxo --libxo pretty,xml 26625 <top> 26626 <data> 26627 <item> 26628 <name>gum</name> 26629 <sold>1412.0</sold> 26630 <in-stock>54</in-stock> 26631 <on-order>10</on-order> --- 34 unchanged lines hidden (view full) --- 26666 <sold>1321.0</sold> 26667 <in-stock>45</in-stock> 26668 <on-order>1</on-order> 26669 <sku>GRO-000-533</sku> 26670 </item> 26671 </data> 26672 </top> 26673 </pre> <p id="doc_section_10_1_p_9">HMTL output:</p> | 26774 % ./testxo --libxo pretty,xml 26775 <top> 26776 <data> 26777 <item> 26778 <name>gum</name> 26779 <sold>1412.0</sold> 26780 <in-stock>54</in-stock> 26781 <on-order>10</on-order> --- 34 unchanged lines hidden (view full) --- 26816 <sold>1321.0</sold> 26817 <in-stock>45</in-stock> 26818 <on-order>1</on-order> 26819 <sku>GRO-000-533</sku> 26820 </item> 26821 </data> 26822 </top> 26823 </pre> <p id="doc_section_10_1_p_9">HMTL output:</p> |
| 26674<div id="doc_figure_u.201"></div> <pre> | 26824<div id="doc_figure_u.208"></div> <pre> |
| 26675 % ./testxo --libxo pretty,html 26676 <div class="line"> 26677 <div class="label">Item</div> 26678 <div class="text"> '</div> 26679 <div class="data" data-tag="name">gum</div> 26680 <div class="text">':</div> 26681 </div> 26682 <div class="line"> --- 178 unchanged lines hidden (view full) --- 26861 </div> 26862 <div class="line"> 26863 <div class="padding"> </div> 26864 <div class="label">SKU</div> 26865 <div class="text">: </div> 26866 <div class="data" data-tag="sku">GRO-000-533</div> 26867 </div> 26868 </pre> <p id="doc_section_10_1_p_11">HTML output with xpath and info flags:</p> | 26825 % ./testxo --libxo pretty,html 26826 <div class="line"> 26827 <div class="label">Item</div> 26828 <div class="text"> '</div> 26829 <div class="data" data-tag="name">gum</div> 26830 <div class="text">':</div> 26831 </div> 26832 <div class="line"> --- 178 unchanged lines hidden (view full) --- 27011 </div> 27012 <div class="line"> 27013 <div class="padding"> </div> 27014 <div class="label">SKU</div> 27015 <div class="text">: </div> 27016 <div class="data" data-tag="sku">GRO-000-533</div> 27017 </div> 27018 </pre> <p id="doc_section_10_1_p_11">HTML output with xpath and info flags:</p> |
| 26869<div id="doc_figure_u.202"></div> <pre> | 27019<div id="doc_figure_u.209"></div> <pre> |
| 26870 % ./testxo --libxo pretty,html,xpath,info 26871 <div class="line"> 26872 <div class="label">Item</div> 26873 <div class="text"> '</div> 26874 <div class="data" data-tag="name" 26875 data-xpath="/top/data/item/name" data-type="string" 26876 data-help="Name of the item">gum</div> 26877 <div class="text">':</div> --- 257 unchanged lines hidden --- | 27020 % ./testxo --libxo pretty,html,xpath,info 27021 <div class="line"> 27022 <div class="label">Item</div> 27023 <div class="text"> '</div> 27024 <div class="data" data-tag="name" 27025 data-xpath="/top/data/item/name" data-type="string" 27026 data-help="Name of the item">gum</div> 27027 <div class="text">':</div> --- 257 unchanged lines hidden --- |