contrib/libxo/libxo/xo_encoder.h

   1 /*
   2  * Copyright (c) 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, August 2015
   9  */
  10
  11 /*
  12  * NOTE WELL: This file is needed to software that implements an
  13  * external encoder for libxo that allows libxo data to be encoded in
  14  * new and bizarre formats.  General libxo code should _never_
  15  * include this header file.
  16  */
  17
  18 #ifndef XO_ENCODER_H
  19 #define XO_ENCODER_H
  20
  21 #include <string.h>
  22
  23 /*
  24  * Expose libxo's memory allocation functions
  25  */
  26 extern xo_realloc_func_t xo_realloc;
  27 extern xo_free_func_t xo_free;
  28
  29 /*
  30  * Simple string comparison function (without the temptation
  31  * to forget the "== 0").
  32  */
  33 static inline int
  34 xo_streq (const char *one, const char *two)
  35 {
  36     return strcmp(one, two) == 0;
  37 }
  38
  39 /* Flags for formatting functions */
  40 typedef unsigned long xo_xff_flags_t;
  41 #define XFF_COLON       (1<<0)  /* Append a ":" */
  42 #define XFF_COMMA       (1<<1)  /* Append a "," iff there's more output */
  43 #define XFF_WS          (1<<2)  /* Append a blank */
  44 #define XFF_ENCODE_ONLY (1<<3)  /* Only emit for encoding styles (XML, JSON) */
  45
  46 #define XFF_QUOTE       (1<<4)  /* Force quotes */
  47 #define XFF_NOQUOTE     (1<<5)  /* Force no quotes */
  48 #define XFF_DISPLAY_ONLY (1<<6) /* Only emit for display styles (text, html) */
  49 #define XFF_KEY         (1<<7)  /* Field is a key (for XPath) */
  50
  51 #define XFF_XML         (1<<8)  /* Force XML encoding style (for XPath) */
  52 #define XFF_ATTR        (1<<9)  /* Escape value using attribute rules (XML) */
  53 #define XFF_BLANK_LINE  (1<<10) /* Emit a blank line */
  54 #define XFF_NO_OUTPUT   (1<<11) /* Do not make any output */
  55
  56 #define XFF_TRIM_WS     (1<<12) /* Trim whitespace off encoded values */
  57 #define XFF_LEAF_LIST   (1<<13) /* A leaf-list (list of values) */
  58 #define XFF_UNESCAPE    (1<<14) /* Need to printf-style unescape the value */
  59 #define XFF_HUMANIZE    (1<<15) /* Humanize the value (for display styles) */
  60
  61 #define XFF_HN_SPACE    (1<<16) /* Humanize: put space before suffix */
  62 #define XFF_HN_DECIMAL  (1<<17) /* Humanize: add one decimal place if <10 */
  63 #define XFF_HN_1000     (1<<18) /* Humanize: use 1000, not 1024 */
  64 #define XFF_GT_FIELD    (1<<19) /* Call gettext() on a field */
  65
  66 #define XFF_GT_PLURAL   (1<<20) /* Call dngettext to find plural form */
  67 #define XFF_ARGUMENT    (1<<21) /* Content provided via argument */
  68
  69 /* Flags to turn off when we don't want i18n processing */
  70 #define XFF_GT_FLAGS (XFF_GT_FIELD | XFF_GT_PLURAL)
  71
  72 typedef unsigned xo_encoder_op_t;
  73
  74 /* Encoder operations; names are in xo_encoder.c:xo_encoder_op_name() */
  75 #define XO_OP_UNKNOWN           0
  76 #define XO_OP_CREATE            1 /* Called when the handle is init'd */
  77 #define XO_OP_OPEN_CONTAINER    2
  78 #define XO_OP_CLOSE_CONTAINER   3
  79 #define XO_OP_OPEN_LIST         4
  80 #define XO_OP_CLOSE_LIST        5
  81 #define XO_OP_OPEN_LEAF_LIST    6
  82 #define XO_OP_CLOSE_LEAF_LIST   7
  83 #define XO_OP_OPEN_INSTANCE     8
  84 #define XO_OP_CLOSE_INSTANCE    9
  85 #define XO_OP_STRING            10 /* Quoted UTF-8 string */
  86 #define XO_OP_CONTENT           11 /* Other content */
  87 #define XO_OP_FINISH            12 /* Finish any pending output */
  88 #define XO_OP_FLUSH             13 /* Flush any buffered output */
  89 #define XO_OP_DESTROY           14 /* Clean up function */
  90 #define XO_OP_ATTRIBUTE         15 /* Attribute name/value */
  91 #define XO_OP_VERSION           16 /* Version string */
  92 #define XO_OP_OPTIONS           17 /* Additional command line options */
  93
  94 #define XO_ENCODER_HANDLER_ARGS                                 \
  95         xo_handle_t *xop __attribute__ ((__unused__)),          \
  96         xo_encoder_op_t op __attribute__ ((__unused__)),        \
  97         const char *name __attribute__ ((__unused__)),          \
  98         const char *value __attribute__ ((__unused__)),         \
  99         void *private __attribute__ ((__unused__)),             \
 100         xo_xff_flags_t flags __attribute__ ((__unused__))
 101
 102 typedef int (*xo_encoder_func_t)(XO_ENCODER_HANDLER_ARGS);
 103
 104 typedef struct xo_encoder_init_args_s {
 105     unsigned xei_version;          /* Current version */
 106     xo_encoder_func_t xei_handler; /* Encoding handler */
 107 } xo_encoder_init_args_t;
 108
 109 #define XO_ENCODER_VERSION      1 /* Current version */
 110
 111 #define XO_ENCODER_INIT_ARGS \
 112     xo_encoder_init_args_t *arg __attribute__ ((__unused__))
 113
 114 typedef int (*xo_encoder_init_func_t)(XO_ENCODER_INIT_ARGS);
 115 /*
 116  * Each encoder library must define a function named xo_encoder_init
 117  * that takes the arguments defined in XO_ENCODER_INIT_ARGS.  It
 118  * should return zero for success.
 119  */
 120 #define XO_ENCODER_INIT_NAME_TOKEN xo_encoder_library_init
 121 #define XO_STRINGIFY(_x) #_x
 122 #define XO_STRINGIFY2(_x) XO_STRINGIFY(_x)
 123 #define XO_ENCODER_INIT_NAME XO_STRINGIFY2(XO_ENCODER_INIT_NAME_TOKEN)
 124 extern int XO_ENCODER_INIT_NAME_TOKEN (XO_ENCODER_INIT_ARGS);
 125
 126 void
 127 xo_encoder_register (const char *name, xo_encoder_func_t func);
 128
 129 void
 130 xo_encoder_unregister (const char *name);
 131
 132 void *
 133 xo_get_private (xo_handle_t *xop);
 134
 135 void
 136 xo_encoder_path_add (const char *path);
 137
 138 void
 139 xo_set_private (xo_handle_t *xop, void *opaque);
 140
 141 xo_encoder_func_t
 142 xo_get_encoder (xo_handle_t *xop);
 143
 144 void
 145 xo_set_encoder (xo_handle_t *xop, xo_encoder_func_t encoder);
 146
 147 int
 148 xo_encoder_init (xo_handle_t *xop, const char *name);
 149
 150 xo_handle_t *
 151 xo_encoder_create (const char *name, xo_xof_flags_t flags);
 152
 153 int
 154 xo_encoder_handle (xo_handle_t *xop, xo_encoder_op_t op,
 155                    const char *name, const char *value, xo_xff_flags_t flags);
 156
 157 void
 158 xo_encoders_clean (void);
 159
 160 const char *
 161 xo_encoder_op_name (xo_encoder_op_t op);
 162
 163 /*
 164  * xo_failure is used to announce internal failures, when "warn" is on
 165  */
 166 void
 167 xo_failure (xo_handle_t *xop, const char *fmt, ...);
 168
 169 #endif /* XO_ENCODER_H */