Xtypes: Documentation

diff --git a/TODO b/TODO
index d47f715e9754360bffd88ec547465f40a4d4b823..1119eb527c079e42117f6db7afdf37d5d777cb81 100644 (file)
--- 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 0384b95d2d9d30c9c1dac8b2137577e5dddd1dc7..65404cf12c1074aa47dd2ce8541b0cf0b868135b 100644 (file)
--- 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 <mj@ucw.cz>
+# (c) 2005--2015 Martin Mares <mj@ucw.cz>
 
 # 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 c0e69738bc1a6a8fc21e1513b3e3158904e46100..94d626d319cbec28d0b4de13b9392fd508fee047 100644 (file)
--- 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 <<daemon:,daemon helpers>>.
+* The <<xtypes:,extended types>> 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 <<opt:,command-line option parser>> 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 b75f827571ca39df9e9e9fd1218d26c3ff766bc7..69077f8c8656713815f0bff43483193fa25ac79e 100644 (file)
--- 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 <<struct_xtype,`struct xtype`>>, which contains properties of the type
+and several pointers to callback functions.
+
+Xtypes are currently supported by the following modules:
+
+* <<table:,Table printer>>
+* <<opt:,Command-line option parser>>
+* <<conf:,Configuration parser>>
+
+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 4e76b8dd52feecb4fb686df8137aaf7f722a045c..fc94a96925f9ec021369aa10f4e601eea095aa75 100644 (file)
--- 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 20edf1a965a78e1a6c82b2f33c6704bc199184b3..da7d253764c3505b38ec26fcfc7ea914c679372a 100644 (file)
--- a/ucw/xtypes.h
+++ b/ucw/xtypes.h
@@ -1,7 +1,7 @@
 /*
  *     UCW Library -- Extended Types
  *
- *     (c) 2014 Martin Mares <mj@ucw.cz>
+ *     (c) 2014--2015 Martin Mares <mj@ucw.cz>
  *
  *     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: "<value><units>". The final value of the of the string is computed using
- * the following formula: <value> * <num>/<denom>.
+ * 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);