contrib/libxo/libxo/xo_emit.3

   1 .\" #
   2 .\" # Copyright (c) 2014, Juniper Networks, Inc.
   3 .\" # All rights reserved.
   4 .\" # This SOFTWARE is licensed under the LICENSE provided in the
   5 .\" # ../Copyright file. By downloading, installing, copying, or
   6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
   7 .\" # LICENSE.
   8 .\" # Phil Shafer, July 2014
   9 .\"
  10 .Dd December 4, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_emit , xo_emit_h , xo_emit_hv
  15 .Nd emit formatted output based on format string and arguments
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft int
  21 .Fn xo_emit "const char *fmt"  "..."
  22 .Ft int
  23 .Fn xo_emit_h "xo_handle_t *xop" "const char *fmt" "..."
  24 .Ft int
  25 .Fn xo_emit_hv "xo_handle_t *xop" "const char *fmt" "va_list vap"
  26 .Sh DESCRIPTION
  27 The
  28 .Fn xo_emit
  29 function emits formatted output using the description in a format
  30 string along with a set of zero or more arguments, in a style similar
  31 to
  32 .Xr printf 3
  33 but using a more complex format description string, as described in
  34 .Xr xo_format 5 .
  35 .Pp
  36 .Fn xo_emit
  37 uses the default output handle, as described in
  38 .Xr libxo 3 ,
  39 where
  40 .Fn xo_emit_h
  41 uses an explicit handle.
  42 .Fn xo_emit_hv
  43 accepts a
  44 .Fa va_list
  45 for additional flexibility.
  46 .Sh EXAMPLES
  47 In this example, a set of four values is emitted using the following
  48 source code:
  49 .Bd  -literal -offset indent
  50     xo_emit(" {:lines/%7ju} {:words/%7ju} "
  51             "{:characters/%7ju} {d:filename/%s}\n",
  52             linect, wordct, charct, file);
  53 .Ed
  54 Output can then be generated in various style, using
  55 the "--libxo" option:
  56 .Bd  -literal -offset indent
  57     % wc /etc/motd
  58           25     165    1140 /etc/motd
  59     % wc --libxo xml,pretty,warn /etc/motd
  60     <wc>
  61       <file>
  62         <lines>25</lines>
  63         <words>165</words>
  64         <characters>1140</characters>
  65         <filename>/etc/motd</filename>
  66       </file>
  67     </wc>
  68     % wc --libxo json,pretty,warn /etc/motd
  69     {
  70       "wc": {
  71         "file": [
  72           {
  73             "lines": 25,
  74             "words": 165,
  75             "characters": 1140,
  76             "filename": "/etc/motd"
  77           }
  78         ]
  79       }
  80     }
  81     % wc --libxo html,pretty,warn /etc/motd
  82     <div class="line">
  83       <div class="text"> </div>
  84       <div class="data" data-tag="lines">     25</div>
  85       <div class="text"> </div>
  86       <div class="data" data-tag="words">    165</div>
  87       <div class="text"> </div>
  88       <div class="data" data-tag="characters">   1140</div>
  89       <div class="text"> </div>
  90       <div class="data" data-tag="filename">/etc/motd</div>
  91     </div>
  92 .Ed
  93 .Sh RETURN CODE
  94 .Nm
  95 returns a negative value on error.  If the
  96 .Nm XOF_COLUMNS
  97 flag has been turned on for the specific handle using
  98 .Xr xo_set_flags 3 ,
  99 then the number of display columns consumed by the output will be returned.
 100 .Sh SEE ALSO
 101 .Xr xo_open_container 3 ,
 102 .Xr xo_open_list 3 ,
 103 .Xr xo_format 5 ,
 104 .Xr libxo 3
 105 .Sh HISTORY
 106 The
 107 .Nm libxo
 108 library first appeared in
 109 .Fx 11.0 .
 110 .Sh AUTHORS
 111 .Nm libxo
 112 was written by
 113 .An Phil Shafer Aq Mt phil@freebsd.org .
 114