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   struct table recording_table = {
  43     TBL_COLUMNS {
  44        [TBL_REC_ID] = TBL_COL_UINT("id", 16),
  45        [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
  46        [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
  47        [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
  48        TBL_COL_END
  49     }
  50   };
  51
  52 Each table definition has to be initialized before use by @table_init():
  53
  54   table_init(&recording_table);
  55
  56 Once it is initialized, we can use it for printing multiple tables.
  57 At the start of each table, we should obtain a <<fastbuf:,fastbuf>> where the output
  58 should be sent, store it in the table structure and call @table_start():
  59
  60   struct fastbuf *out = bfdopen_shared(1, 4096);
  61   table_start(&recording_table, out);
  62
  63 Then we can fill the rows one after another. Each row is ended by
  64 @table_end_row():
  65
  66   table_col_uint(&recording_table, TBL_REC_ID, 0);
  67   table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "The Wall");
  68   table_col_str(&recording_table, TBL_REC_ARTIST, "Pink Floyd");
  69   table_col_uint(&recording_table, TBL_REC_YEAR, 1979);
  70   table_end_row(&recording_table);
  71
  72   table_col_uint(&recording_table, TBL_REC_ID, 1);
  73   table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
  74   table_col_str(&recording_table, TBL_REC_ARTIST, "ZZ Top");
  75   table_col_uint(&recording_table, TBL_REC_YEAR, 1972);
  76   table_end_row(&recording_table);
  77
  78 Finally, we should close the table by calling @table_end():
  79
  80   table_end(&recording_table);
  81
  82 At this moment, the table structure is ready to be used again. When
  83 you do not need it any longer, you can dispose of it by @table_cleanup():
  84
  85   table_cleanup(&recording_table);
  86
  87 ucw/table.h
  88 -----------
  89
  90 !!ucw/table.h