contrib/libxo/doc/intro.rst

   1
   2 Introducing libxo
   3 =================
   4
   5 The libxo library allows an application to generate text, XML, JSON,
   6 and HTML output using a common set of function calls.  The application
   7 decides at run time which output style should be produced.  The
   8 application calls a function "xo_emit" to product output that is
   9 described in a format string.  A "field descriptor" tells libxo what
  10 the field is and what it means.  Each field descriptor is placed in
  11 braces with printf-like :ref:`format-strings`::
  12
  13     xo_emit(" {:lines/%7ju} {:words/%7ju} "
  14             "{:characters/%7ju} {d:filename/%s}\n",
  15             linect, wordct, charct, file);
  16
  17 Each field can have a role, with the 'value' role being the default,
  18 and the role tells libxo how and when to render that field (see
  19 :ref:`field-roles` for details).  Modifiers change how the field is
  20 rendered in different output styles (see :ref:`field-modifiers` for
  21 details.  Output can then be generated in various style, using the
  22 "--libxo" option::
  23
  24     % wc /etc/motd
  25           25     165    1140 /etc/motd
  26     % wc --libxo xml,pretty,warn /etc/motd
  27     <wc>
  28       <file>
  29         <lines>25</lines>
  30         <words>165</words>
  31         <characters>1140</characters>
  32         <filename>/etc/motd</filename>
  33       </file>
  34     </wc>
  35     % wc --libxo json,pretty,warn /etc/motd
  36     {
  37       "wc": {
  38         "file": [
  39           {
  40             "lines": 25,
  41             "words": 165,
  42             "characters": 1140,
  43             "filename": "/etc/motd"
  44           }
  45         ]
  46       }
  47     }
  48     % wc --libxo html,pretty,warn /etc/motd
  49     <div class="line">
  50       <div class="text"> </div>
  51       <div class="data" data-tag="lines">     25</div>
  52       <div class="text"> </div>
  53       <div class="data" data-tag="words">    165</div>
  54       <div class="text"> </div>
  55       <div class="data" data-tag="characters">   1140</div>
  56       <div class="text"> </div>
  57       <div class="data" data-tag="filename">/etc/motd</div>
  58     </div>
  59
  60 Same code path, same format strings, same information, but it's
  61 rendered in distinct styles based on run-time flags.
  62
  63 .. admonition:: Tale of Two Code Paths
  64
  65   You want to prepare for the future, but you need to live in the
  66   present.  You'd love a flying car, but need to get work done today.
  67   You want to support features like XML, JSON, and HTML rendering to
  68   allow integration with NETCONF, REST, and web browsers, but you need
  69   to make text output for command line users.
  70
  71   And you don't want multiple code paths that can't help but get out
  72   of sync::
  73
  74       /* None of this "if (xml) {... } else {...}"  logic */
  75       if (xml) {
  76           /* some code to make xml */
  77       } else {
  78           /* other code to make text */
  79           /* oops! forgot to add something on both clauses! */
  80       }
  81
  82       /* And ifdefs are right out. */
  83       #ifdef MAKE_XML
  84           /* icky */
  85       #else
  86           /* pooh */
  87       #endif
  88
  89   But you'd really, really like all the fancy features that modern
  90   encoding formats can provide.  libxo can help.