From 3ac63c12b1eb6b8eb3bab45dfed93636e6c0c30f Mon Sep 17 00:00:00 2001 From: Robert Kessl Date: Mon, 4 Aug 2014 13:45:12 +0200 Subject: [PATCH] tableprinter: update of documentation --- ucw/doc/table-user.txt | 81 ++++++++++++++++++++++++++++++++++++++++++ ucw/doc/table.txt | 39 ++++++++++++++------ 2 files changed, 109 insertions(+), 11 deletions(-) create mode 100644 ucw/doc/table-user.txt diff --git a/ucw/doc/table-user.txt b/ucw/doc/table-user.txt new file mode 100644 index 00000000..4f9b64a0 --- /dev/null +++ b/ucw/doc/table-user.txt @@ -0,0 +1,81 @@ +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: + + := [,]* + + := [ '[' ']' ] + + is a string that does not contain comma ',' or '[',']' brackets + + := [ ',' ] + +Where 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'. + diff --git a/ucw/doc/table.txt b/ucw/doc/table.txt index 4c8eee15..65cd291b 100644 --- a/ucw/doc/table.txt +++ b/ucw/doc/table.txt @@ -4,17 +4,34 @@ Table printer 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 ------- -- 2.39.2