| Current File : //usr/local/share/man/man1/showtable.1 |
.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SHOWTABLE 1"
.TH SHOWTABLE 1 "2013-10-25" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
showtable \- Show data in nicely formatted columns
.SH "USAGE"
.IX Header "USAGE"
\&\fBshowtable\fR [\-\fIoptions\fR] [\fIfile\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBShowtable\fR reads an input data stream and displays it in a nicely
formatted listing, with exact formatting depending upon the options.
The input stream, \fIfile\fR or \f(CW\*(C`STDIN\*(C'\fR by default should consist of data
separated by tabs or the defined \fIseparator\fR character (see \fB\-d\fR).
.PP
The actual output formatting is peformed by the \fBShowTable\fR module.
.SH "OPTIONS"
.IX Header "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.
.SS "\fBOptions affecting input\fP"
.IX Subsection "Options affecting input"
.IP "\fB\-break=\fR\fIstr\fR" 10
.IX Item "-break=str"
Set the inter-column break string to "\fIstr\fR\*(L". The default
is a tab (\*(R"\f(CW\*(C`\et\*(C'\fR"). If \fB\-strip\fR is also given, blanks surrounding
the break string will also be ignored.
.IP "\fB\-d\fR\fIstr\fR" 10
.IX Item "-dstr"
This is the same as \f(CW\*(C`\-break=\*(C'\fR\fIstr\fR.
.IP "\fB\-nod(ashes)\fR" 10
.IX Item "-nod(ashes)"
Do not ignore lines of separators, such as dashes, equal
signs, or underlines. If \fB\-nodashes\fR is given, and these lines do occur
in the stream, they will be treated as normal data.
.IP "\fB\-ti(tles)[=\fR\fI\s-1NN\s0\fR\fB]\fR" 10
.IX Item "-ti(tles)[=NN]"
Treat the first \fI\s-1NN\s0\fR rows of data as column titles; multiple
words in the column titles may wrap vertically. If \fI\s-1NN\s0\fR is
omitted, it defaults to 1. No \fB\-titles\fR option is the same
as \fB\-titles=0\fR.
.IP "\fB\-in(put)=\fR\fItype\fR" 10
.IX Item "-in(put)=type"
Set the input type as \fItype\fR, which can be one of: \fIbox\fR, \fIlist\fR, \fItable\fR,
or \fIsimple\fR. A \fIsimple\fR\-type table is the same as a \fItable\fR\-type,
but no wrapping characters are recognized.
.IP "\fB\-s(trip)\fR" 10
.IX Item "-s(trip)"
Strip blanks from around the column values.
.IP "\fB\-nos(trip)\fR" 10
.IX Item "-nos(trip)"
Do not strip blanks from the input. Useful if there is formatted or aligned
data within a boxed table.
.SS "\fBOptions affecting output\fP"
.IX Subsection "Options affecting output"
.IP "\fB\-t(able)\fR" 10
.IX Item "-t(able)"
Use a \fItable\fR format for output, with wrapping of column values longer
than the given or determined column widths. See Data::ShowTable for
more details.
.IP "\fB\-si(mple)\fR" 10
.IX Item "-si(mple)"
Use a simple table format, without any wrapping of column values.
See Data::ShowTable for more details.
.IP "\fB\-l(ist)\fR" 10
.IX Item "-l(ist)"
Use a list style format. See Data::ShowTable for more details.
.IP "\fB\-b(ox)\fR" 10
.IX Item "-b(ox)"
Use a \*(L"boxed\*(R" style table. See Data::ShowTable for more details.
.IP "\fB\-ht(ml)\fR" 10
.IX Item "-ht(ml)"
Use HTML-formating. See Data::ShowTable for more details.
.IP "\fB\-ti(tles)=\fR\fIname1\fR\fB,\fR\fIname2\fR\fB,...,\fR\fInameN\fR" 10
.IX Item "-ti(tles)=name1,name2,...,nameN"
Define the column names explicitly. This is useful for naming columns
of data from \f(CW\*(C`STDIN\*(C'\fR, when \fBshowtable\fR is being used as a filter. The
first column name, \fIname1\fR, cannot begin with a digit. This option
allows any column titles obtained from the input to be overridden.
.IP "\fB\-noh(eaders)\fR" 10
.IX Item "-noh(eaders)"
Do not output any headers on the tables; \fB\-titles=0\fR implies this option.
.IP "\fB\-f\fR\fIn1\fR[,\fIn2\fR, ..., \fInN\fR]" 10
.IX Item "-fn1[,n2, ..., nN]"
Select fields numbered \fIn1\fR, \fIn2\fR, etc., to display. Each \fInN\fR is a
field index, or a range of indexes in the form: \f(CW\*(C`N\*(C'\fR\-\f(CW\*(C`M\*(C'\fR 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
\&\f(CW\*(C`/etc/passwd\*(C'\fR file:
.Sp
.Vb 1
\& showtable \-d: \-f1,2\-5 /etc/passwd
.Ve
.IP "\fB\-fields\fR=\fIfname1\fR[,\fIfname2\fR, ..., \fIfnameN\fR]" 10
.IX Item "-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 \fB\-titles\fR option. The field
names given must match the existing field names \fIexactly\fR.
.Sp
Using the file \f(CW\*(C`/etc/passwd\*(C'\fR for another example: to show the same first two
fields, by name:
.Sp
.Vb 1
\& showtable \-d: \-titles=Login,UID \-fields=Login,UID /etc/passwd
.Ve
.IP "\fB\-w(idth)\fR=\fInum\fR" 10
.IX Item "-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.
.Sp
If \fB\-width\fR is not given, then for all output but \fB\-html\fR, the default
value is either "\f(CW\*(C`COLUMNS\*(C'\fR", if defined, or 80, if not. Whith \fB\-html\fR
mode, there is no default value for \fB\-width\fR; in other words, there is
no limit to the width.
.IP "\fB\-cw(idths)\fR=\fIw1\fR[,\fIw2\fR,...,\fIwN\fR]" 10
.IX Item "-cw(idths)=w1[,w2,...,wN]"
Set individual column widths to the specified values. Empty column
widths imply no maximum width. If the \fB\-width\fR option is also given,
then the \fB\-cwidth\fR column widths can also be given as fractions or
percentages.
.Sp
Example: To set the maximum width of the third column to 20 characters:
.Sp
.Vb 1
\& \-cw=,,20
.Ve
.SS "\fBHTML-only options\fP (the usage of which implies \fB\-html\fP)"
.IX Subsection "HTML-only options (the usage of which implies -html)"
.IP "\fB\-noe(scape)\fR" 10
.IX Item "-noe(scape)"
Do not perform \s-1HTML\s0 escape sequences on the data; this allows embedded
\&\s-1HTML\s0 text in the data to be displayed properly with the \fB\-html\fR option.
.IP "\fB\-attributes\fR='\fIattr1\fR \fIattr2\fR ...'" 10
.IX Item "-attributes='attr1 attr2 ...'"
Declare the table attributes, which are inserted into the \f(CW\*(C`TABLE\*(C'\fR
token. For example, the option:
.Sp
.Vb 1
\& \-attributes=\*(AqBORDER=0 CELLSPACING=2 CELLPADDING=4\*(Aq
.Ve
.Sp
would cause the following \s-1HTML:\s0
.Sp
.Vb 1
\& <TABLE BORDER=0 CELLSPACING=2 CELLPADDING=4>
.Ve
.Sp
The default table attributes are:
.Sp
.Vb 1
\& <TABLE BORDER=1 CELLSPACING=1 CELLPADDING=1>
.Ve
.IP "\fB\-t(itle)_f(ormats)\fR=\fIfmt1\fR;\fIfmt2\fR;...;\fIfmtN\fR" 10
.IX Item "-t(itle)_f(ormats)=fmt1;fmt2;...;fmtN"
Set the \s-1HTML\s0 formats for the column titles. The \fB\-title_formats\fR (or
just \fB\-tf\fR) can be given multiple times, for each column, or formats
for multiple columns can be given on the same option separated by
semi-colons "\f(CW\*(C`;\*(C'\fR".
.Sp
Each \fIfmtN\fR can itself be multiple \s-1HTML\s0 items, separated by commas.
Each \s-1HTML\s0 element can be given either as an \s-1HTML\s0 token (eg:
"\f(CW\*(C`\e<BOLD\e\*(C'\fR>\*(L"), or as a plain name (eg: \*(R"\f(CW\*(C`BOLD\*(C'\fR").
.Sp
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:
.Sp
.Vb 1
\& \-tf=\*(AqBOLD,I;I;<FONT SIZE=\-2>,I\*(Aq
.Ve
.IP "\fB\-d(ata)_f(formats)\fR=\fIfmt1\fR;\fIfmt2\fR;...;\fIfmtN\fR" 10
.IX Item "-d(ata)_f(formats)=fmt1;fmt2;...;fmtN"
The same as \fB\-title_formats\fR but applies to the column data.
.IP "\fB\-url(s)=\f(BIcol1\fB=\f(BIurl1\fB,\f(BIcol2\fB=\f(BIurl2\fB,...\fR" 10
.IX Item "-url(s)=col1=url1,col2=url2,..."
Define a mapping from column names, or indexes, to URLs to be inserted
as <A \s-1HREF\s0's> around the values for the named columns. Each \fIcolN\fR is
a column name or index, and each \fIurlN\fR is a string representing the
\&\s-1URL\s0 to be inserted for the given column.
.Sp
The \s-1URL\s0 text may contain these substitution strings:
.Sp
\&\fB\f(CB%K\fB\fR \- will be substituted with the current column name (or \fIkey\fR).
.Sp
\&\fB\f(CB%V\fB\fR \- will be substituted with the current column value.
.Sp
Multiple \fB\-url\fR options may be given, if desired, rather than
creating one long argument for a single \fB\-url\fR. For example:
.Sp
.Vb 4
\& showtable \-d: \-f1,6 \-titles=Login,Homedir \e
\& \-url=\*(AqLogin=mailto:%V\*(Aq \e
\& \-url=\*(AqHomeDir=file:%V\*(Aq \e
\& /etc/passwd
.Ve
.SS "\fBOther options\fP"
.IX Subsection "Other options"
.IP "\fB\-help\fR" 10
.IX Item "-help"
Display some help to the user and quit.
.SS "\fBBoxed Input\fP"
.IX Subsection "Boxed Input"
If the input type is \fIbox\fR, 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 "\f(CW\*(C`|\*(C'\fR\*(L" or \*(R"\f(CW\*(C`:\*(C'\fR\*(L". The The horizontal box characters are
\&\*(R"\f(CW\*(C`+\*(C'\fR\*(L" and \*(R"\f(CW\*(C`\-\*(C'\fR".
.PP
Morever, data wrapped within a column is recognized and parsed as one
column value, by recognizing the presence of a \fIwrapping prefix\fR or
\&\fIwrapping suffix\fR character. Currently, the wrapping prefix character
is \*(L"<\*(R", and the wrapping suffix character is \*(L">\*(R".
.PP
An example of data wrapped within a column is given here. The table
below has just two \fIlogical\fR rows of data; with both rows having data
wrapped into multiple \fIphysical\fR rows.
.PP
.Vb 9
\& +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
\& | 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 |
\& +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
.Ve
.SS "\fBList Format\fP"
.IX Subsection "List Format"
When using the \fB\-list\fR or \fB\-input=list\fR options, either, or both, the
input and output may be in a \*(L"list\*(R" format, which is implemented
using the following syntax:
.PP
.Vb 4
\& 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
.Ve
.PP
Each \fIrow\fR of data consists of one or more \fIcolumns\fR, and ends with
a blank line.
.PP
Each \fIcolumn\fR consists of a \fIcolumn name\fR, followed by a colon \*(L":\*(R",
followed by an optional, single space or tab, followed by the
\&\fIcolumn value\fR, on the same line.
.PP
Continuation lines of the previous column value consist of one or more
space or tab characters, a colon \*(L":\*(R", 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.
.SS "\fB\s-1HTML\s0 Input with \s-1HTML\s0 Output\fP"
.IX Subsection "HTML Input with HTML Output"
When using \fB\-html\fR on data already containing HTML-formatted text,
the \fB\-noescape\fR option should be used. By default, all input
text is assumed \fInot\fR to be HTML-formatted, and is escaped
allowing embedded \*(L"<\*(R", \*(L">\*(R" characters, if any, to be displayed
correctly.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "\fBData::ShowTable\fR module" 10
.IX Item "Data::ShowTable module"
Performs the actual output formatting.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alan K. Stebbens \fIaks@stebbens.org\fR
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 5
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.
.IP "\(bu" 5
The continuation prefix and suffix characters, '<' and '>',
respectively, are also not configurable:
.IP "\(bu" 5
When reading \fItable\fR input, any data ending with \*(L">\*(R" will
be considered to be continued by the next row of data. To avoid
this, use \fB\-input=simple\fR.
.IP "\(bu" 5
When selecting noncontiguous fields (ie: \fB\-f1,4\fR>) 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 \fB\-title=...\fR
option.