showtable(1)
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 deter
mine the format of the output.
Options affecting input
- -break=str
- Set the inter-column break string to "str". The
default is a tab (""""). 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 wrap
ping 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 deter
mined 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 exam
ple: 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 multi ple times, for each column, or formats for mul
tiple 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 specifica
tion 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)=ccooll11=uurrll11,ccooll22=uurrll22,...
- 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.
- 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. Cur rently, 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
+---------+---------+---------+- 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, fol
lowed 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 continua
tion 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@sgi.com
BUGS
- · Currently, the box formatting characters are not con
- figurable: '+' 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-intu
itive to the original selection. To avoid this, name
the fields using the -title=... option.