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