Deleted Added
sdiff udiff text old ( 282100 ) new ( 287111 )
full compact
xo.h (282100) xo.h (287111)
1/*
1/*
2 * Copyright (c) 2014, Juniper Networks, Inc.
2 * Copyright (c) 2014-2015, 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, JSON, and HTML output
13 * using a single set of function calls, maximizing the value of output
14 * while minimizing the cost/impact on the code.
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, JSON, and HTML 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 * Full documentation is available in ./doc/libxo.txt or online at:
17 * http://juniper.github.io/libxo/libxo-manual.html
15 */
16
17#ifndef INCLUDE_XO_H
18#define INCLUDE_XO_H
19
18 */
19
20#ifndef INCLUDE_XO_H
21#define INCLUDE_XO_H
22
23#include <stdio.h>
20#include <sys/types.h>
24#include <sys/types.h>
25#include <stdarg.h>
26#include <stdlib.h>
27#include <errno.h>
21
22#ifdef __dead2
23#define NORETURN __dead2
24#else
25#define NORETURN
26#endif /* __dead2 */
27
28/*

--- 5 unchanged lines hidden (view full) ---

34 */
35#if !defined(NO_PRINTFLIKE) && !defined(__linux__)
36#define PRINTFLIKE(_x, _y) __printflike(_x, _y)
37#else
38#define PRINTFLIKE(_x, _y)
39#endif /* NO_PRINTFLIKE */
40
41/** Formatting types */
28
29#ifdef __dead2
30#define NORETURN __dead2
31#else
32#define NORETURN
33#endif /* __dead2 */
34
35/*

--- 5 unchanged lines hidden (view full) ---

41 */
42#if !defined(NO_PRINTFLIKE) && !defined(__linux__)
43#define PRINTFLIKE(_x, _y) __printflike(_x, _y)
44#else
45#define PRINTFLIKE(_x, _y)
46#endif /* NO_PRINTFLIKE */
47
48/** Formatting types */
42typedef unsigned xo_style_t;
49typedef unsigned short xo_style_t;
43#define XO_STYLE_TEXT 0 /** Generate text output */
44#define XO_STYLE_XML 1 /** Generate XML output */
45#define XO_STYLE_JSON 2 /** Generate JSON output */
46#define XO_STYLE_HTML 3 /** Generate HTML output */
50#define XO_STYLE_TEXT 0 /** Generate text output */
51#define XO_STYLE_XML 1 /** Generate XML output */
52#define XO_STYLE_JSON 2 /** Generate JSON output */
53#define XO_STYLE_HTML 3 /** Generate HTML output */
54#define XO_STYLE_SDPARAMS 4 /* Generate syslog structured data params */
55#define XO_STYLE_ENCODER 5 /* Generate calls to external encoder */
47
48/** Flags for libxo */
49typedef unsigned long long xo_xof_flags_t;
50#define XOF_BIT(_n) ((xo_xof_flags_t) 1 << (_n))
51#define XOF_CLOSE_FP XOF_BIT(0) /** Close file pointer on xo_close() */
52#define XOF_PRETTY XOF_BIT(1) /** Make 'pretty printed' output */
56
57/** Flags for libxo */
58typedef unsigned long long xo_xof_flags_t;
59#define XOF_BIT(_n) ((xo_xof_flags_t) 1 << (_n))
60#define XOF_CLOSE_FP XOF_BIT(0) /** Close file pointer on xo_close() */
61#define XOF_PRETTY XOF_BIT(1) /** Make 'pretty printed' output */
53#define XOF_DIV_OPEN XOF_BIT(2) /** Internal use only: a <div> is open */
54#define XOF_LINE_OPEN XOF_BIT(3) /** Internal use only: <div class="line"> */
62#define XOF_LOG_SYSLOG XOF_BIT(2) /** Log (on stderr) our syslog content */
63#define XOF_RESV3 XOF_BIT(3) /* Unused */
55
56#define XOF_WARN XOF_BIT(4) /** Generate warnings for broken calls */
57#define XOF_XPATH XOF_BIT(5) /** Emit XPath attributes in HTML */
58#define XOF_INFO XOF_BIT(6) /** Emit additional info fields (HTML) */
59#define XOF_WARN_XML XOF_BIT(7) /** Emit warnings in XML (on stdout) */
60
61#define XOF_NO_ENV XOF_BIT(8) /** Don't look at LIBXO_OPTIONS env var */
62#define XOF_NO_VA_ARG XOF_BIT(9) /** Don't advance va_list w/ va_arg() */
63#define XOF_DTRT XOF_BIT(10) /** Enable "do the right thing" mode */
64#define XOF_KEYS XOF_BIT(11) /** Flag 'key' fields for xml and json */
65
66#define XOF_IGNORE_CLOSE XOF_BIT(12) /** Ignore errors on close tags */
67#define XOF_NOT_FIRST XOF_BIT(13) /* Not the first item (JSON) */
68#define XOF_NO_LOCALE XOF_BIT(14) /** Don't bother with locale */
64
65#define XOF_WARN XOF_BIT(4) /** Generate warnings for broken calls */
66#define XOF_XPATH XOF_BIT(5) /** Emit XPath attributes in HTML */
67#define XOF_INFO XOF_BIT(6) /** Emit additional info fields (HTML) */
68#define XOF_WARN_XML XOF_BIT(7) /** Emit warnings in XML (on stdout) */
69
70#define XOF_NO_ENV XOF_BIT(8) /** Don't look at LIBXO_OPTIONS env var */
71#define XOF_NO_VA_ARG XOF_BIT(9) /** Don't advance va_list w/ va_arg() */
72#define XOF_DTRT XOF_BIT(10) /** Enable "do the right thing" mode */
73#define XOF_KEYS XOF_BIT(11) /** Flag 'key' fields for xml and json */
74
75#define XOF_IGNORE_CLOSE XOF_BIT(12) /** Ignore errors on close tags */
76#define XOF_NOT_FIRST XOF_BIT(13) /* Not the first item (JSON) */
77#define XOF_NO_LOCALE XOF_BIT(14) /** Don't bother with locale */
69#define XOF_TOP_EMITTED XOF_BIT(15) /* The top JSON braces have been emitted */
78#define XOF_RESV15 XOF_BIT(15) /* Unused */
70
71#define XOF_NO_TOP XOF_BIT(16) /** Don't emit the top braces in JSON */
79
80#define XOF_NO_TOP XOF_BIT(16) /** Don't emit the top braces in JSON */
72#define XOF_ANCHOR XOF_BIT(17) /** An anchor is in place */
81#define XOF_RESV17 XOF_BIT(17) /* Unused */
73#define XOF_UNITS XOF_BIT(18) /** Encode units in XML */
82#define XOF_UNITS XOF_BIT(18) /** Encode units in XML */
74#define XOF_UNITS_PENDING XOF_BIT(19) /** We have a units-insertion pending */
83#define XOF_RESV19 XOF_BIT(19) /* Unused */
75
76#define XOF_UNDERSCORES XOF_BIT(20) /** Replace dashes with underscores (JSON)*/
77#define XOF_COLUMNS XOF_BIT(21) /** xo_emit should return a column count */
78#define XOF_FLUSH XOF_BIT(22) /** Flush after each xo_emit call */
79#define XOF_FLUSH_LINE XOF_BIT(23) /** Flush after each newline */
80
81#define XOF_NO_CLOSE XOF_BIT(24) /** xo_finish won't close open elements */
82#define XOF_COLOR_ALLOWED XOF_BIT(25) /** Allow color/effects to be enabled */
83#define XOF_COLOR XOF_BIT(26) /** Enable color and effects */
84
85#define XOF_UNDERSCORES XOF_BIT(20) /** Replace dashes with underscores (JSON)*/
86#define XOF_COLUMNS XOF_BIT(21) /** xo_emit should return a column count */
87#define XOF_FLUSH XOF_BIT(22) /** Flush after each xo_emit call */
88#define XOF_FLUSH_LINE XOF_BIT(23) /** Flush after each newline */
89
90#define XOF_NO_CLOSE XOF_BIT(24) /** xo_finish won't close open elements */
91#define XOF_COLOR_ALLOWED XOF_BIT(25) /** Allow color/effects to be enabled */
92#define XOF_COLOR XOF_BIT(26) /** Enable color and effects */
93#define XOF_NO_HUMANIZE XOF_BIT(27) /** Block the {h:} modifier */
84
94
95#define XOF_LOG_GETTEXT XOF_BIT(28) /** Log (stderr) gettext lookup strings */
96#define XOF_UTF8 XOF_BIT(29) /** Force text output to be UTF8 */
97
85/*
86 * The xo_info_t structure provides a mapping between names and
87 * additional data emitted via HTML.
88 */
89typedef struct xo_info_s {
90 const char *xi_name; /* Name of the element */
91 const char *xi_type; /* Type of field */
92 const char *xi_help; /* Description of field */
93} xo_info_t;
94
98/*
99 * The xo_info_t structure provides a mapping between names and
100 * additional data emitted via HTML.
101 */
102typedef struct xo_info_s {
103 const char *xi_name; /* Name of the element */
104 const char *xi_type; /* Type of field */
105 const char *xi_help; /* Description of field */
106} xo_info_t;
107
108#define XO_INFO_NULL NULL, NULL, NULL /* Use '{ XO_INFO_NULL }' to end lists */
109
95struct xo_handle_s; /* Opaque structure forward */
96typedef struct xo_handle_s xo_handle_t; /* Handle for XO output */
97
98typedef int (*xo_write_func_t)(void *, const char *);
99typedef void (*xo_close_func_t)(void *);
100typedef int (*xo_flush_func_t)(void *);
101typedef void *(*xo_realloc_func_t)(void *, size_t);
102typedef void (*xo_free_func_t)(void *);

