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 consists of a number of rows, which are processed one
   8 after another. All rows have the same number of columns. Internally,
   9 the columns have a fixed order, each column has its name and a data
  10 type (e.g., int, uint, u64, etc.). The table printer checks that
  11 each cell is filled by a value of the appropriate type, except that
  12 a string value is allowed in any cell (for example, this allows
  13 a numeric cell to be set to "--" or "unknown").
  14
  15 Once a table is defined, it can be printed using a variety of formatters
  16 (human-readable, tab-separated values, etc.). Also, a subset of columns
  17 can be selected and their order changed.
  18
  19 Example
  20 -------
  21
  22 Let us construct a simple table of music recordings:
  23
  24 First, we define an enum with column indices (the values are automatically
  25 numbered starting from 0):
  26
  27   enum table_columns {
  28      TBL_REC_ID,
  29      TBL_REC_ALBUM_NAME,
  30      TBL_REC_ARTIST,
  31      TBL_REC_YEAR
  32   };
  33
  34 Then we create a structure with the definition of our table.
  35 The table columns are defined using the `TBL_COL_`'type' and `TBL_COL_`'type'`_FMT`
  36 macros. Each macro gets the name of the column and its default width
  37 in characters. The `_FMT` version adds an explicit format
  38 string for `printf` used for this column. Moreover, various flags can
  39 be OR-ed to the width of the column, for example `CELL_ALIGN_LEFT` prescribes
  40 that the cell should be aligned to the left.
  41
  42 To define the column order, we can create an array of struct table_col_info
  43 using the following macros: TBL_COL, TBL_COL_FMT, TBL_COL_TYPE. An example
  44 follows:
  45
  46   struct table_col_info column_order[] = { TBL_COL(TBL_REC_ID), TBL_COL(TBL_REC_ALBUM_NAME) };
  47
  48 The column order is supplied in the struct table using the TBL_COL_ORDER macro.
  49
  50   struct table recording_table_template = {
  51     TBL_COLUMNS {
  52        [TBL_REC_ID] = TBL_COL_UINT("id", 16),
  53        [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
  54        [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
  55        [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
  56        TBL_COL_END
  57     },
  58     TBL_COL_ORDER(column_order)
  59   };
  60
  61
  62 Each table definition has to be created from a template before use by @table_init():
  63
  64   struct table *rec_table = table_init(&recording_table_template);
  65
  66 Once it is initialized, we can use it for printing multiple tables.
  67 At the start of each table, we should obtain a <<fastbuf:,fastbuf>> where the output
  68 should be sent, store it in the table structure and call @table_start():
  69
  70   struct fastbuf *out = bfdopen_shared(1, 4096);
  71   table_start(&rec_table, out);
  72
  73 Then we can fill the rows one after another. Each row is ended by
  74 @table_end_row():
  75
  76   table_col_uint(&rec_table, TBL_REC_ID, 0);
  77   table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "The Wall");
  78   table_col_str(&rec_table, TBL_REC_ARTIST, "Pink Floyd");
  79   table_col_uint(&rec_table, TBL_REC_YEAR, 1979);
  80   table_end_row(&rec_table);
  81
  82   table_col_uint(&rec_table, TBL_REC_ID, 1);
  83   table_col_str(&rec_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
  84   table_col_str(&rec_table, TBL_REC_ARTIST, "ZZ Top");
  85   table_col_uint(&rec_table, TBL_REC_YEAR, 1972);
  86   table_end_row(&rec_table);
  87
  88 Finally, we should close the table by calling @table_end():
  89
  90   table_end(&rec_table);
  91
  92 At this moment, the table structure is ready to be used again. When
  93 you do not need it any longer, you can dispose of it by @table_cleanup():
  94
  95   table_cleanup(&rec_table);
  96
  97 ucw/table.h
  98 -----------
  99
 100 !!ucw/table.h