--- /dev/null
+UCW-TABLEPRINTER(1)
+===================
+
+NAME
+----
+
+ucw-tableprinter - UCW table printer is a program module that allows user-customized printing of tables.
+
+DESCRIPTION
+-----------
+
+The table printer module provides formatting of 2-dimensional tables
+in various ways.
+
+Each table print-out consists of a number of rows, which are processed
+one after another. All rows have the same number of columns. Once a
+table is defined, it can be printed using a variety of formatters
+(block-line, human-readable, machine-readable, etc.).
+
+The table definition consists of various column definitions, each
+column definition is a pair consisting of a name and a type. Name of
+each column must be unique in the whole table. Each column definition
+can be instantiated(printed) in its own format, e.g., a size column
+can be printed three-times: 1) in bytes; 2) in gigabytes; 3)
+human-readable.
+
+The table can be controlled using various options:
+
+[options="header"]
+|===============================================================================================================
+| option | argument | meaning
+| `header` | 0 or 1 | set whether a table header should be printed
+| `noheader` | 'none' | equivalent to `header`=0
+| `cols` | comma-separated column list | set order of columns
+| `fmt` | `human`/`machine`/`block` | set table formatter to one of the built-in formatters
+| `col-delim` | string | set column delimiter
+| `cells` | string | set column cell format mode, possibilities are: default, raw, pretty
+| `raw` | 'none' | set column cell format to raw data, equivalent to cells:raw
+| `pretty` | 'none' | set column cell format to pretty-printing, equivalent to cells:pretty
+|===============================================================================================================
+
+Column order (`cols` option) has the following format:
+
+<col-order-string> := <col-def>[,<col-def>]*
+
+<col-def> := <col-name> [ '[' <col-opts> ']' ]
+
+<col-name> is a string that does not contain comma ',' or '[',']' brackets
+
+<col-opts> := <string> [ ',' <string> ]
+
+Where <col-opts> is a comma-separated list of options
+
+Column delimiter option (`col-delim`) can be an arbitrary string. The
+cell format option `cells` can have one of the possible three values:
+1) `pretty`, 2) `default`, 3) `raw`. The `raw` and `pretty` value of
+`cells` option can be shortcutted as options `raw` and `pretty` with
+no value.
+
+Additionally to standart types (like integer, floating point) there
+are the two following types: 1) size; 2) timestamp. The 'size' type
+has the following case-sensitive column options: `KB`, `MB`, `GB`,
+`TB`, `auto`, e.g., a column of type size and name `file-size` can be
+specified as `file-size[MB]` or `file-size[auto]`. The 'timestamp'
+has the following case-sensitive column options: 1) `datetime` which
+corresponds to date(1) format "%F %T", 2) `timestamp` which
+corresponds to a number of seconds relative to start of some epoch.
+
+Description of table formats
+-----------------------------
+
+'human-readable': prints columns separated by single space, rows
+separated by newline '\n'.
+
+'block-line': prints each column on one line, i.e., the column
+separator is '\n', rows are separated by double newlines
+'\n\n'. Therefore, rows forms newline separated blocks of rows.
+
+'machine-readable': prints columns separated by a tabulator '\t', rows
+separated by '\n'.
+
The table printer module provides formatting of 2-dimensional tables
in various ways.
-Each table consists of a number of rows, which are processed one
-after another. All rows have the same number of columns. Internally,
-the columns have a fixed order, each column has its name and a data
-type (e.g., int, uint, u64, etc.). The table printer checks that
-each cell is filled by a value of the appropriate type, except that
-a string value is allowed in any cell (for example, this allows
-a numeric cell to be set to "--" or "unknown").
-
-Once a table is defined, it can be printed using a variety of formatters
-(human-readable, tab-separated values, etc.). Also, a subset of columns
-can be selected and their order changed.
+Each table print-out consists of a number of rows, which are processed
+one after another. All rows have the same number of columns.
+Internally, the columns have a fixed order, each column has its name
+and a data type (e.g., int, uint, u64, etc.). The data type is
+realized using extended types (referred to as xtypes). The table
+printer checks that each cell is filled by a value of the appropriate
+type, except that a string value is allowed in any cell (for example,
+this allows a numeric cell to be set to "--" or "unknown"). Once a
+table is defined, it can be printed using a variety of formatters
+(human-readable, tab-separated values, etc.) and its cells can be
+formatted using at least three different formats: 1) pretty (or
+human-readable); 2) raw; 3) default.
+
+The table definition consists of various column types, each column
+type is a pair consisting of a name and a data type. Name of each
+column must be unique in the whole table definition. Each column type
+can have multiple instances in the final table print-out. The columns
+are printed using xtypes. For example: let have a column definition
+with name 'size' of type xt_size. The column can be printed on
+position 0 (in bytes) and position 5 (in kilobytes). This allows easy
+filtering using standart cmd line filters. For example, we want to
+remove all rows that has size greater then 1572864 bytes (1.5MB) and
+print the size in human readable format. Human readable format means
+that if there is size of 1610612736 bytes it will be rather printed as
+1536MB.
+
+Also, columns can be printed in an arbitrary order and with repeated
+columns.
Example
-------
projects / libucw.git / commitdiff