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 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 void 21.Fn xo_set_flags "xo_handle_t *handle" "unsigned flags" 22.Ft void 23.Fn xo_clear_flags "xo_handle_t *handle" "xo_xof_flags_t flags" 24.Sh DESCRIPTION 25Use the 26.Fn xo_set_flags 27function to set the flags for a 28.Nm libxo 29handle. 30To use the default handle, pass a 31.Dv NULL 32handle. 33.Pp 34The set of valid flags include: 35.Bl -tag -width "XOF_UNDERSCORES" 36.It Sy "Flag Description" 37.It Dv XOF_CLOSE_FP 38Close file pointer on 39.Xr xo_destroy 3 . 40This flag will trigger the call of the 41.Fn close_func 42(provided via 43.Xr xo_set_writer 3 ) 44when the handle is destroyed. 45.It Dv XOF_DTRT 46Enable "do the right thing" mode 47.It Dv XOF_INFO 48Display info data attributes (HTML) 49.It Dv XOF_KEYS 50Emit the key attribute (XML) 51.It Dv XOF_NO_ENV 52Do not use the 53.Ev LIBXO_OPTIONS 54environment variable. 55.It Dv XOF_PRETTY 56Make 'pretty printed' output, with the 57addition of indentation and newlines to enhance the readability of 58XML, JSON, and HTML output. 59Text output is not affected. 60.It Dv XOF_UNDERSCORES 61Replaces hyphens with underscores 62.It Dv XOF_UNITS 63Display units (XML and HMTL) 64.It Dv XOF_WARN 65Generate warnings for broken calls, triggering diagnostic 66output (on standard error) when the library notices errors during 67operations, or with arguments to functions. 68Without warnings enabled, such conditions are ignored. 69Warnings allow developers to debug their interaction with 70.Nm libxo . 71The function 72.Fn xo_failure 73can be used as a breakpoint for a debugger, 74regardless of whether warnings are enabled. 75.It Dv XOF_WARN_XML 76Generate warnings in XML on stdout 77.It Dv XOF_XPATH 78Emit XPath expressions (HTML) 79.It Dv XOF_COLUMNS 80Force 81.Xr xo_emit 3 82to return columns used 83.It Dv XOF_FLUSH 84Flush output after each 85.Xr xo_emit 3 86call 87.El 88.Pp 89If the style is 90.Dv XO_STYLE_HTML , 91the following additional flags can be 92used: 93.Bl -tag -width "XOF_UNDERSCORES" 94.It Sy "Flag Description" 95.It Dv XOF_XPATH 96Emit "data-xpath" attributes 97.It Dv XOF_INFO 98Emit additional informational fields for HTML 99output. 100See 101.Xr xo_set_info 3 102for details. 103.El 104.Pp 105The 106.Dv XOF_XPATH 107flag enables the emission of XPath expressions detailing 108the hierarchy of XML elements used to encode the data field, if the 109XPATH style of output were requested. 110.Pp 111If the style is 112.Dv XO_STYLE_XML , 113the following additional flags can be 114used: 115.Bl -tag -width "XOF_UNDERSCORES" 116.It Sy "Flag Description" 117.It XOF_KEYS 118Add 'key' attribute to the XML encoding for 119field definitions that use the 'k' modifier. 120The key attribute has 121the value "key". 122.El 123.Pp 124The 125.Fn xo_clear_flags 126function turns off the given flags in a specific 127handle. 128.Sh ADDITIONAL DOCUMENTATION 129Complete documentation can be found on github: 130.Bd -literal -offset indent 131http://juniper.github.io/libxo/libxo-manual.html 132.Ed 133.Pp 134.Nm libxo 135lives on github as: 136.Bd -literal -offset indent 137https://github.com/Juniper/libxo 138.Ed 139.Pp 140The latest release of 141.Nm libxo 142is available at: 143.Bd -literal -offset indent 144https://github.com/Juniper/libxo/releases 145.Ed 146.Sh SEE ALSO 147.Xr xo_emit 3 148.Sh HISTORY 149The 150.Nm libxo 151library was added in 152.Fx 11.0 . 153.Sh AUTHOR 154Phil Shafer 155