contrib/libxo/doc/formatting.rst

   1
   2 Formatting with libxo
   3 =====================
   4
   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.
  13
  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.
  20
  21 In addition, modern reality means that more output ends up in web
  22 browsers than in terminals, making HTML output valuable.
  23
  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.
  28
  29 A 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
  52 Encoding Styles
  53 ---------------
  54
  55 There 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
  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`).
  69
  70 Text Output
  71 ~~~~~~~~~~~
  72
  73 Most traditional programs generate text output on standard output,
  74 with contents like::
  75
  76     36      ./src
  77     40      ./bin
  78     90      .
  79
  80 In this example (taken from *du* source code), the code to generate this
  81 data might look like::
  82
  83     printf("%d\t%s\n", num_blocks, path);
  84
  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.
  88
  89 libxo expands on the idea of printf format strings to make a single
  90 format containing instructions for creating multiple output styles::
  91
  92     xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path);
  93
  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.
  96
  97 The following sections introduce the other formats.
  98
  99 XML Output
 100 ~~~~~~~~~~
 101
 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::
 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
 123 JSON Output
 124 ~~~~~~~~~~~
 125
 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::
 131
 132     items: [
 133         { "blocks": 36, "path" : "./src" },
 134         { "blocks": 40, "path" : "./bin" },
 135         { "blocks": 90, "path" : "./" }
 136     ]
 137
 138 HTML Output
 139 ~~~~~~~~~~~
 140
 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.
 147
 148 Additional attributes can be enabled to provide more details about the
 149 data, 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>