contrib/libxo/libxo/xo.h

   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 otherwise
   6  * using the SOFTWARE, you agree to be bound by the terms of that
   7  * LICENSE.
   8  * Phil Shafer, July 2014
   9  */
  10
  11 /**
  12  * libxo provides a means of generating text, XML, and JSON output
  13  * using a single set of function calls, maximizing the value of output
  14  * while minimizing the cost/impact on the code.
  15  */
  16
  17 #ifndef INCLUDE_XO_H
  18 #define INCLUDE_XO_H
  19
  20 /** Formatting types */
  21 typedef unsigned xo_style_t;
  22 #define XO_STYLE_TEXT   0       /** Generate text output */
  23 #define XO_STYLE_XML    1       /** Generate XML output */
  24 #define XO_STYLE_JSON   2       /** Generate JSON output */
  25 #define XO_STYLE_HTML   3       /** Generate HTML output */
  26
  27 /** Flags for libxo */
  28 typedef unsigned long xo_xof_flags_t;
  29 #define XOF_CLOSE_FP    (1<<0)  /** Close file pointer on xo_close() */
  30 #define XOF_PRETTY      (1<<1)  /** Make 'pretty printed' output */
  31 #define XOF_DIV_OPEN    (1<<2)  /** Internal use only: a <div> is open */
  32 #define XOF_LINE_OPEN   (1<<3)  /** Internal use only: a <div class="line"> */
  33
  34 #define XOF_WARN        (1<<4)  /** Generate warnings for broken calls */
  35 #define XOF_XPATH       (1<<5)  /** Emit XPath attributes in HTML  */
  36 #define XOF_INFO        (1<<6)  /** Emit additional info fields (HTML) */
  37 #define XOF_WARN_XML    (1<<7)  /** Emit warnings in XML (on stdout) */
  38
  39 #define XOF_NO_ENV      (1<<8)  /** Don't look at the LIBXO_OPTIONS env var */
  40 #define XOF_NO_VA_ARG   (1<<9)  /** Don't advance va_list w/ va_arg() */
  41 #define XOF_DTRT        (1<<10) /** Enable "do the right thing" mode */
  42 #define XOF_KEYS        (1<<11) /** Flag 'key' fields for xml and json */
  43
  44 #define XOF_IGNORE_CLOSE (1<<12) /** Ignore errors on close tags */
  45 #define XOF_NOT_FIRST   (1<<13)  /* Not the first item (JSON)  */
  46 #define XOF_NO_LOCALE   (1<<14)  /** Don't bother with locale */
  47 #define XOF_TOP_EMITTED (1<<15)  /* The top JSON braces have been emitted  */
  48
  49 #define XOF_NO_TOP      (1<<16) /** Don't emit the top braces in JSON */
  50 #define XOF_ANCHOR      (1<<17) /** An anchor is in place  */
  51 #define XOF_UNITS       (1<<18) /** Encode units in XML */
  52 #define XOF_UNITS_PENDING (1<<19) /** We have a units-insertion pending */
  53
  54 #define XOF_UNDERSCORES (1<<20) /** Replace dashes with underscores (JSON)  */
  55 #define XOF_COLUMNS     (1<<21) /** xo_emit should return a column count */
  56 #define XOF_FLUSH       (1<<22) /** Flush after each xo_emit call */
  57
  58 /*
  59  * The xo_info_t structure provides a mapping between names and
  60  * additional data emitted via HTML.
  61  */
  62 typedef struct xo_info_s {
  63     const char *xi_name;        /* Name of the element */
  64     const char *xi_type;        /* Type of field */
  65     const char *xi_help;        /* Description of field */
  66 } xo_info_t;
  67
  68 struct xo_handle_s;             /* Opaque structure forward */
  69 typedef struct xo_handle_s xo_handle_t; /* Handle for XO output */
  70
  71 typedef int (*xo_write_func_t)(void *, const char *);
  72 typedef void (*xo_close_func_t)(void *);
  73 typedef void *(*xo_realloc_func_t)(void *, size_t);
  74 typedef void (*xo_free_func_t)(void *);
  75
  76 /*
  77  * The formatter function mirrors "vsnprintf", with an additional argument
  78  * of the xo handle.  The caller should return the number of bytes _needed_
  79  * to fit the data, even if this exceeds 'len'.
  80  */
  81 typedef int (*xo_formatter_t)(xo_handle_t *, char *, int,
  82                                 const char *, va_list);
  83 typedef void (*xo_checkpointer_t)(xo_handle_t *, va_list, int);
  84
  85 xo_handle_t *
  86 xo_create (xo_style_t style, xo_xof_flags_t flags);
  87
  88 xo_handle_t *
  89 xo_create_to_file (FILE *fp, xo_style_t style, xo_xof_flags_t flags);
  90
  91 void
  92 xo_destroy (xo_handle_t *xop);
  93
  94 void
  95 xo_set_writer (xo_handle_t *xop, void *opaque, xo_write_func_t write_func,
  96                xo_close_func_t close_func);
  97
  98 void
  99 xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func);
 100
 101 void
 102 xo_set_style (xo_handle_t *xop, xo_style_t style);
 103
 104 xo_style_t
 105 xo_get_style (xo_handle_t *xop);
 106
 107 int
 108 xo_set_style_name (xo_handle_t *xop, const char *style);
 109
 110 int
 111 xo_set_options (xo_handle_t *xop, const char *input);
 112
 113 xo_xof_flags_t
 114 xo_get_flags (xo_handle_t *xop);
 115
 116 void
 117 xo_set_flags (xo_handle_t *xop, xo_xof_flags_t flags);
 118
 119 void
 120 xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags);
 121
 122 void
 123 xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
 124
 125 void
 126 xo_set_formatter (xo_handle_t *xop, xo_formatter_t func, xo_checkpointer_t);
 127
 128 void
 129 xo_set_depth (xo_handle_t *xop, int depth);
 130
 131 int
 132 xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
 133
 134 int
 135 xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
 136
 137 int
 138 xo_emit (const char *fmt, ...);
 139
 140 int
 141 xo_open_container_h (xo_handle_t *xop, const char *name);
 142
 143 int
 144 xo_open_container (const char *name);
 145
 146 int
 147 xo_open_container_hd (xo_handle_t *xop, const char *name);
 148
 149 int
 150 xo_open_container_d (const char *name);
 151
 152 int
 153 xo_close_container_h (xo_handle_t *xop, const char *name);
 154
 155 int
 156 xo_close_container (const char *name);
 157
 158 int
 159 xo_close_container_hd (xo_handle_t *xop);
 160
 161 int
 162 xo_close_container_d (void);
 163
 164 int
 165 xo_open_list_h (xo_handle_t *xop, const char *name);
 166
 167 int
 168 xo_open_list (const char *name);
 169
 170 int
 171 xo_open_list_hd (xo_handle_t *xop, const char *name);
 172
 173 int
 174 xo_open_list_d (const char *name);
 175
 176 int
 177 xo_close_list_h (xo_handle_t *xop, const char *name);
 178
 179 int
 180 xo_close_list (const char *name);
 181
 182 int
 183 xo_close_list_hd (xo_handle_t *xop);
 184
 185 int
 186 xo_close_list_d (void);
 187
 188 int
 189 xo_open_instance_h (xo_handle_t *xop, const char *name);
 190
 191 int
 192 xo_open_instance (const char *name);
 193
 194 int
 195 xo_open_instance_hd (xo_handle_t *xop, const char *name);
 196
 197 int
 198 xo_open_instance_d (const char *name);
 199
 200 int
 201 xo_close_instance_h (xo_handle_t *xop, const char *name);
 202
 203 int
 204 xo_close_instance (const char *name);
 205
 206 int
 207 xo_close_instance_hd (xo_handle_t *xop);
 208
 209 int
 210 xo_close_instance_d (void);
 211
 212 int
 213 xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...);
 214
 215 int
 216 xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap);
 217
 218 int
 219 xo_attr (const char *name, const char *fmt, ...);
 220
 221 void
 222 xo_error_hv (xo_handle_t *xop, const char *fmt, va_list vap);
 223
 224 void
 225 xo_error_h (xo_handle_t *xop, const char *fmt, ...);
 226
 227 void
 228 xo_error (const char *fmt, ...);
 229
 230 void
 231 xo_flush_h (xo_handle_t *xop);
 232
 233 void
 234 xo_flush (void);
 235
 236 void
 237 xo_finish_h (xo_handle_t *xop);
 238
 239 void
 240 xo_finish (void);
 241
 242 void
 243 xo_set_leading_xpath (xo_handle_t *xop, const char *path);
 244
 245 void
 246 xo_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...);
 247
 248 void
 249 xo_warn_c (int code, const char *fmt, ...);
 250
 251 void
 252 xo_warn (const char *fmt, ...);
 253
 254 void
 255 xo_warnx (const char *fmt, ...);
 256
 257 void
 258 xo_err (int eval, const char *fmt, ...);
 259
 260 void
 261 xo_errx (int eval, const char *fmt, ...);
 262
 263 void
 264 xo_errc (int eval, int code, const char *fmt, ...);
 265
 266 void
 267 xo_message_hcv (xo_handle_t *xop, int code, const char *fmt, va_list vap);
 268
 269 void
 270 xo_message_hc (xo_handle_t *xop, int code, const char *fmt, ...);
 271
 272 void
 273 xo_message_c (int code, const char *fmt, ...);
 274
 275 void
 276 xo_message (const char *fmt, ...);
 277
 278 void
 279 xo_no_setlocale (void);
 280
 281 int
 282 xo_parse_args (int argc, char **argv);
 283
 284 /*
 285  * This is the "magic" number returned by libxo-supporting commands
 286  * when passed the equally magic "--libxo-check" option.  If you
 287  * return this, we can assume that since you know the magic handshake,
 288  * you'll happily handle future --libxo options and not do something
 289  * violent like reboot the box or create another hole in the ozone
 290  * layer.
 291  */
 292 #define XO_HAS_LIBXO    121
 293
 294 /*
 295  * externs for our version number strings
 296  */
 297 extern const char xo_version[];
 298 extern const char xo_version_extra[];
 299
 300 #endif /* INCLUDE_XO_H */