Tableprinter: Fixed a tiny typo

[libucw.git] / ucw / table.h

diff --git a/ucw/table.h b/ucw/table.h
index 1e79c587c28792f644b9e45d5799d9f20128e63c..0d20c1b9e789773132f595013e593274d05f2ea4 100644 (file)
--- a/ucw/table.h
+++ b/ucw/table.h
@@ -9,7 +9,9 @@
 
 #include <ucw/fastbuf.h>
 #include <ucw/mempool.h>
 
 #include <ucw/fastbuf.h>
 #include <ucw/mempool.h>

+#include <ucw/xtypes.h>

 
 

+// FIXME: update these macros

 #ifdef CONFIG_UCW_CLEAN_ABI
 #define table_append_bool ucw_table_append_bool
 #define table_append_double ucw_table_append_double
 #ifdef CONFIG_UCW_CLEAN_ABI
 #define table_append_bool ucw_table_append_bool
 #define table_append_double ucw_table_append_double


@@ -73,23 +75,11 @@
  * -----------------
  ***/
 
  * -----------------
  ***/
 

+// FIXME: update documentation according to the changes made in recent commits!
+

 /** Types of columns. These are seldom used explicitly, using a column definition macro is preferred. **/
 /** Types of columns. These are seldom used explicitly, using a column definition macro is preferred. **/

-enum column_type {
-  COL_TYPE_STR,                // String
-  COL_TYPE_INT,                // int
-  COL_TYPE_S64,                // Signed 64-bit integer
-  COL_TYPE_INTMAX,     // intmax_t
-  COL_TYPE_UINT,       // unsigned int
-  COL_TYPE_U64,                // Unsigned 64-bit integer
-  COL_TYPE_UINTMAX,    // uintmax_t
-  COL_TYPE_BOOL,       // bool
-  COL_TYPE_DOUBLE,     // double
-  COL_TYPE_ANY,                // Any type
-  COL_TYPE_LAST
-};

 
 

-#define COL_TYPE_UCW           0x100
-#define COL_TYPE_CUSTOM        0x1000
+#define COL_TYPE_ANY      NULL

 
 /** Justify cell contents to the left. **/
 #define CELL_ALIGN_LEFT     (1U << 31)
 
 /** Justify cell contents to the left. **/
 #define CELL_ALIGN_LEFT     (1U << 31)


