ucw/doc/ucw-tableprinter.txt

   1 UCW-TABLEPRINTER(1)
   2 ===================
   3
   4 NAME
   5 ----
   6
   7 ucw-tableprinter - UCW table printer is a program module that allows user-customized printing of tables.
   8
   9 DESCRIPTION
  10 -----------
  11
  12 The table printer module provides formatting of 2-dimensional tables
  13 in various ways.
  14
  15 Each table print-out consists of a number of rows, which are processed
  16 one after another. All rows have the same number of columns. Once a
  17 table is defined, it can be printed using a variety of formatters
  18 (block-line, human-readable, machine-readable, etc.).
  19
  20 The table definition consists of various column definitions, each
  21 column definition is a pair consisting of a name and a type. Name of
  22 each column must be unique in the whole table. Each column definition
  23 can be instantiated(printed) in its own format, e.g., a size column
  24 can be printed three-times: 1) in bytes; 2) in gigabytes; 3)
  25 human-readable.
  26
  27 The table can be controlled using various options:
  28
  29 [options="header"]
  30 |===============================================================================================================
  31 | option      | argument                    | meaning
  32 | `header`    | 0 or 1                      | set whether a table header should be printed
  33 | `noheader`  | 'none'                      | equivalent to `header`=0
  34 | `cols`      | comma-separated column list | set order of columns
  35 | `fmt`       | `human`/`machine`/`block`   | set table formatter to one of the built-in formatters
  36 | `col-delim` | string                      | set column delimiter
  37 | `cells`     | string                      | set column cell format mode, possibilities are: default, raw, pretty
  38 | `raw`       | 'none'                      | set column cell format to raw data, equivalent to cells:raw
  39 | `pretty`    | 'none'                      | set column cell format to pretty-printing, equivalent to cells:pretty
  40 |===============================================================================================================
  41
  42 Column order (`cols` option) has the following format:
  43
  44 <col-order-string> := <col-def>[,<col-def>]*
  45
  46 <col-def> := <col-name> [ '[' <col-opts> ']' ]
  47
  48 <col-name> is a string that does not contain comma ',' or '[',']' brackets
  49
  50 <col-opts> := <string> [ ',' <string> ]
  51
  52 Where <col-opts> is a comma-separated list of options.
  53
  54 Column delimiter option (`col-delim`) can be an arbitrary string. The
  55 cell format option `cells` can have one of the possible three values:
  56 1) `pretty`, 2) `default`, 3) `raw`. The `raw` and `pretty` value of
  57 `cells` option can be shortcutted as options `raw` and `pretty` with
  58 no value.
  59
  60 Additionally to standard types (like integer, floating point) there
  61 are the two following types: 1) size; 2) timestamp. The 'size' type
  62 has the following case-sensitive column options: `KB`, `MB`, `GB`,
  63 `TB`, `auto`, e.g., a column of type size and name `file-size` can be
  64 specified as `file-size[MB]` or `file-size[auto]`.  The 'timestamp'
  65 has the following case-sensitive column options: 1) `datetime` which
  66 corresponds to date(1) format "%F %T", 2) `timestamp` which
  67 corresponds to a number of seconds relative to start of some epoch.
  68
  69 Description of table formats
  70 -----------------------------
  71
  72 'human-readable': prints columns separated by single space, rows
  73 separated by newline '\n'.
  74
  75 'block-line': prints each column on one line, i.e., the column
  76 separator is '\n', rows are separated by double newlines
  77 '\n\n'. Therefore, rows forms newline separated blocks of rows.
  78
  79 'machine-readable': prints columns separated by a tabulator '\t', rows
  80 separated by '\n'.
  81