.TH sorttable "" "" "/rdb Command"
.PC "Sort a table by one or more columns"
\fBsorttable [\fIsort options\fB] [\fIcolumnname ...\fB] < \fItableorlist\fR
.PP
.II "table^sort"
The command
.B sorttable
uses the COHERENT command
.B sort
to sort
.IR tableorlist .
Unlike
.BR sort ,
it knows about table head lines and column names.
.PP
With
.B sorttable ,
you use the column names rather than column numbers, as in
.BR sort .
.B sorttable
also tells
.B sort
to use tabs as field separators, instead of white space
(i.e., blanks and tabs).
.PP
.B sorttable
completely sorts by the first column you name.
If there are any duplicate values in that column, it goes
to the second column and sort on those values.
It continues across the named columns until it either finds
a column that consists of unique values, or it runs out of columns.
For example, if you sort a ledger on columns
.B Account
and
.BR Date ,
.B sorttable
sorts the entire table on
column
.BR Account ,
and sorts by
.B Date
within each account.
.PP
If no columns are named,
.B sorttable
sorts
.I tableorlist
by all of its columns from left to right.
.SH Options
.B sorttable
passes all the options you give it to
.BR sort .
See the entry for
.B sort
in the COHERENT manual's Lexicon for details on this command's options.
.SH Example
Consider table
.BR inventory ,
which is structured as follows:
.DM
Item#   Amount   Cost    Value  Description   
------- ------- ------- ------- ---------------
      1       3    5.00   15.00 rubber gloves  
      2     100    0.50   50.00 test tubes     
      3       5    8.00   40.00 clamps         
      4      23    1.98   45.54 plates         
      5      99    2.45  242.55 cleaning cloth 
      6      89   14.75 1312.75 bunsen burners 
      7       5  175.00  875.00 scales         
.DE
.PP
To see
.B inventory
sorted with the highest
.B Cost
items on top, type:
.DM
	sorttable -n -r Cost < inventory
.DE
.PP
This produces:
.DM
Item#   Amount   Cost    Value  Description   
------- ------- ------- ------- ---------------
      7       5  175.00  875.00 scales         
      6      89   14.75 1312.75 bunsen burners 
      3       5    8.00   40.00 clamps         
      1       3    5.00   15.00 rubber gloves  
      5      99    2.45  242.55 cleaning cloth 
      4      23    1.98   45.54 plates         
      2     100    0.50   50.00 test tubes     
.DE
.PP
Note that
.B Cost
is in reverse order (the
.B \-r
option) and that it was treated as a number (\fB\-n\fR option)
instead of a character string.
.PP
If you use
.B sorttable
frequently, you should carefully study the
COHERENT Lexicon entry for
.BR sort .
For example, you can control which columns
.B sorttable
sort on.
If you name several columns,
.B sort
sees each column's numbers proceeded by a `+'.
The `+' means ``start sorting on this column'', the hyphen `-' means
``stop on the next column''.
To see this, use the
.B \-D
(debug) option for
.B sorttable.
(By the way, it is because
.B sort
has a
.B \-d
option that we use a capital
.B \-D
for the debug option for the
.B /rdb
commands).
For example, typing
.DM
	sorttable -D Cost Description < inventory
.DE
.PP
yields:
.DM
Item    Onhand   Cost    Value  Description   
------- ------- ------- ------- ---------------
sorttable: command executed: sort -t'   '   +2 -3 +4 -5 
2       100     1       100     test tubes
4       23      2       51      plates
5       99      3       297     cleaning cloth
1       3       5       15      rubber gloves
3       5       8       40      clamps
6       89      18      1602    bunsen burners
7       5       175     875     scales
.DE
.PP
The line beginning with
.B sort
is the line passed to COHERENT.
Note the
.BR +1 ,
.BR \-2 ,
and so on.
That tells
.B sort
to sort on columns 2 and 4 (where the first column is 0).
Thus,
.B sorttable
correctly turns the column names you type into a
.B sort
command by looking up the column names in the table head line and
converting them to column numbers for the COHERENT command
.BR sort .
.PP
People are often confused by
.B sort
because it does not behave the way one would expect.
Study its entry in the COHERENT Lexicon.
.SH "See Also"
COHERENT Lexicon:
.B
sort
.R