@@ -99,9 +89,7 @@ enum column_type {
 #define CELL_FLAG_MASK (CELL_ALIGN_LEFT)
 #define CELL_WIDTH_MASK        (~CELL_FLAG_MASK)
 
 #define CELL_FLAG_MASK (CELL_ALIGN_LEFT)
 #define CELL_WIDTH_MASK        (~CELL_FLAG_MASK)
 

-#define CELL_OUT_UNINITIALIZED      -1
-#define CELL_OUT_HUMAN_READABLE     0
-#define CELL_OUT_MACHINE_READABLE   1
+struct table;

 
 /**
  * Definition of a single table column.
 
 /**
  * Definition of a single table column.


@@ -110,33 +98,52 @@ enum column_type {
  **/
 struct table_column {
   const char *name;            // [*] Name of the column displayed in table header
  **/
 struct table_column {
   const char *name;            // [*] Name of the column displayed in table header

-  int width;                   // [*] Width of the column (in characters) OR'ed with column flags
-  const char *fmt;             // [*] Default format of each cell in the column
-  enum column_type type;       // [*] Type of the cells in the column
-  int first_column;
-  int last_column;
+  uint width;                  // [*] Width of the column (in characters) OR'ed with column flags
+  uint fmt;                     // [*] default format of the column
+  const struct xtype *type_def; // [*] pointer to xtype of this column
+
+  bool (*set_col_instance_option)(struct table *tbl, uint col, const char *value, char **err);
+       // [*] process table option for a column instance
+};
+
+// FIXME: is it correct to have idx and col_def? idx is sufficient and in fact a duplicity of idx
+// idx is used only for initialization and col_def is used in other cases
+struct table_col_instance {
+  uint idx;                            // idx is a index into struct table::columns
+  const struct table_column *col_def;  // this is pointer to the column definition, located in the array struct table::columns
+  const char *cell_content;            // content of the cell of the current row
+  int next_column;                     // index of next column in linked list of columns of the same type
+  uint output_type;                    // format of this column

 };
 
 };
 

-struct table_col_info {
-  uint idx;
-  char *cell_content;
-  int next_column;
-  int output_type;
+/**
+ * Definition of a table. Contains column definitions, and some per-table settings.
+ * Please use only fields marked with `[*]`.
+ **/
+struct table_template {
+  const struct table_column *columns;       // [*] Definition of columns
+  struct table_col_instance *column_order;  // [*] Order of the columns in the print-out of the table
+  uint cols_to_output;                      // [*] Number of columns that are printed
+  const char *col_delimiter;                // [*] Delimiter that is placed between columns
+  // Back-end used for table formatting and its private data
+  struct table_formatter *formatter; // FIXME: should be const?

 };
 
 /**
 };
 
 /**

- * Definition of a table. Contains column definitions, per-table settings
- * and internal data. Please use only fields marked with `[*]`.
+ * Handle of a table. Contains column definitions, per-table settings
+ * and internal data. To change the table definition, please use only
+ * fields marked with `[*]`.

  **/
 struct table {
  **/
 struct table {

-  struct table_column *columns;                // [*] Definition of columns
+  const struct table_column *columns;  // [*] Definition of columns

   int column_count;                    // [*] Number of columns (calculated by table_init())
   int column_count;                    // [*] Number of columns (calculated by table_init())

+  int *ll_headers;                      // headers of linked lists that connects column instances

   struct mempool *pool;                        // Memory pool used for storing table data. Contains global state
                                        // and data of the current row.
   struct mempool_state pool_state;     // State of the pool after the table is initialized, i.e., before
                                        // per-row data have been allocated.
 
   struct mempool *pool;                        // Memory pool used for storing table data. Contains global state
                                        // and data of the current row.
   struct mempool_state pool_state;     // State of the pool after the table is initialized, i.e., before
                                        // per-row data have been allocated.
 

-  struct table_col_info *column_order;  // [*] Order of the columns in the print-out of the table
+  struct table_col_instance *column_order;  // [*] Order of the columns in the print-out of the table

   uint cols_to_output;                 // [*] Number of columns that are printed
   const char *col_delimiter;           // [*] Delimiter that is placed between columns
   uint print_header;                   // [*] 0 indicates that table header should not be printed
   uint cols_to_output;                 // [*] Number of columns that are printed
   const char *col_delimiter;           // [*] Delimiter that is placed between columns
   uint print_header;                   // [*] 0 indicates that table header should not be printed


@@ -169,47 +176,65 @@ struct table {
  *
  ***/
 
  *
  ***/
 

-#define TBL_COL_LIST_INIT     .first_column = -1, .last_column = -1
-#define TBL_COL_STR(_name, _width)            { .name = _name, .width = _width, .fmt = "%s", .type = COL_TYPE_STR, TBL_COL_LIST_INIT }
-#define TBL_COL_INT(_name, _width)            { .name = _name, .width = _width, .fmt = "%d", .type = COL_TYPE_INT, TBL_COL_LIST_INIT }
-#define TBL_COL_S64(_name, _width)            { .name = _name, .width = _width, .fmt = "%lld", .type = COL_TYPE_S64, TBL_COL_LIST_INIT }
-#define TBL_COL_UINT(_name, _width)           { .name = _name, .width = _width, .fmt = "%u", .type = COL_TYPE_UINT, TBL_COL_LIST_INIT }
-#define TBL_COL_U64(_name, _width)            { .name = _name, .width = _width, .fmt = "%llu", .type = COL_TYPE_U64, TBL_COL_LIST_INIT }
-#define TBL_COL_INTMAX(_name, _width)         { .name = _name, .width = _width, .fmt = "%jd", .type = COL_TYPE_INTMAX, TBL_COL_LIST_INIT }
-#define TBL_COL_UINTMAX(_name, _width)        { .name = _name, .width = _width, .fmt = "%ju", .type = COL_TYPE_UINTMAX, TBL_COL_LIST_INIT }
-#define TBL_COL_HEXUINT(_name, _width)        { .name = _name, .width = _width, .fmt = "0x%x", .type = COL_TYPE_UINT, TBL_COL_LIST_INIT }
-#define TBL_COL_DOUBLE(_name, _width, _prec)  { .name = _name, .width = _width, .fmt = "%." #_prec "lf", .type = COL_TYPE_DOUBLE, TBL_COL_LIST_INIT }
-#define TBL_COL_BOOL(_name, _width)           { .name = _name, .width = _width, .fmt = "%s", .type = COL_TYPE_BOOL, TBL_COL_LIST_INIT }
-#define TBL_COL_ANY(_name, _width)            { .name = _name, .width = _width, .fmt = 0, .type = COL_TYPE_ANY, TBL_COL_LIST_INIT }
-
-#define TBL_COL_STR_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_STR, TBL_COL_LIST_INIT }
-#define TBL_COL_INT_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_INT, TBL_COL_LIST_INIT }
-#define TBL_COL_S64_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_S64, TBL_COL_LIST_INIT }
-#define TBL_COL_UINT_FMT(_name, _width, _fmt)           { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_UINT, TBL_COL_LIST_INIT }
-#define TBL_COL_U64_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_U64, TBL_COL_LIST_INIT }
-#define TBL_COL_INTMAX_FMT(_name, _width, _fmt)         { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_INTMAX, TBL_COL_LIST_INIT }
-#define TBL_COL_UINTMAX_FMT(_name, _width, _fmt)        { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_UINTMAX, TBL_COL_LIST_INIT }
-#define TBL_COL_HEXUINT_FMT(_name, _width, _fmt)        { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_UINT, TBL_COL_LIST_INIT }
-#define TBL_COL_BOOL_FMT(_name, _width, _fmt)           { .name = _name, .width = _width, .fmt = _fmt, .type = COL_TYPE_BOOL, TBL_COL_LIST_INIT }
-
-#define TBL_COL_END { .name = 0, .width = 0, .fmt = 0, .type = COL_TYPE_LAST }
+#define TBL_COL_STR(_name, _width)            { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_str }
+#define TBL_COL_INT(_name, _width)            { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_int }
+#define TBL_COL_S64(_name, _width)            { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_s64 }
+#define TBL_COL_UINT(_name, _width)           { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_uint }
+#define TBL_COL_U64(_name, _width)            { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_u64 }
+#define TBL_COL_INTMAX(_name, _width)         { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_intmax }
+#define TBL_COL_UINTMAX(_name, _width)        { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_uintmax }
+#define TBL_COL_HEXUINT(_name, _width)        { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_uint }
+#define TBL_COL_DOUBLE(_name, _width)         { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_double }
+#define TBL_COL_BOOL(_name, _width)           { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = &xt_bool }
+#define TBL_COL_ANY(_name, _width)            { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = COL_TYPE_ANY }
+#define TBL_COL_CUSTOM(_name, _width, _xtype) { .name = _name, .width = _width, .fmt = XTYPE_FMT_DEFAULT, .type_def = _xtype }
+
+#define TBL_COL_STR_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_str }
+#define TBL_COL_INT_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_int }
+#define TBL_COL_S64_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_s64 }
+#define TBL_COL_UINT_FMT(_name, _width, _fmt)           { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_uint }
+#define TBL_COL_U64_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_u64 }
+#define TBL_COL_INTMAX_FMT(_name, _width, _fmt)         { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_intmax }
+#define TBL_COL_UINTMAX_FMT(_name, _width, _fmt)        { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_uintmax }
+#define TBL_COL_HEXUINT_FMT(_name, _width, _fmt)        { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_uint }
+#define TBL_COL_BOOL_FMT(_name, _width, _fmt)           { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_bool }
+#define TBL_COL_ANY_FMT(_name, _width, _fmt)            { .name = _name, .width = _width, .fmt = _fmt, .type_def = COL_TYPE_ANY }
+#define TBL_COL_DOUBLE_FMT(_name, _width, _fmt)         { .name = _name, .width = _width, .fmt = _fmt, .type_def = &xt_double }
+
+#define TBL_COL_END { .name = 0, .width = 0, .fmt = 0, .type_def = NULL }

 
 #define TBL_COLUMNS  .columns = (struct table_column [])
 
 #define TBL_COLUMNS  .columns = (struct table_column [])

-#define TBL_COL_ORDER(order) .column_order = (struct table_col_info *) order, .cols_to_output = ARRAY_SIZE(order)
+#define TBL_COL_ORDER(order) .column_order = (struct table_col_instance *) order, .cols_to_output = ARRAY_SIZE(order)

 #define TBL_COL_DELIMITER(_delimiter_) .col_delimiter = _delimiter_
 #define TBL_COL_DELIMITER(_delimiter_) .col_delimiter = _delimiter_

-#define TBL_COL(_idx) { .idx = _idx, .output_type = -1, .next_column = -1 }
-#define TBL_COL_FMT(_idx, _fmt) { .idx = _idx, .output_type = -1, .next_column = -1, .fmt = _fmt }
-#define TBL_COL_TYPE(_idx, _type) { .idx = _idx, .output_type = _type, .next_column = -1 }
+
+/**
+ * These macros are used for definition of column order
+ **/
+#define TBL_COL(_idx) { .idx = _idx, .output_type = XTYPE_FMT_DEFAULT, .next_column = -1 }
+#define TBL_COL_FMT(_idx, _fmt) { .idx = _idx, .output_type = _fmt, .next_column = -1 }

 
 #define TBL_OUTPUT_HUMAN_READABLE     .formatter = &table_fmt_human_readable
 #define TBL_OUTPUT_BLOCKLINE          .formatter = &table_fmt_blockline
 #define TBL_OUTPUT_MACHINE_READABLE   .formatter = &table_fmt_machine_readable
 
 /**
 
 #define TBL_OUTPUT_HUMAN_READABLE     .formatter = &table_fmt_human_readable
 #define TBL_OUTPUT_BLOCKLINE          .formatter = &table_fmt_blockline
 #define TBL_OUTPUT_MACHINE_READABLE   .formatter = &table_fmt_machine_readable
 
 /**

- * Initialize a table definition. The structure should already contain
+ * The TBL_COL_ITER_START macro are used for iterating over all instances of a particular column in
+ * table _tbl.  _colidx is the column index in _tbl, _instptr is the pointer to the column instance
+ * (struct table_col_instance *), _idxval is the index of current column index. The variables are
+ * enclosed in a block, so they do not introduce variable name collisions.
+ *
+ * The TBL_COL_ITER_END macro must close the block started with TBL_COL_ITER_START.
+ **/
+#define TBL_COL_ITER_START(_tbl, _colidx, _instptr, _idxval) { struct table_col_instance *_instptr = NULL; int _idxval = _tbl->ll_headers[_colidx]; \
+  for(_idxval = _tbl->ll_headers[_colidx], _instptr = _tbl->column_order + _idxval; _idxval != -1; _idxval = _tbl->column_order[_idxval].next_column, _instptr = _tbl->column_order + _idxval)
+
+#define TBL_COL_ITER_END }
+
+/**
+ * Creates a new table from a table template. The template should already contain

  * the definitions of columns.
  **/
  * the definitions of columns.
  **/

-void table_init(struct table *tbl);
+struct table *table_init(const struct table_template *tbl_template);

 
 /** Destroy a table definition, freeing all memory used by it. **/
 void table_cleanup(struct table *tbl);
 
 /** Destroy a table definition, freeing all memory used by it. **/
 void table_cleanup(struct table *tbl);


@@ -245,27 +270,31 @@ void table_end(struct table *tbl);
  *     recently accessed cell.
  ***/
 
  *     recently accessed cell.
  ***/
 

-#define TABLE_COL_PROTO(_name_, _type_) void table_col_##_name_(struct table *tbl, int col, _type_ val);\
-  void table_col_##_name_##_name(struct table *tbl, const char *col_name, _type_ val);\
-  void table_col_##_name_##_fmt(struct table *tbl, int col, const char *fmt, _type_ val) FORMAT_CHECK(printf, 3, 0);

 
 

-// table_col_<type>_fmt has one disadvantage: it is not possible to
-// check whether fmt contains format that contains formatting that is
-// compatible with _type_
+#define TABLE_COL_PROTO(_name_, _type_) void table_col_##_name_(struct table *tbl, int col, _type_ val);
+
+TABLE_COL_PROTO(int, int)
+TABLE_COL_PROTO(uint, uint)
+TABLE_COL_PROTO(double, double)
+TABLE_COL_PROTO(intmax, intmax_t)
+TABLE_COL_PROTO(uintmax, uintmax_t)
+TABLE_COL_PROTO(s64, s64)
+TABLE_COL_PROTO(u64, u64)
+TABLE_COL_PROTO(bool, bool)

 
 

-TABLE_COL_PROTO(int, int);
-TABLE_COL_PROTO(uint, uint);
-TABLE_COL_PROTO(double, double);
-TABLE_COL_PROTO(str, const char *);
-TABLE_COL_PROTO(intmax, intmax_t);
-TABLE_COL_PROTO(uintmax, uintmax_t);
-TABLE_COL_PROTO(s64, s64);
-TABLE_COL_PROTO(u64, u64);
+void table_col_str(struct table *tbl, int col, const char * val);

 
 

-void table_col_bool(struct table *tbl, int col, uint val);
-void table_col_bool_name(struct table *tbl, const char *col_name, uint val);
-void table_col_bool_fmt(struct table *tbl, int col, const char *fmt, uint val);
-#undef TABLE_COL_PROTO
+/** TABLE_COL_BODY macro enables easy definitions of bodies of table_col_<something> functions **/
+#define TABLE_COL_BODY(_name_, _type_) void table_col_##_name_(struct table *tbl, int col, _type_ val) {\
+    table_col_generic_format(tbl, col, (void*)&val, &xt_##_name_);\
+  }
+
+/**
+ * The table_col_generic_format performs all the checks necessary while filling cell with value,
+ * calls the format function from expected_type and stores its result as a cell value. The function
+ * guarantees that each column instance is printed with its format.
+ **/
+void table_col_generic_format(struct table *tbl, int col, void *value, const struct xtype *expected_type);

 
 /**
  * Set a particular cell of the current row to a string formatted
 
 /**
  * Set a particular cell of the current row to a string formatted


@@ -307,6 +336,12 @@ void table_reset_row(struct table *tbl);
  **/
 int table_get_col_idx(struct table *tbl, const char *col_name);
 
  **/
 int table_get_col_idx(struct table *tbl, const char *col_name);
 

+
+/**
+ * Sets a string argument to a column instance
+ **/
+bool table_set_col_opt_default(struct table *tbl, int col_idx, const char *col_arg, char ** err);
+

 /**
  * Returns a comma-and-space-separated list of column names, allocated from table's internal
  * memory pool.
 /**
  * Returns a comma-and-space-separated list of column names, allocated from table's internal
  * memory pool.


@@ -329,6 +364,17 @@ bool table_col_is_printed(struct table *tbl, uint col_idx);
  * Sets the order in which the columns are printed. The specification is a string with comma-separated column
  * names. Returns NULL for success and an error message otherwise. The string is not referenced after
  * this function returns.
  * Sets the order in which the columns are printed. The specification is a string with comma-separated column
  * names. Returns NULL for success and an error message otherwise. The string is not referenced after
  * this function returns.

+ *
+ * The format of the col_order string is the following:
+ * <col-order-string> := <col-def>[,<col-def>]*
+ *
+ * <col-def> := <col-name> '[' <col-opt> ']'
+ *
+ * <col-name> is a string that does not contain comma ',' or '[',']' brackets
+ *
+ * <col-opt> is currently only one string.
+ *
+ * FIXME In the future, we should allow <col-opt> to be a comma(,) separated list of identifiers

  **/
 const char *table_set_col_order_by_name(struct table *tbl, const char *col_order);
 
  **/
 const char *table_set_col_order_by_name(struct table *tbl, const char *col_order);
 


@@ -349,6 +395,7 @@ void table_set_formatter(struct table *tbl, struct table_formatter *fmt);
  * | `cols`    | comma-separated column list   | set order of columns
  * | `fmt`     | `human`/`machine`/`block`     | set table formatter to one of the built-in formatters
  * | `col-delim`| string                       | set column delimiter
  * | `cols`    | comma-separated column list   | set order of columns
  * | `fmt`     | `human`/`machine`/`block`     | set table formatter to one of the built-in formatters
  * | `col-delim`| string                       | set column delimiter

+*  | `cell-fmt` | string                        | set column format type

  * |===================================================================================================
  **/
 const char *table_set_option_value(struct table *tbl, const char *key, const char *value);
  * |===================================================================================================
  **/
 const char *table_set_option_value(struct table *tbl, const char *key, const char *value);


@@ -390,7 +437,6 @@ struct table_formatter {
   void (*table_end)(struct table *tbl);                // [*] table_end callback (optional)
   bool (*process_option)(struct table *tbl, const char *key, const char *value, const char **err);
        // [*] Process table option and possibly return an error message (optional)
   void (*table_end)(struct table *tbl);                // [*] table_end callback (optional)
   bool (*process_option)(struct table *tbl, const char *key, const char *value, const char **err);
        // [*] Process table option and possibly return an error message (optional)

-  const char *formats[];

 };
 
 /** Standard formatter for human-readable output. **/
 };
 
 /** Standard formatter for human-readable output. **/