xref: /freebsd/contrib/libxo/libxo/xo_emit.3 (revision 2a58b312) 
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 xo_ssize_t
21.Fn xo_emit "const char *fmt"  "..."
22.Ft xo_ssize_t
23.Fn xo_emit_h "xo_handle_t *xop" "const char *fmt" "..."
24.Ft xo_ssize_t
25.Fn xo_emit_hv "xo_handle_t *xop" "const char *fmt" "va_list vap"
26.Sh DESCRIPTION
27The
28.Fn xo_emit
29function emits formatted output using the description in a format
30string along with a set of zero or more arguments, in a style similar
31to
32.Xr printf 3
33but using a more complex format description string, as described in
34.Xr xo_format 5 .
35.Pp
36.Fn xo_emit
37uses the default output handle, as described in
38.Xr libxo 3 ,
39where
40.Fn xo_emit_h
41uses an explicit handle.
42.Fn xo_emit_hv
43accepts a
44.Fa va_list
45for additional flexibility.
46.Sh EXAMPLES
47In this example, a set of four values is emitted using the following
48source 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
54Output can then be generated in various style, using
55the "--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
95returns a negative value on error.  If the
96.Nm XOF_COLUMNS
97flag has been turned on for the specific handle using
98.Xr xo_set_flags 3 ,
99then 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_emit_f 3 ,
104.Xo xo_emit_field 3 ,
105.Xr xo_format 5 ,
106.Xr libxo 3
107.Sh HISTORY
108The
109.Nm libxo
110library first appeared in
111.Fx 11.0 .
112.Sh AUTHORS
113.Nm libxo
114was written by
115.An Phil Shafer Aq Mt phil@freebsd.org .
116
117