DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

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 for-
       matted listing, with exact formatting depending upon the options.  The
       input stream, file or "STDIN" by default should consist of data sepa-
       rated 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 out-
       put.

       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.

       -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 ta-
                 ble-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 for-
                 matted 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 nam-
                 ing 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 exist-
                 ing 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_for-
                 mats (or just -tf) can be given multiple times, for each col-
                 umn, 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)=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 col-
                 umns.  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 sepa-
       raters) 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 wrap-
       ping 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 |
               +---------+---------+---------+

       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 ":", fol-
       lowed 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@sgi.com


BUGS

       o    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.

       o    The continuation prefix and suffix characters, '<' and '>',
            respectively, are also not configurable:

       o    When reading table input, any data ending with ">" will be consid-
            ered to be continued by the next row of data.  To avoid this, use
            -input=simple.

       o    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.

perl v5.8.8                       1997-02-25                      SHOWTABLE(1)

Man(1) output converted with man2html