From: Martin Mares Date: Fri, 16 Jan 2015 14:09:55 +0000 (+0100) Subject: Xtypes: Documentation X-Git-Tag: v6.2~4 X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=51eb484a86657f9e74805c2c334661b63d3a99e7;p=libucw.git Xtypes: Documentation --- diff --git a/TODO b/TODO index d47f715e..1119eb52 100644 --- a/TODO +++ b/TODO @@ -6,4 +6,3 @@ Tableprinter: - computing statistics of columns via the table_start_callback/table_end_callback. - unsupported: (dynamic) alignment of cells which is computed in table_end -* document xtypes diff --git a/ucw/default.cfg b/ucw/default.cfg index 0384b95d..65404cf1 100644 --- a/ucw/default.cfg +++ b/ucw/default.cfg @@ -1,12 +1,12 @@ # Configuration variables of the UCW library and their default values -# (c) 2005--2014 Martin Mares +# (c) 2005--2015 Martin Mares # Version of the whole package -Set("UCW_VERSION" => "6.1-dev"); -Set("UCW_VERSION_CODE" => 6001000); +Set("UCW_VERSION" => "6.2"); +Set("UCW_VERSION_CODE" => 6002000); # Name of libraries in packages (libucw$UCW_ABI_SUFFIX.so.0.0, etc.) -Set("UCW_ABI_SUFFIX" => "-6.1"); +Set("UCW_ABI_SUFFIX" => "-6.2"); # Compile everything with debug information and ASSERT's UnSet("CONFIG_DEBUG"); diff --git a/ucw/doc/relnotes.txt b/ucw/doc/relnotes.txt index c0e69738..94d626d3 100644 --- a/ucw/doc/relnotes.txt +++ b/ucw/doc/relnotes.txt @@ -1,6 +1,26 @@ Release notes ============= +6.2 (2015-01-16) +---------------- +* Fixed race conditions in <>. +* The <> have been documented and integrated + in the table printer, command-line option parser, and configuration parser. + +6.1 (2014-08-09) +---------------- + +Incompatible changes +~~~~~~~~~~~~~~~~~~~~ +* Major changes of the table printer module. Finally, its interface can be + considered stable now. + +Minor changes +~~~~~~~~~~~~~ +* The <> gained `OPT_BREAK` class and + `OPT_HELP_COLUMNS` flag. +* The strtonum module supports more types. + 6.0 (2014-06-20) ---------------- diff --git a/ucw/doc/xtypes.txt b/ucw/doc/xtypes.txt index b75f8275..69077f8c 100644 --- a/ucw/doc/xtypes.txt +++ b/ucw/doc/xtypes.txt @@ -1,6 +1,22 @@ Extended types ============== -FIXME: Introduction +Extended types ('xtypes') are user-defined data types equipped with mechanisms +for parsing and printing. +Each xtype is described by a <>, which contains properties of the type +and several pointers to callback functions. + +Xtypes are currently supported by the following modules: + +* <> +* <> +* <> + +ucw/xtypes.h +------------ !!ucw/xtypes.h + +ucw/xtypes-extra.h +------------------ +!!ucw/xtypes-extra.h diff --git a/ucw/xtypes-extra.h b/ucw/xtypes-extra.h index 4e76b8dd..fc94a969 100644 --- a/ucw/xtypes-extra.h +++ b/ucw/xtypes-extra.h @@ -17,10 +17,17 @@ #define xt_timestamp ucw_xt_timestamp #endif -/* Size, possibly with a unit. Internally represented as u64. */ +/*** + * Size + * ~~~~ + * + * `xt_size` is a size, possibly with a unit. Internally, it is represented + * as a `u64`. + ***/ extern const struct xtype xt_size; +/** Units **/ enum size_units { XT_SIZE_UNIT_BYTE, XT_SIZE_UNIT_KILOBYTE, @@ -30,6 +37,7 @@ enum size_units { XT_SIZE_UNIT_AUTO }; +/** Custom formatting mode: use a specified unit (`XT_SIZE_UNIT_`'xxx') **/ #define XT_SIZE_FMT_UNIT(_unit) (_unit | XT_SIZE_FMT_FIXED_UNIT) #define XT_SIZE_FMT_FIXED_UNIT XTYPE_FMT_CUSTOM @@ -38,7 +46,12 @@ enum size_units { TABLE_COL_PROTO(size, u64) -/* Timestamp. Internally represented as time_t. */ +/*** + * Time + * ~~~~ + * + * `xt_timestamp` is a timestamp, internally represented as `time_t`. + ***/ #define XT_TIMESTAMP_FMT_EPOCH XTYPE_FMT_RAW #define XT_TIMESTAMP_FMT_DATETIME XTYPE_FMT_PRETTY diff --git a/ucw/xtypes.h b/ucw/xtypes.h index 20edf1a9..da7d2537 100644 --- a/ucw/xtypes.h +++ b/ucw/xtypes.h @@ -1,7 +1,7 @@ /* * UCW Library -- Extended Types * - * (c) 2014 Martin Mares + * (c) 2014--2015 Martin Mares * * This software may be freely distributed and used according to the terms * of the GNU Lesser General Public License. @@ -27,6 +27,11 @@ struct mempool; +/*** + * Definitions of types + * ~~~~~~~~~~~~~~~~~~~~ + ***/ + /** * A parsing callback. Takes a string, interprets it as a value of the particular * xtype and stores it where @dest points. Returns NULL on success and an error message @@ -53,7 +58,6 @@ typedef const char * (*xtype_formatter)(void *src, u32 fmt, struct mempool *pool * significant bit is set, the meaning of the mode is specific to the particular * xtype. **/ - enum xtype_fmt { XTYPE_FMT_DEFAULT = 0, // Default format: readable, but not hostile to machine parsing XTYPE_FMT_RAW = 1, // Raw data with no frills @@ -102,37 +106,61 @@ const char *xtype_parse_fmt(const struct xtype *xt, const char *str, u32 *dest, **/ const char *xtype_format_fmt(struct xtype *xt, u32 fmt, struct mempool *pool); -// Basic set of extended types -extern const struct xtype xt_str; +/*** + * Basic pre-defined types + * ~~~~~~~~~~~~~~~~~~~~~~~ + * + * We provide xtypes for many basic data types: + * + * * `xt_bool` + * * `xt_double` -- in addition to the generic formatting modes, you can use + * `XT_DOUBLE_FMT_PREC(`'n'`)` to generate a mode for fixed formatting with + * 'n' decimal places. + * * `xt_int` + * * `xt_intmax` + * * `xt_s64` + * * `xt_str` -- string, represented by a `const char *` + * * `xt_u64` + * * `xt_uint` + * * `xt_uintmax` + ***/ + +extern const struct xtype xt_bool; +extern const struct xtype xt_double; extern const struct xtype xt_int; -extern const struct xtype xt_s64; extern const struct xtype xt_intmax; -extern const struct xtype xt_uint; +extern const struct xtype xt_s64; +extern const struct xtype xt_str; extern const struct xtype xt_u64; +extern const struct xtype xt_uint; extern const struct xtype xt_uintmax; -extern const struct xtype xt_bool; -extern const struct xtype xt_double; // Fixed-precision formats for xt_double #define XT_DOUBLE_FMT_PREC(_prec) (_prec | XT_DOUBLE_FMT_PREC_FLAG) #define XT_DOUBLE_FMT_PREC_FLAG XTYPE_FMT_CUSTOM -/* Tables of units, provided as convenience for the implementations of xtypes */ +/*** + * Tables of units + * ~~~~~~~~~~~~~~~ + * + * Various xtypes accept values accompanied by a unit of measure. + * Units by handled by the xtypes themselves, but we provide a couple + * of generic functions for their convenience. + ***/ /** - * Definition of the units that are appended to an xtype value. The value with units is represented - * by the following string: "". The final value of the of the string is computed using - * the following formula: * /. + * Each unit is defined by a conversion ratio, which is a fraction with 64-bit numerator + * and denominator. Therefore, a value of 'x' units is interpreted as 'x' * 'num' / 'denon'. **/ struct unit_definition { - const char *unit; // string representation of unit - u64 num; - u64 denom; + const char *unit; // Symbol (name of the unit, as appended to values) + u64 num; // Numerator + u64 denom; // Denominator }; /** - * Parse a name of a unit and return its index in the @units array or -1 - * if is not present there. + * Given an array @units of unit definitions (terminated by an all-zero entry), + * parse a name of a unit and return its index in the array, or -1 if it is not found. **/ int xtype_unit_parser(const char *str, const struct unit_definition *units);