'''Tabulate''' is a command line utility that converts the standard input into pretty-printed tables. It is also a Tcl [module] that does the same with lists of lists. It was inspired by https://github.com/joepvd/table. Tabulate works in Tcl 8.5+ and [Jim Tcl].

It is now developed as part of the [Sqawk] project.

Download the latest version: `curl https://raw.githubusercontent.com/dbohdan/sqawk/master/lib/tabulate.tcl > tabulate.tcl`



** Use example **

*** Command line ***

======
$ ps | jimsh ./tabulate.tcl   
┌─────┬─────┬────────┬─────┐
│ PID │ TTY │  TIME  │ CMD │
├─────┼─────┼────────┼─────┤
│20583│pts/3│00:00:01│ zsh │
├─────┼─────┼────────┼─────┤
│23301│pts/3│00:00:00│  ne │
├─────┼─────┼────────┼─────┤
│28007│pts/3│00:00:00│  ps │
├─────┼─────┼────────┼─────┤
│28008│pts/3│00:00:00│jimsh│
└─────┴─────┴────────┴─────┘
======

*** tclsh ***

======
% source tabulate.tcl
% ::tabulate::tabulate -data {{Hello World} {11 101}}
┌─────┬─────┐
│Hello│World│
├─────┼─────┤
│ 11  │ 101 │
└─────┴─────┘
======



** Usage **

Below are the options you can pass to `tabulate.tcl` on the command line and/or the procedure `::tabulate::tabulate` in Tcl.

%| Option | Description | Example |%
&| `-FS` (command line only) | The field separator for the input. If set to an empty string, which is the default, any Tcl [whitespace] is treated as a separator. | `-FS ,` |&
&| `-data` (Tcl only) | The data to format. | `-data {{foo bar} {11 101}}` |&
&| `-style` | The characters with which to draw the table. Set to `default` for Unicode or `loFi` for 7-bit ASCII. | `-style loFi` |&
&| `-align` or `-alignments` | Which way (`left`, `right`, or `center`, the default) to align the text in each column. This only makes a difference if a cell's contents is narrower than the full width of the column. It has no effect if all cells' contents is the same width. | `-align "left center right"` |&
&| `-margins` | The number of extra spaces to put on each side of the contents of each cell (zero by default). | `-margins 5` |&



** `::tabulate::options` DSL **

Tabulate's code includes a DSL for processing [named arguments] stored in [args].

*** Use example ***

======
proc ::tabulate::tabulate args {
    options::process $args \
        store -data in data \
        store -style in style default $::tabulate::style::default \
        store -alignments or -align in align default {} \
        store -margins in margins default 0

    # ...
}
======



** Discussion **

[JM] 2015-08-03: I am probably doing something wrong:<<br>>
 % info tclversion
 8.6
 % info patchlevel
 8.6.4
 % source tabulate.tcl
 % ::tabulate::tabulate -data {{Hello World!}}
 wrong # args: should be "dict exists dictionary key ?key ...?"

[dbohdan] 2015-08-03: I cannot reproduce that on my system by just following your transcript. Could you file an issue at https://github.com/dbohdan/sqawk/issues?

[JM] 2015-08-03: never mind, I found the error on my side...there were spaces after the "\" line continuations, hence breaking the command. Somehow I got that from the copy-paste from the source.
 +------------------------------+
 ¦Thanks¦for¦sharing¦      ¦    ¦
 +------+---+-------+------+----¦
 ¦ This ¦ is¦   a   ¦second¦line¦
 +------------------------------+

[APN] 2015-11-20: Neat and useful. One small caveat - you have to remember to use `-encoding utf-8` with the source command since the style::default variable embeds graphics as raw UTF-8 characters. For cases where you don't have control of the source command used to pull in the tabulate.tcl file (for example with [critcl]), below is the equivalent using escape sequences.

======
    variable default {
        top {
            left \U250C
            padding \U2500
            separator \U252C
            right \U2510
        }
        separator {
            left \U251C
            padding \U2500
            separator \U253C
            right \U2524
        }
        row {
            left \U2502
            padding { }
            separator \U2502
            right \U2502
        }
        bottom {
            left \U2514
            padding \U2500
            separator \U2534
            right \U2518
        }
    }
======



** Code **

See https://github.com/dbohdan/sqawk/blob/master/lib/tabulate.tcl.



** See also **

   * [report]
   * [http://core.tcl-lang.org/tcllib/doc/trunk/embedded/www/tcllib/files/modules/report/report.html#section7%|%Report examples]

<<categories>> Application | Argument Processing | Jim Package | Text Screen