5 Most unix commands emit text output aimed at humans. It is designed
6 to be parsed and understood by a user. Humans are gifted at
7 extracting details and pattern matching in such output. Often
8 programmers need to extract information from this human-oriented
9 output. Programmers use tools like grep, awk, and regular expressions
10 to ferret out the pieces of information they need. Such solutions are
11 fragile and require maintenance when output contents change or evolve,
12 along with testing and validation.
14 Modern tool developers favor encoding schemes like XML and JSON,
15 which allow trivial parsing and extraction of data. Such formats are
16 simple, well understood, hierarchical, easily parsed, and often
17 integrate easier with common tools and environments. Changes to
18 content can be done in ways that do not break existing users of the
19 data, which can reduce maintenance costs and increase feature velocity.
21 In addition, modern reality means that more output ends up in web
22 browsers than in terminals, making HTML output valuable.
24 libxo allows a single set of function calls in source code to generate
25 traditional text output, as well as XML and JSON formatted data. HTML
26 can also be generated; "<div>" elements surround the traditional text
27 output, with attributes that detail how to render the data.
29 A single libxo function call in source code is all that's required::
31 xo_emit("Connecting to {:host}.{:domain}...\n", host, domain);
34 Connecting to my-box.example.com...
37 <domain>example.com</domain>
40 "domain": "example.com"
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>
55 There are four encoding styles supported by libxo:
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
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
66 In general, XML and JSON are suitable for encoding data, while TEXT is
67 suited for terminal output and HTML is suited for display in a web
68 browser (see :ref:`xohtml`).
73 Most traditional programs generate text output on standard output,
80 In this example (taken from *du* source code), the code to generate this
81 data might look like::
83 printf("%d\t%s\n", num_blocks, path);
85 Simple, direct, obvious. But it's only making text output. Imagine
86 using a single code path to make TEXT, XML, JSON or HTML, deciding at
87 run time which to generate.
89 libxo expands on the idea of printf format strings to make a single
90 format containing instructions for creating multiple output styles::
92 xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path);
94 This line will generate the same text output as the earlier printf
95 call, but also has enough information to generate XML, JSON, and HTML.
97 The following sections introduce the other formats.
102 XML output consists of a hierarchical set of elements, each encoded
103 with a start tag and an end tag. The element should be named for data
104 value that it is encoding::
119 `XML`_ is the W3C standard for encoding data.
121 .. _XML: https://w3c.org/TR/xml
126 JSON output consists of a hierarchical set of objects and lists, each
127 encoded with a quoted name, a colon, and a value. If the value is a
128 string, it must be quoted, but numbers are not quoted. Objects are
129 encoded using braces; lists are encoded using square brackets.
130 Data inside objects and lists is separated using commas::
133 { "blocks": 36, "path" : "./src" },
134 { "blocks": 40, "path" : "./bin" },
135 { "blocks": 90, "path" : "./" }
141 HTML output is designed to allow the output to be rendered in a web
142 browser with minimal effort. Each piece of output data is rendered
143 inside a <div> element, with a class name related to the role of the
144 data. By using a small set of class attribute values, a CSS
145 stylesheet can render the HTML into rich text that mirrors the
146 traditional text content.
148 Additional attributes can be enabled to provide more details about the
149 data, including data type, description, and an XPath location::
152 <div class="data" data-tag="blocks">36</div>
153 <div class="padding"> </div>
154 <div class="data" data-tag="path">./src</div>
157 <div class="data" data-tag="blocks">40</div>
158 <div class="padding"> </div>
159 <div class="data" data-tag="path">./bin</div>
162 <div class="data" data-tag="blocks">90</div>
163 <div class="padding"> </div>
164 <div class="data" data-tag="path">./</div>