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.
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.
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.
-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.
-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.
Use a ``boxed'' style table. See ShowTable for more details.
-ht(ml)
Use HTML-formating. See 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.
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:
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:
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:
``\<BOLD\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:
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. |<is also>|
|<inued >| |<long. |
|<value. | | |
|This is >| Item2-2 | Item2-3 |
+---------+---------+---------+
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:
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.
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.
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.