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.
- -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.
- -dstr
- 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
ShowTable for more details.
- -si(mple)
- Use a simple table format, without any wrapping of column
values. See ShowTable for more details.
- -l(ist)
- Use a list style format. See ShowTable for more
details.
- -b(ox)
- 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.
- -fn1[,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:
<TABLE BORDER=0 CELLSPACING=2 CELLPADDING=4>
The default table attributes are:
<TABLE BORDER=1 CELLSPACING=1 CELLPADDING=1>
- -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:
""\<BOLD\">"), 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;<FONT SIZE=-2>,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 <A HREF's> 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.
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:
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.
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@sgi.com
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.