ucw/doc/table.txt

   1 Table printer
   2 =============
   3
   4 The table printer module provides formatting of 2-dimensional tables
   5 in various ways.
   6
   7 Each table print-out consists of a number of rows, which are processed
   8 one after another. All rows have the same number of columns.
   9 Internally, the columns have a fixed order, each column has its name
  10 and a data type (e.g., int, uint, u64, etc.). The data type is
  11 realized using extended types (referred to as xtypes). The table
  12 printer checks that each cell is filled by a value of the appropriate
  13 type, except that a string value is allowed in any cell (for example,
  14 this allows a numeric cell to be set to "--" or "unknown"). Once a
  15 table is defined, it can be printed using a variety of formatters
  16 (human-readable, tab-separated values, etc.) and its cells can be
  17 formatted using at least three different formats: 1) pretty (or
  18 human-readable); 2) raw; 3) default.
  19
  20 The table definition consists of various column types, each column
  21 type is a pair consisting of a name and a data type. Name of each
  22 column must be unique in the whole table definition.  Each column type
  23 can have multiple instances in the final table print-out. The columns
  24 are printed using xtypes.  For example: let have a column definition
  25 with name 'size' of type xt_size. The column can be printed on
  26 position 0 (in bytes) and position 5 (in kilobytes).  This allows easy
  27 filtering using standart cmd line filters. For example, we want to
  28 remove all rows that has size greater then 1572864 bytes (1.5MB) and
  29 print the size in human readable format. Human readable format means
  30 that if there is size of 1610612736 bytes it will be rather printed as
  31 1536MB.
  32
  33 Also, columns can be printed in an arbitrary order and with repeated
  34 columns.
  35
  36 Example
  37 -------
  38
  39 Let us construct a simple table of music recordings:
  40
  41 First, we define an enum with column indices (the values are automatically
  42 numbered starting from 0):
  43
  44   enum table_columns {
  45      TBL_REC_ID,
  46      TBL_REC_ALBUM_NAME,
  47      TBL_REC_ARTIST,
  48      TBL_REC_YEAR
  49   };
  50
  51 Then we create a structure with the definition of our table.
  52 The table columns are defined using the `TBL_COL_`'type' and `TBL_COL_`'type'`_FMT`
  53 macros. Each macro gets the name of the column and its default width
  54 in characters. The `_FMT` version adds an explicit format
  55 string for `printf` used for this column. Moreover, various flags can
  56 be OR-ed to the width of the column, for example `CELL_ALIGN_LEFT` prescribes
  57 that the cell should be aligned to the left.
  58
  59 To define the column order, we can create an array of struct table_col_info
  60 using the following macros: TBL_COL, TBL_COL_FMT, TBL_COL_TYPE. An example
  61 follows:
  62
  63   struct table_col_info column_order[] = { TBL_COL(TBL_REC_ID), TBL_COL(TBL_REC_ALBUM_NAME) };
  64
  65 The column order is supplied in the struct table_template using the TBL_COL_ORDER macro.
  66
  67   struct table_template recording_table_template = {
  68     TBL_COLUMNS {
  69        [TBL_REC_ID] = TBL_COL_UINT("id", 16),
  70        [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
  71        [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
  72        [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
  73        TBL_COL_END
  74     },
  75     TBL_COL_ORDER(column_order)
  76   };
  77
  78
  79 Each table definition has to be created from a template before use by @table_init():
  80
  81   struct table *rec_table = table_init(&recording_table_template);
  82
  83 Once it is initialized, we can use it for printing multiple tables.
  84 At the start of each table, we should obtain a <<fastbuf:,fastbuf>> where the output
  85 should be sent, store it in the table structure and call @table_start():
  86
  87   struct fastbuf *out = bfdopen_shared(1, 4096);
  88   table_start(&rec_table, out);
  89
  90 Then we can fill the rows one after another. Each row is ended by
  91 @table_end_row():
  92
  93   table_col_uint(&rec_table, TBL_REC_ID, 0);
  94   table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "The Wall");
  95   table_col_str(&rec_table, TBL_REC_ARTIST, "Pink Floyd");
  96   table_col_uint(&rec_table, TBL_REC_YEAR, 1979);
  97   table_end_row(&rec_table);
  98
  99   table_col_uint(&rec_table, TBL_REC_ID, 1);
 100   table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
 101   table_col_str(&rec_table, TBL_REC_ARTIST, "ZZ Top");
 102   table_col_uint(&rec_table, TBL_REC_YEAR, 1972);
 103   table_end_row(&rec_table);
 104
 105 Finally, we should close the table by calling @table_end():
 106
 107   table_end(&rec_table);
 108
 109 At this moment, the table structure is ready to be used again. When
 110 you do not need it any longer, you can dispose of it by @table_cleanup():
 111
 112   table_cleanup(&rec_table);
 113
 114 ucw/table.h
 115 -----------
 116
 117 !!ucw/table.h