--- 57 unchanged lines hidden (view full) ---

160xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
161
162int
163xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
164
165int
166xo_emit (const char *fmt, ...);
167
110struct xo_handle_s; /* Opaque structure forward */
111typedef struct xo_handle_s xo_handle_t; /* Handle for XO output */
112
113typedef int (*xo_write_func_t)(void *, const char *);
114typedef void (*xo_close_func_t)(void *);
115typedef int (*xo_flush_func_t)(void *);
116typedef void *(*xo_realloc_func_t)(void *, size_t);
117typedef void (*xo_free_func_t)(void *);

--- 57 unchanged lines hidden (view full) ---

175xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
176
177int
178xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
179
180int
181xo_emit (const char *fmt, ...);
182
183PRINTFLIKE(2, 0)
184static inline int
185xo_emit_hvp (xo_handle_t *xop, const char *fmt, va_list vap)
186{
187 return xo_emit_hv(xop, fmt, vap);
188}
189
190PRINTFLIKE(2, 3)
191static inline int
192xo_emit_hp (xo_handle_t *xop, const char *fmt, ...)
193{
194 va_list vap;
195 va_start(vap, fmt);
196 int rc = xo_emit_hv(xop, fmt, vap);
197 va_end(vap);
198 return rc;
199}
200
201PRINTFLIKE(1, 2)
202static inline int
203xo_emit_p (const char *fmt, ...)
204{
205 va_list vap;
206 va_start(vap, fmt);
207 int rc = xo_emit_hv(NULL, fmt, vap);
208 va_end(vap);
209 return rc;
210}
211
168int
169xo_open_container_h (xo_handle_t *xop, const char *name);
170
171int
172xo_open_container (const char *name);
173
174int
175xo_open_container_hd (xo_handle_t *xop, const char *name);

