2 * UCW Library -- Extended Types
4 * (c) 2014 Martin Mares <mj@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
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.
21 typedef const char * (*xtype_parser)(const char *str, void *dest, struct mempool *pool);
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.
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.
31 typedef const char * (*xtype_formatter)(void *src, u32 fmt, struct mempool *pool);
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
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,
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.
53 typedef const char * (*xtype_fmt_parser)(const char *str, u32 *dest, struct mempool *pool);
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.
60 typedef const char * (*xtype_fmt_formatter)(u32 fmt, struct mempool *pool);
63 * Definition of the units that are appended to an xtype value. The value with units is represented
64 * by the following string: "<value><units>". The final value of the of the string is computed using
65 * the following formula: <value> * <num>/<denom>.
67 struct unit_definition {
68 const char *unit; // string representation of unit
74 * Parses a unit definition in units_str and returns index into units_def array. -1 if the units
75 * were not contained in the array.
77 int xtype_unit_parser(const char *units_str, struct unit_definition *units_def);
80 * This structure describes an xtype. Among other things, it points to callback
81 * functions handling this xtype.
84 size_t size; // How many bytes does a single value occupy
85 const char *name; // Name used in debug messages
86 xtype_parser parse; // Parsing callback
87 xtype_formatter format; // Formatting callback
88 xtype_fmt_parser parse_fmt; // Format mode parsing callback (optional)
89 xtype_fmt_formatter format_fmt; // Format mode formatting callback (optional)
93 * Construct a formatting mode from its string representation. It is a wrapper
94 * around the `xtype_fmt_parser` hook, which handles generic modes first.
96 * The generic modes are called `default`, `raw`, and `pretty`.
98 const char *xtype_parse_fmt(struct xtype *xt, const char *str, u32 *dest, struct mempool *pool);
101 * Construct a string representation of a formatting mode. It is a wrapper
102 * around the `xtype_fmt_formatter` hook, which handles generic modes first.
103 * Returns an empty string for unknown modes.
105 const char *xtype_format_fmt(struct xtype *xt, u32 fmt, struct mempool *pool);
107 // Basic set of extended types
108 extern const struct xtype xt_str;
109 extern const struct xtype xt_int;
110 extern const struct xtype xt_s64;
111 extern const struct xtype xt_intmax;
112 extern const struct xtype xt_uint;
113 extern const struct xtype xt_u64;
114 extern const struct xtype xt_uintmax;
115 extern const struct xtype xt_bool;
116 extern const struct xtype xt_double;
119 #define XTYPE_FMT_DBL_PREC XTYPE_FMT_CUSTOM
120 #define XTYPE_FMT_DBL_FIXED_PREC(_prec) (_prec | XTYPE_FMT_CUSTOM)