ucw/xtypes.h

   1 /*
   2  *      UCW Library -- Extended Types
   3  *
   4  *      (c) 2014 Martin Mares <mj@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_XTYPE_H
  11 #define _UCW_XTYPE_H
  12
  13 struct mempool;
  14
  15 /**
  16  * A parsing callback. Takes a string, interprets it as a value of the particular
  17  * xtype and stores it where @dest points. Returns NULL on success and an error message
  18  * otherwise. It may allocate memory from the @pool and the parsed value can contain
  19  * pointers to this memory.
  20  **/
  21 typedef const char * (*xtype_parser)(const char *str, void *dest, struct mempool *pool);
  22
  23 /**
  24  * A formatting callback. Takes a value of the particular xtype and a formatting
  25  * mode @fmt (see below for how the modes work) and returns a string representation
  26  * of the value. The string can be allocated from the @pool, but it does not have to.
  27  *
  28  * When @fmt is set to `XTYPE_FMT_DEFAULT`, the resulting string should be
  29  * parseable via the parsing callback and yield a semantically equivalent value.
  30  **/
  31 typedef const char * (*xtype_formatter)(void *src, u32 fmt, struct mempool *pool);
  32
  33 /**
  34  * Formatting of values is controlled by a mode parameter, which is generally
  35  * a 32-bit integer. If the most significant bit is clear, it is one of generic
  36  * well-known modes (`XTYPE_FMT_`'something'), which can be passed to all formatters
  37  * and if it is not understood, it acts like `XTYPE_FMT_DEFAULT`. When the most
  38  * significant bit is set, the meaning of the mode is specific to the particular
  39  * xtype.
  40  **/
  41
  42 enum xtype_fmt {
  43   XTYPE_FMT_DEFAULT = 0,        // Default format: readable, but not hostile to machine parsing
  44   XTYPE_FMT_RAW = 1,            // Raw data with no frills
  45   XTYPE_FMT_PRETTY = 2,         // Try to please humans (e.g., like "ls -h")
  46   XTYPE_FMT_CUSTOM = 0x80000000,
  47 };
  48
  49 /**
  50  * A callback for parsing non-generic formatting modes. See `xtype_parser` for more
  51  * details. It is usually called via `xtype_parse_fmt`, which handles the generic modes.
  52  **/
  53 typedef const char * (*xtype_fmt_parser)(const char *str, u32 *dest, struct mempool *pool);
  54
  55 /**
  56  * A callback for constructing a string representation of non-generic formatting modes,
  57  * analogous to `xtype_formatter`. It is usually called via `xtype_format_fmt`,
  58  * which handles the generic modes. Returns an empty string for unknown modes.
  59  **/
  60 typedef const char * (*xtype_fmt_formatter)(u32 fmt, struct mempool *pool);
  61
  62 /**
  63  * This structure describes an xtype. Among other things, it points to callback
  64  * functions handling this xtype.
  65  **/
  66 struct xtype {
  67   size_t size;                          // How many bytes does a single value occupy
  68   const char *name;                     // Name used in debug messages
  69   xtype_parser parse;                   // Parsing callback
  70   xtype_formatter format;               // Formatting callback
  71   xtype_fmt_parser parse_fmt;           // Format mode parsing callback (optional)
  72   xtype_fmt_formatter format_fmt;       // Format mode formatting callback (optional)
  73 };
  74
  75 /**
  76  * Construct a formatting mode from its string representation. It is a wrapper
  77  * around the `xtype_fmt_parser` hook, which handles generic modes first.
  78  *
  79  * The generic modes are called `default`, `raw`, and `pretty`.
  80  **/
  81 const char *xtype_parse_fmt(struct xtype *xt, const char *str, u32 *dest, struct mempool *pool);
  82
  83 /**
  84  * Construct a string representation of a formatting mode. It is a wrapper
  85  * around the `xtype_fmt_formatter` hook, which handles generic modes first.
  86  * Returns an empty string for unknown modes.
  87  **/
  88 const char *xtype_format_fmt(struct xtype *xt, u32 fmt, struct mempool *pool);
  89
  90 // Basic set of extended types
  91 extern const struct xtype xt_str;
  92 extern const struct xtype xt_int;
  93 extern const struct xtype xt_s64;
  94 extern const struct xtype xt_intmax;
  95 extern const struct xtype xt_uint;
  96 extern const struct xtype xt_u64;
  97 extern const struct xtype xt_uintmax;
  98 extern const struct xtype xt_bool;
  99 extern const struct xtype xt_double;
 100
 101 #endif