ucw/doc/table.txt

   1 Tableprinter
   2 ============
   3
   4 The table.h provides table printing facility. We need to print table
   5 with arbitrary column types (e.g. int, uint, u64, etc.). The table
   6 columns have names and the order of the columns is configurable. The
   7 table checks that the user writes correct type into a cell of the
   8 table. Additionally, the table allows to print string to an arbitrary
   9 cell (in order to make the table slightly more flexible).
  10
  11 We should be able to print the table in various formats. Currently
  12 there is a human readable format
  13
  14 We demonstrate the table on a table that contains music recordings:
  15
  16 The following enum defines the column indices (the enum is indexed
  17 starting from 0):
  18
  19 // definition of columns
  20 enum table_columns {
  21    TBL_REC_ID,
  22    TBL_REC_ALBUM_NAME,
  23    TBL_REC_ARTIST,
  24    TBL_REC_YEAR
  25 };
  26
  27 The following structure contains definition of the table. The table
  28 columns are defined using the TBL_COL_xxx and TBL_COL_xxx_FMT
  29 macros. The TBL_COL_xxx macro has two arguments: (1) column name; (2)
  30 width of the table column. The TBL_COL_xxx_FMT has an additional
  31 format argument. There exists flags that causes the column to be
  32 left-aligned (see TBL_REC_ALBUM_NAME for a reference). An example of
  33 the table follows:
  34
  35 struct table recording_table = {
  36   TBL_COLUMNS {
  37      [TBL_REC_ID] = TBL_COL_UINT("id", 16),
  38      [TBL_REC_ALBUM_NAME] = TBL_COL_STR_FMT("album-name", 20 | CELL_ALIGN_LEFT, "%s"),
  39      [TBL_REC_ARTIST] = TBL_COL_STR("artist", 20),
  40      [TBL_REC_YEAR] = TBL_COL_UINT("year", 10),
  41      TBL_COL_END
  42   }
  43 };
  44
  45 The table struct can be reused for printing of multiple tables.  The
  46 usage of the table is used as follows. After the table init is called:
  47
  48 table_init(&recording_table);
  49
  50 the table is initialized and ready to use. To start printing of the
  51 table, the user has to initialize the fastbuf (which is used for
  52 output) and call table_start:
  53
  54 struct fastbuf *out = bfdopen_shared(1, 4096);
  55
  56 table_start(&recording_table, out);
  57
  58 after the table_start is called, we can start filling the rows. Each
  59 row is ended by table_end_row:
  60
  61 table_col_uint(&recording_table, TBL_REC_ID, 0);
  62 table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "The Wall");
  63 table_col_str(&recording_table, TBL_REC_ARTIST, "Pink Floyd");
  64 table_col_uint(&recording_table, TBL_REC_YEAR, 1979);
  65 table_end_row(&recording_table);
  66
  67 table_col_uint(&recording_table, TBL_REC_ID, 1);
  68 table_col_str(&recording_table, TBL_REC_ALBUM_NAME, "Rio Grande Mud");
  69 table_col_str(&recording_table, TBL_REC_ARTIST, "ZZ Top");
  70 table_col_uint(&recording_table, TBL_REC_YEAR, 1972);
  71 table_end_row(&recording_table);
  72
  73 Printing of the whole table is endded by calling of the table_end():
  74
  75 table_end(&recording_table);
  76
  77
  78 To reuse the recording_table, we just call table_start followed by
  79 table_end once again.
  80
  81 At the end of the lifetime of the struct recording_table we call:
  82 table_cleanup(&recording_table);
  83