--- name: "showtable" section: "1p" platform: "linux" package: "libdata-showtable-perl" version: "4.6-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/showtable/1p" --- # showtable(1p) Show data in nicely formatted columns ## NAME showtable - Show data in nicely formatted columns ## USAGE **showtable** \[-*options*\] \[*file*\] ## DESCRIPTION **Showtable** reads an input data stream and displays it in a nicely formatted listing, with exact formatting depending upon the options. The input stream, *file* or `"STDIN"` by default should consist of data separated by tabs or the defined *separator* character (see **-d**). The actual output formatting is peformed by the **ShowTable** module. ## OPTIONS There are two general sets of options: those which help determine the format of the input, and those which determine the format of the output. ### Options affecting input - **-break=***str* Set the inter-column break string to "*str*". The default is a tab ("`"\t"`"). If **-strip** is also given, blanks surrounding the break string will also be ignored. - **-d***str* This is the same as `"-break="`*str*. - **-nod(ashes)** Do not ignore lines of separators, such as dashes, equal signs, or underlines. If **-nodashes** is given, and these lines do occur in the stream, they will be treated as normal data. - **-ti(tles)\[=***NN***\]** Treat the first *NN* rows of data as column titles; multiple words in the column titles may wrap vertically. If *NN* is omitted, it defaults to 1. No **-titles** option is the same as **-titles=0**. - **-in(put)=***type* Set the input type as *type*, which can be one of: *box*, *list*, *table*, or *simple*. A *simple*-type table is the same as a *table*-type, but no wrapping characters are recognized. - **-s(trip)** Strip blanks from around the column values. - **-nos(trip)** Do not strip blanks from the input. Useful if there is formatted or aligned data within a boxed table. ### Options affecting output - **-t(able)** Use a *table* format for output, with wrapping of column values longer than the given or determined column widths. See Data::ShowTable for more details. - **-si(mple)** Use a simple table format, without any wrapping of column values. See Data::ShowTable for more details. - **-l(ist)** Use a list style format. See Data::ShowTable for more details. - **-b(ox)** Use a "boxed" style table. See Data::ShowTable for more details. - **-ht(ml)** Use HTML-formating. See Data::ShowTable for more details. - **-ti(tles)=***name1***,***name2***,...,***nameN* Define the column names explicitly. This is useful for naming columns of data from `"STDIN"`, when **showtable** is being used as a filter. The first column name, *name1*, cannot begin with a digit. This option allows any column titles obtained from the input to be overridden. - **-noh(eaders)** Do not output any headers on the tables; **-titles=0** implies this option. - **-f***n1*\[,*n2*, ..., *nN*\] Select fields numbered *n1*, *n2*, etc., to display. Each *nN* is a field index, or a range of indexes in the form: `"N"`-`"M"` The default is to show all the fields in each row. Fields are numbered from 1. An example: to show the first, and three through five fields of the `"/etc/passwd"` file: ``` showtable -d: -f1,2-5 /etc/passwd ``` - **-fields**=*fname1*\[,*fname2*, ..., *fnameN*\] Select the named fields to display. The field names must be available, either through the data stream, or by using the **-titles** option. The field names given must match the existing field names *exactly*. Using the file `"/etc/passwd"` for another example: to show the same first two fields, by name: ``` showtable -d: -titles=Login,UID -fields=Login,UID /etc/passwd ``` - **-w(idth)**=*num* Set the maximum table width. This value is applied to the variable Data::Showtable::Max\_Table\_Width. When the total width of all columns to be displayed exceeds this value, all column widths are scaled uniformly. If **-width** is not given, then for all output but **-html**, the default value is either "`"COLUMNS"`", if defined, or 80, if not. Whith **-html** mode, there is no default value for **-width**; in other words, there is no limit to the width. - **-cw(idths)**=*w1*\[,*w2*,...,*wN*\] Set individual column widths to the specified values. Empty column widths imply no maximum width. If the **-width** option is also given, then the **-cwidth** column widths can also be given as fractions or percentages. Example: To set the maximum width of the third column to 20 characters: ``` -cw=,,20 ``` ### HTML-only options (the usage of which implies -html) - **-noe(scape)** Do not perform HTML escape sequences on the data; this allows embedded HTML text in the data to be displayed properly with the **-html** option. - **-attributes**='*attr1* *attr2* ...' Declare the table attributes, which are inserted into the `"TABLE"` token. For example, the option: ``` -attributes='BORDER=0 CELLSPACING=2 CELLPADDING=4' ``` would cause the following HTML: ``` ``` The default table attributes are: ```
``` - **-t(itle)\_f(ormats)**=*fmt1*;*fmt2*;...;*fmtN* Set the HTML formats for the column titles. The **-title\_formats** (or just **-tf**) can be given multiple times, for each column, or formats for multiple columns can be given on the same option separated by semi-colons "`";"`". Each *fmtN* can itself be multiple HTML items, separated by commas. Each HTML element can be given either as an HTML token (eg: "`"\"), or as a plain name (eg: "`"BOLD"`"). For example, here is a title format specification for three columns, where the first column title should be bold italic, the second italic, and the third italic in a smaller font: ``` -tf='BOLD,I;I;,I' ``` - **-d(ata)\_f(formats)**=*fmt1*;*fmt2*;...;*fmtN* The same as **-title\_formats** but applies to the column data. - **-url(s)=*****col1*****=*****url1*****,*****col2*****=*****url2*****,...** Define a mapping from column names, or indexes, to URLs to be inserted as \ around the values for the named columns. Each *colN* is a column name or index, and each *urlN* is a string representing the URL to be inserted for the given column. The URL text may contain these substitution strings: **%K** - will be substituted with the current column name (or *key*). **%V** - will be substituted with the current column value. Multiple **-url** options may be given, if desired, rather than creating one long argument for a single **-url**. For example: ``` showtable -d: -f1,6 -titles=Login,Homedir \ -url='Login=mailto:%V' \ -url='HomeDir=file:%V' \ /etc/passwd ``` ### Other options - **-help** Display some help to the user and quit. ### Boxed Input If the input type is *box*, then vertical and horizontal box characters are removed from the input stream, and blanks surrounding the vertical box characters are removed. The vertical box characters (column separaters) are "`"|"`" or "`":"`". The The horizontal box characters are "`"+"`" and "`"-"`". Morever, data wrapped within a column is recognized and parsed as one column value, by recognizing the presence of a *wrapping prefix* or *wrapping suffix* character. Currently, the wrapping prefix character is "\<", and the wrapping suffix character is "\>". An example of data wrapped within a column is given here. The table below has just two *logical* rows of data; with both rows having data wrapped into multiple *physical* rows. ``` +---------+---------+---------+ | Col 1 | Col 2 | Col 3 | +---------+---------+---------+ | This is>| Another>| Row 1,3>| |< a cont>|< value. || || || Item2-2 | Item2-3 | +---------+---------+---------+ ``` ### List Format When using the **-list** or **-input=list** options, either, or both, the input and output may be in a "list" format, which is implemented using the following syntax: ``` r1c1_name: r1c1_value r1c2_name: r1c2_value ... r1cN_name: r1cN_value r2c1_name: r2c1_value r2c2_name: r2c2_value : r2c2_value_continued ... r2cN_name: r2cN_value rMc1_name: rMc1_value rMc2_name: rMc2_value ... rMcN_name: rMcN_value ``` Each *row* of data consists of one or more *columns*, and ends with a blank line. Each *column* consists of a *column name*, followed by a colon ":", followed by an optional, single space or tab, followed by the *column value*, on the same line. Continuation lines of the previous column value consist of one or more space or tab characters, a colon ":", one optional, single space or tab, followed by the continuation value. In the example above, The second column value of the second row was continued. ### HTML Input with HTML Output When using **-html** on data already containing HTML-formatted text, the **-noescape** option should be used. By default, all input text is assumed *not* to be HTML-formatted, and is escaped allowing embedded "\<", "\>" characters, if any, to be displayed correctly. ## DEPENDENCIES - **Data::ShowTable** module Performs the actual output formatting. ## AUTHOR Alan K. Stebbens *aks@stebbens.org* ## BUGS - • Currently, the box formatting characters are not configurable: '+' for the corners; '-' and '\|' for the tops and sides, respectively. In an ideal world, these things would be configurable. - • The continuation prefix and suffix characters, '\<' and '\>', respectively, are also not configurable: - • When reading *table* input, any data ending with "\>" will be considered to be continued by the next row of data. To avoid this, use **-input=simple**. - • When selecting noncontiguous fields (ie: **-f1,4**\>) without field names, the default field names will be consecutively numbered from 1, which is counter-intuitive to the original selection. To avoid this, name the fields using the **-title=...** option.