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 #define XO_OP_OPTIONS_PLUS      18 /* Additional command line options */
  94
  95 #define XO_ENCODER_HANDLER_ARGS                                 \
  96         xo_handle_t *xop __attribute__ ((__unused__)),          \
  97         xo_encoder_op_t op __attribute__ ((__unused__)),        \
  98         const char *name __attribute__ ((__unused__)),          \
  99         const char *value __attribute__ ((__unused__)),         \
 100         void *private __attribute__ ((__unused__)),             \
 101         xo_xff_flags_t flags __attribute__ ((__unused__))
 102
 103 typedef int (*xo_encoder_func_t)(XO_ENCODER_HANDLER_ARGS);
 104
 105 typedef struct xo_encoder_init_args_s {
 106     unsigned xei_version;          /* Current version */
 107     xo_encoder_func_t xei_handler; /* Encoding handler */
 108 } xo_encoder_init_args_t;
 109
 110 #define XO_ENCODER_VERSION      1 /* Current version */
 111
 112 #define XO_ENCODER_INIT_ARGS \
 113     xo_encoder_init_args_t *arg __attribute__ ((__unused__))
 114
 115 typedef int (*xo_encoder_init_func_t)(XO_ENCODER_INIT_ARGS);
 116 /*
 117  * Each encoder library must define a function named xo_encoder_init
 118  * that takes the arguments defined in XO_ENCODER_INIT_ARGS.  It
 119  * should return zero for success.
 120  */
 121 #define XO_ENCODER_INIT_NAME_TOKEN xo_encoder_library_init
 122 #define XO_STRINGIFY(_x) #_x
 123 #define XO_STRINGIFY2(_x) XO_STRINGIFY(_x)
 124 #define XO_ENCODER_INIT_NAME XO_STRINGIFY2(XO_ENCODER_INIT_NAME_TOKEN)
 125 extern int XO_ENCODER_INIT_NAME_TOKEN (XO_ENCODER_INIT_ARGS);
 126
 127 void
 128 xo_encoder_register (const char *name, xo_encoder_func_t func);
 129
 130 void
 131 xo_encoder_unregister (const char *name);
 132
 133 void *
 134 xo_get_private (xo_handle_t *xop);
 135
 136 void
 137 xo_encoder_path_add (const char *path);
 138
 139 void
 140 xo_set_private (xo_handle_t *xop, void *opaque);
 141
 142 xo_encoder_func_t
 143 xo_get_encoder (xo_handle_t *xop);
 144
 145 void
 146 xo_set_encoder (xo_handle_t *xop, xo_encoder_func_t encoder);
 147
 148 int
 149 xo_encoder_init (xo_handle_t *xop, const char *name);
 150
 151 xo_handle_t *
 152 xo_encoder_create (const char *name, xo_xof_flags_t flags);
 153
 154 int
 155 xo_encoder_handle (xo_handle_t *xop, xo_encoder_op_t op,
 156                    const char *name, const char *value, xo_xff_flags_t flags);
 157
 158 void
 159 xo_encoders_clean (void);
 160
 161 const char *
 162 xo_encoder_op_name (xo_encoder_op_t op);
 163
 164 /*
 165  * xo_failure is used to announce internal failures, when "warn" is on
 166  */
 167 void
 168 xo_failure (xo_handle_t *xop, const char *fmt, ...);
 169
 170 #endif /* XO_ENCODER_H */