X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Ftable.h;h=494276bada5f4d14a95de042d5a468c01390961e;hb=a7bae3293ad367903df28054af1e0b9be3d169b5;hp=a7c0236eff57869278935fbdfc25b9a986373057;hpb=a28ed79993e6fb8542d917e9270b0245860f35cb;p=libucw.git diff --git a/ucw/table.h b/ucw/table.h index a7c0236e..494276ba 100644 --- a/ucw/table.h +++ b/ucw/table.h @@ -81,19 +81,24 @@ struct table_column { uint fmt; // [*] default format of the column const struct xtype *type_def; // [*] pointer to xtype of this column - const char * (*set_col_opt)(struct table *tbl, uint col, const char *value); - // [*] process table option for a column instance - // FIXME: Comment on arguments and return value + const char * (*set_col_opt)(struct table *tbl, uint col_inst_idx, const char *col_opt); + // [*] process table option for a column instance. @col_inst_idx is the index of the column + // instance to which the @col_opt is set. Return value is the error string. }; -// 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 +/** + * Definition of a column instance. The table_col_instance belongs to a struct table. col_def is + * pointing to a definition of the column in struct table::columns. The user can fill only the @idx + * and @fmt. The @col_def, @cell_content, @next_column are private fields. + * + * Please use only fields marked with `[*]`. + **/ struct table_col_instance { - uint idx; // idx is a index into struct table::columns + 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 fmt; // format of this column + uint fmt; // [*] format of this column }; /** @@ -103,10 +108,9 @@ struct table_col_instance { 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 - const struct table_formatter *formatter; // FIXME: should be const? + const struct table_formatter *formatter; }; /** @@ -129,15 +133,13 @@ struct table { bool print_header; // [*] false indicates that table header should not be printed struct fastbuf *out; // [*] Fastbuffer to which the table is printed - int last_printed_col; // Index of the last column which was set. -1 indicates start of row. - // Used for example for appending to the current column. - bool row_printing_started; // Indicates that a row has been started. Duplicates last_printed_col, but harmlessly. + bool row_printing_started; // Indicates that a row has been started. struct fbpool fb_col_out; // Per-cell fastbuf, see table_col_fbstart() int col_out; // Index of the column that is currently printed using fb_col_out // Back-end used for table formatting and its private data const struct table_formatter *formatter; - void *data; + void *formatter_data; }; /**** @@ -149,7 +151,7 @@ struct table { * * `TBL_COL_`'type'`_FMT(name, width, fmt)` defines a column with a custom format string * * `TBL_COL_END` ends the column definitions * * `TBL_COL_ORDER` specifies custom ordering of columns in the output - * * `TBL_COL_DELIMITER` and `TBL_APPEND_DELIMITER` override default delimiters + * * `TBL_COL_DELIMITER` overrides the default delimiter * * `TBL_FMT_HUMAN_READABLE` requests human-readable formatting (this is the default) * * `TBL_FMT_MACHINE_READABLE` requests machine-readable TSV output * * `TBL_FMT_BLOCKLINE` requests block formatting (each cell printed a pair of a key and value on its own line) @@ -184,7 +186,7 @@ struct table { #define TBL_COL_END { .name = 0, .width = 0, .fmt = 0, .type_def = NULL } #define TBL_COLUMNS .columns = (struct table_column []) -#define TBL_COL_ORDER(order) .column_order = (struct table_col_instance *) order, .cols_to_output = ARRAY_SIZE(order) +#define TBL_COL_ORDER(order) .column_order = (struct table_col_instance *) order #define TBL_COL_DELIMITER(_delimiter) .col_delimiter = _delimiter /** @@ -192,6 +194,7 @@ struct table { **/ #define TBL_COL(_idx) { .idx = _idx, .fmt = XTYPE_FMT_DEFAULT, .next_column = -1 } #define TBL_COL_FMT(_idx, _fmt) { .idx = _idx, .fmt = _fmt, .next_column = -1 } +#define TBL_COL_ORDER_END { .col_def = 0, .idx = ~0U, .fmt = 0, .next_column = -1 } /** * These macros are aliases to various kinds of table formats. @@ -199,22 +202,7 @@ struct table { #define TBL_FMT_HUMAN_READABLE .formatter = &table_fmt_human_readable #define TBL_FMT_BLOCKLINE .formatter = &table_fmt_blockline #define TBL_FMT_MACHINE_READABLE .formatter = &table_fmt_machine_readable - -/** - * 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. - * - * These macros are usually used to hide the implementation details of the column instances linked - * list. This is usefull for definition of new types. - **/ -#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 } +#define TBL_FMT(_fmt) .formatter = _fmt /** * Creates a new table from a table template. The template should already contain @@ -246,11 +234,10 @@ void table_end(struct table *tbl); * For each column type, there are functions for filling of cells * of the particular type: * - * * `table_col_`'type'`(table, idx, value)` sets the cell in column `idx` + * * `table_col_`'type'`(table, col_def_idx, value)` sets the cell in column `col_def_idx` * to the `value` ***/ - #define TABLE_COL_PROTO(_name, _type) void table_col_##_name(struct table *tbl, int col, _type val); TABLE_COL_PROTO(int, int) @@ -261,8 +248,7 @@ TABLE_COL_PROTO(uintmax, uintmax_t) TABLE_COL_PROTO(s64, s64) TABLE_COL_PROTO(u64, u64) TABLE_COL_PROTO(bool, bool) - -void table_col_str(struct table *tbl, int col, const char * val); +TABLE_COL_PROTO(str, const char *) /** TABLE_COL_BODY macro enables easy definitions of bodies of table_col_ functions **/ #define TABLE_COL_BODY(_name, _type) void table_col_##_name(struct table *tbl, int col, _type val) {\ @@ -312,25 +298,23 @@ void table_reset_row(struct table *tbl); ***/ /** - * Find the index of a column with name @col_name. Returns -1 if there is no such column. + * Find the index of a column definition with name @col_name. Returns -1 if there is no such column. **/ int table_get_col_idx(struct table *tbl, const char *col_name); - /** - * Sets a string option to an instance of a column type. This is the default version that checks - * whether the xtype::parse_fmt can be called and calls it. However, there are situation in which - * the xtype::parse_fmt is not sufficient, e.g., column decoration, post-processing, etc. + * Sets a string option on a column instance. * - * Each struct table_column has a pointer to a customized version of table_set_col_opt which is - * called instead of this (default) version of table_set_col_opt + * By default, the option is parsed as a formatting mode of the corresponding <> + * using <>. * - * FIXME: Make table_set_col_opt() a front-end function used by everybody, - * which checks if the set_col_opt hook is defined and either calls it or - * processes the options in the generic way. Nobody else should call the - * hook directly. + * As special cases might require special handling (e.g., column decoration, post-processing, etc.), + * a column can define a `set_col_opt` hook, which takes over option parsing. (Beware, the hook must + * not be called directly and it must not call this function.) + * + * See <> for more. **/ -const char *table_set_col_opt(struct table *tbl, uint col_idx, const char *col_opt); +const char *table_set_col_opt(struct table *tbl, uint col_inst_idx, const char *col_opt); /** * Returns a comma-and-space-separated list of column names, allocated from table's internal @@ -339,59 +323,38 @@ const char *table_set_col_opt(struct table *tbl, uint col_idx, const char *col_o const char *table_get_col_list(struct table *tbl); /** - * Sets the order in which the columns are printed. - * The table converts the integers in @col_order into an internal representation stored - * in `column_order`. Options to column instances can be set using @table_set_col_opt(). - **/ -void table_set_col_order(struct table *tbl, int *col_order, int col_order_size); - -/** - * Returns true if col_idx will be printed, false otherwise. + * Sets the order in which the columns are printed. The columns are specified by array of struct + * @table_col_instance. This allows specification of format. The user should make an array of struct + * @table_col_instance and fill the array using the TBL_COL and TBL_COL_FMT. The array has a special + * last element: @TBL_COL_ORDER_END. * - * FIXME: Naming of arguments is confusing. @col_idx sometimes indexes - * columns, but sometimes their instances. + * The table copies content of @col_order into an internal representation stored + * in `column_order`. Options to column instances can be set using @table_set_col_opt(). **/ -bool table_col_is_printed(struct table *tbl, uint col_idx); +void table_set_col_order(struct table *tbl, const struct table_col_instance *col_order); /** * 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: - * := [,]* - * - * := '[' ']' - * - * is a string that does not contain comma ',' or '[',']' brackets - * - * is currently only one string without commas. In the future the format can be ,,... . - * - * FIXME In the future, we should allow to be a comma(,) separated list of identifiers + * See <> for full syntax. **/ const char *table_set_col_order_by_name(struct table *tbl, const char *col_order); +/** + * Returns true if @col_def_idx will be printed, false otherwise. + **/ +bool table_col_is_printed(struct table *tbl, uint col_def_idx); + /** * Sets table formatter. See below for the list of formatters. **/ void table_set_formatter(struct table *tbl, const struct table_formatter *fmt); /** - * Set a table option. All options have a key and a value. Currently, - * the following keys are defined (other keys can be accepted by formatters): - * - * [options="header"] - * |=================================================================================================== - * | key | value | meaning - * | `header` | 0 or 1 | set whether a table header should be printed - * | `noheader` | 'none' | equivalent to `header`=0 - * | `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 - * | `cells` | string | set column format mode - * | `raw` | 'none' | set column format to raw data - * | `pretty` | 'none' | set column format to pretty-printing - * |=================================================================================================== + * Set a table option. All options have a key and a value. + * See <>. **/ const char *table_set_option_value(struct table *tbl, const char *key, const char *value);