1 2Formatting with libxo 3===================== 4 5Most unix commands emit text output aimed at humans. It is designed 6to be parsed and understood by a user. Humans are gifted at 7extracting details and pattern matching in such output. Often 8programmers need to extract information from this human-oriented 9output. Programmers use tools like grep, awk, and regular expressions 10to ferret out the pieces of information they need. Such solutions are 11fragile and require maintenance when output contents change or evolve, 12along with testing and validation. 13 14Modern tool developers favor encoding schemes like XML and JSON, 15which allow trivial parsing and extraction of data. Such formats are 16simple, well understood, hierarchical, easily parsed, and often 17integrate easier with common tools and environments. Changes to 18content can be done in ways that do not break existing users of the 19data, which can reduce maintenance costs and increase feature velocity. 20 21In addition, modern reality means that more output ends up in web 22browsers than in terminals, making HTML output valuable. 23 24libxo allows a single set of function calls in source code to generate 25traditional text output, as well as XML and JSON formatted data. HTML 26can also be generated; "<div>" elements surround the traditional text 27output, with attributes that detail how to render the data. 28 29A single libxo function call in source code is all that's required:: 30 31 xo_emit("Connecting to {:host}.{:domain}...\n", host, domain); 32 33 TEXT: 34 Connecting to my-box.example.com... 35 XML: 36 <host>my-box</host> 37 <domain>example.com</domain> 38 JSON: 39 "host": "my-box", 40 "domain": "example.com" 41 HTML: 42 <div class="line"> 43 <div class="text">Connecting to </div> 44 <div class="data" data-tag="host" 45 data-xpath="/top/host">my-box</div> 46 <div class="text">.</div> 47 <div class="data" data-tag="domain" 48 data-xpath="/top/domain">example.com</div> 49 <div class="text">...</div> 50 </div> 51 52Encoding Styles 53--------------- 54 55There are four encoding styles supported by libxo: 56 57- TEXT output can be display on a terminal session, allowing 58 compatibility with traditional command line usage. 59- XML output is suitable for tools like XPath and protocols like 60 NETCONF. 61- JSON output can be used for RESTful APIs and integration with 62 languages like Javascript and Python. 63- HTML can be matched with a small CSS file to permit rendering in any 64 HTML5 browser. 65 66In general, XML and JSON are suitable for encoding data, while TEXT is 67suited for terminal output and HTML is suited for display in a web 68browser (see :ref:`xohtml`). 69 70Text Output 71~~~~~~~~~~~ 72 73Most traditional programs generate text output on standard output, 74with contents like:: 75 76 36 ./src 77 40 ./bin 78 90 . 79 80In this example (taken from *du* source code), the code to generate this 81data might look like:: 82 83 printf("%d\t%s\n", num_blocks, path); 84 85Simple, direct, obvious. But it's only making text output. Imagine 86using a single code path to make TEXT, XML, JSON or HTML, deciding at 87run time which to generate. 88 89libxo expands on the idea of printf format strings to make a single 90format containing instructions for creating multiple output styles:: 91 92 xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path); 93 94This line will generate the same text output as the earlier printf 95call, but also has enough information to generate XML, JSON, and HTML. 96 97The following sections introduce the other formats. 98 99XML Output 100~~~~~~~~~~ 101 102XML output consists of a hierarchical set of elements, each encoded 103with a start tag and an end tag. The element should be named for data 104value that it is encoding:: 105 106 <item> 107 <blocks>36</blocks> 108 <path>./src</path> 109 </item> 110 <item> 111 <blocks>40</blocks> 112 <path>./bin</path> 113 </item> 114 <item> 115 <blocks>90</blocks> 116 <path>.</path> 117 </item> 118 119`XML`_ is the W3C standard for encoding data. 120 121.. _XML: https://w3c.org/TR/xml 122 123JSON Output 124~~~~~~~~~~~ 125 126JSON output consists of a hierarchical set of objects and lists, each 127encoded with a quoted name, a colon, and a value. If the value is a 128string, it must be quoted, but numbers are not quoted. Objects are 129encoded using braces; lists are encoded using square brackets. 130Data inside objects and lists is separated using commas:: 131 132 items: [ 133 { "blocks": 36, "path" : "./src" }, 134 { "blocks": 40, "path" : "./bin" }, 135 { "blocks": 90, "path" : "./" } 136 ] 137 138HTML Output 139~~~~~~~~~~~ 140 141HTML output is designed to allow the output to be rendered in a web 142browser with minimal effort. Each piece of output data is rendered 143inside a <div> element, with a class name related to the role of the 144data. By using a small set of class attribute values, a CSS 145stylesheet can render the HTML into rich text that mirrors the 146traditional text content. 147 148Additional attributes can be enabled to provide more details about the 149data, including data type, description, and an XPath location:: 150 151 <div class="line"> 152 <div class="data" data-tag="blocks">36</div> 153 <div class="padding"> </div> 154 <div class="data" data-tag="path">./src</div> 155 </div> 156 <div class="line"> 157 <div class="data" data-tag="blocks">40</div> 158 <div class="padding"> </div> 159 <div class="data" data-tag="path">./bin</div> 160 </div> 161 <div class="line"> 162 <div class="data" data-tag="blocks">90</div> 163 <div class="padding"> </div> 164 <div class="data" data-tag="path">./</div> 165 </div> 166