--- 99 unchanged lines hidden (view full) ---

275
276int
277xo_finish_h (xo_handle_t *xop);
278
279int
280xo_finish (void);
281
282void
212int
213xo_open_container_h (xo_handle_t *xop, const char *name);
214
215int
216xo_open_container (const char *name);
217
218int
219xo_open_container_hd (xo_handle_t *xop, const char *name);

--- 99 unchanged lines hidden (view full) ---

319
320int
321xo_finish_h (xo_handle_t *xop);
322
323int
324xo_finish (void);
325
326void
327xo_finish_atexit (void);
328
329void
283xo_set_leading_xpath (xo_handle_t *xop, const char *path);
284
285void
286xo_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
287
288void
289xo_warn_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
290

--- 8 unchanged lines hidden (view full) ---

299
300void
301xo_errx (int eval, const char *fmt, ...) NORETURN PRINTFLIKE(2, 3);
302
303void
304xo_errc (int eval, int code, const char *fmt, ...) NORETURN PRINTFLIKE(3, 4);
305
306void
330xo_set_leading_xpath (xo_handle_t *xop, const char *path);
331
332void
333xo_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
334
335void
336xo_warn_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
337

--- 8 unchanged lines hidden (view full) ---

346
347void
348xo_errx (int eval, const char *fmt, ...) NORETURN PRINTFLIKE(2, 3);
349
350void
351xo_errc (int eval, int code, const char *fmt, ...) NORETURN PRINTFLIKE(3, 4);
352
353void
307xo_message_hcv (xo_handle_t *xop, int code, const char *fmt, va_list vap);
354xo_message_hcv (xo_handle_t *xop, int code, const char *fmt, va_list vap) PRINTFLIKE(3, 0);
308
309void
310xo_message_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
311
312void
313xo_message_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
314
315void
355
356void
357xo_message_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
358
359void
360xo_message_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
361
362void
363xo_message_e (const char *fmt, ...) PRINTFLIKE(1, 2);
364
365void
316xo_message (const char *fmt, ...) PRINTFLIKE(1, 2);
317
318void
366xo_message (const char *fmt, ...) PRINTFLIKE(1, 2);
367
368void
369xo_emit_warn_hcv (xo_handle_t *xop, int as_warning, int code,
370 const char *fmt, va_list vap);
371
372void
373xo_emit_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...);
374
375void
376xo_emit_warn_c (int code, const char *fmt, ...);
377
378void
379xo_emit_warn (const char *fmt, ...);
380
381void
382xo_emit_warnx (const char *fmt, ...);
383
384void
385xo_emit_err (int eval, const char *fmt, ...) NORETURN;
386
387void
388xo_emit_errx (int eval, const char *fmt, ...) NORETURN;
389
390void
391xo_emit_errc (int eval, int code, const char *fmt, ...) NORETURN;
392
393PRINTFLIKE(4, 0)
394static inline void
395xo_emit_warn_hcvp (xo_handle_t *xop, int as_warning, int code,
396 const char *fmt, va_list vap)
397{
398 xo_emit_warn_hcv(xop, as_warning, code, fmt, vap);
399}
400
401PRINTFLIKE(3, 4)
402static inline void
403xo_emit_warn_hcp (xo_handle_t *xop, int code, const char *fmt, ...)
404{
405 va_list vap;
406 va_start(vap, fmt);
407 xo_emit_warn_hcv(xop, 1, code, fmt, vap);
408 va_end(vap);
409}
410
411PRINTFLIKE(2, 3)
412static inline void
413xo_emit_warn_cp (int code, const char *fmt, ...)
414{
415 va_list vap;
416 va_start(vap, fmt);
417 xo_emit_warn_hcv(NULL, 1, code, fmt, vap);
418 va_end(vap);
419}
420
421PRINTFLIKE(1, 2)
422static inline void
423xo_emit_warn_p (const char *fmt, ...)
424{
425 int code = errno;
426 va_list vap;
427 va_start(vap, fmt);
428 xo_emit_warn_hcv(NULL, 1, code, fmt, vap);
429 va_end(vap);
430}
431
432PRINTFLIKE(1, 2)
433static inline void
434xo_emit_warnx_p (const char *fmt, ...)
435{
436 va_list vap;
437 va_start(vap, fmt);
438 xo_emit_warn_hcv(NULL, 1, -1, fmt, vap);
439 va_end(vap);
440}
441
442NORETURN PRINTFLIKE(2, 3)
443static inline void
444xo_emit_err_p (int eval, const char *fmt, ...)
445{
446 int code = errno;
447 va_list vap;
448 va_start(vap, fmt);
449 xo_emit_warn_hcv(NULL, 0, code, fmt, vap);
450 va_end(vap);
451
452 exit(eval);
453}
454
455PRINTFLIKE(2, 3)
456static inline void
457xo_emit_errx_p (int eval, const char *fmt, ...)
458{
459 va_list vap;
460 va_start(vap, fmt);
461 xo_emit_warn_hcv(NULL, 0, -1, fmt, vap);
462 va_end(vap);
463 exit(eval);
464}
465
466PRINTFLIKE(3, 4)
467static inline void
468xo_emit_errc_p (int eval, int code, const char *fmt, ...)
469{
470 va_list vap;
471 va_start(vap, fmt);
472 xo_emit_warn_hcv(NULL, 0, code, fmt, vap);
473 va_end(vap);
474 exit(eval);
475}
476
477void
478xo_emit_err_v (int eval, int code, const char *fmt, va_list vap) NORETURN PRINTFLIKE(3, 0);
479
480void
319xo_no_setlocale (void);
320
321/**
322 * @brief Lift libxo-specific arguments from a set of arguments
323 *
324 * libxo-enable programs typically use command line options to enable
325 * all the nifty-cool libxo features. xo_parse_args() makes this simple
326 * by pre-processing the command line arguments given to main(), handling

--- 63 unchanged lines hidden (view full) ---

390/**
391 * #xo_set_version with a handle.
392 * @param[in] xop A valid libxo handle, or NULL for the default handle
393 * @param[in] version The version number, encoded as a string
394 */
395void
396xo_set_version_h (xo_handle_t *xop, const char *version);
397
481xo_no_setlocale (void);
482
483/**
484 * @brief Lift libxo-specific arguments from a set of arguments
485 *
486 * libxo-enable programs typically use command line options to enable
487 * all the nifty-cool libxo features. xo_parse_args() makes this simple
488 * by pre-processing the command line arguments given to main(), handling

--- 63 unchanged lines hidden (view full) ---

552/**
553 * #xo_set_version with a handle.
554 * @param[in] xop A valid libxo handle, or NULL for the default handle
555 * @param[in] version The version number, encoded as a string
556 */
557void
558xo_set_version_h (xo_handle_t *xop, const char *version);
559
560void
561xo_open_log (const char *ident, int logopt, int facility);
562
563void
564xo_close_log (void);
565
566int
567xo_set_logmask (int maskpri);
568
569void
570xo_set_unit_test_mode (int value);
571
572void
573xo_syslog (int priority, const char *name, const char *message, ...);
574
575void
576xo_vsyslog (int priority, const char *name, const char *message, va_list args);
577
578typedef void (*xo_syslog_open_t)(void);
579typedef void (*xo_syslog_send_t)(const char *full_msg,
580 const char *v0_hdr, const char *text_only);
581typedef void (*xo_syslog_close_t)(void);
582
583void
584xo_set_syslog_handler (xo_syslog_open_t open_func, xo_syslog_send_t send_func,
585 xo_syslog_close_t close_func);
586
587void
588xo_set_syslog_enterprise_id (unsigned short eid);
589
590typedef void (*xo_simplify_field_func_t)(const char *, unsigned, int);
591
592char *
593xo_simplify_format (xo_handle_t *xop, const char *fmt, int with_numbers,
594 xo_simplify_field_func_t field_cb);
595
398#endif /* INCLUDE_XO_H */
596#endif /* INCLUDE_XO_H */