RTBL(3)                  BSD Library Functions Manual                  RTBL(3)

[1mNAME[0m
     [1mrtbl_create[22m, [1mrtbl_destroy[22m, [1mrtbl_set_flags[22m, [1mrtbl_get_flags[22m,
     [1mrtbl_set_prefix[22m, [1mrtbl_set_separator[22m, [1mrtbl_set_column_prefix[22m,
     [1mrtbl_set_column_affix_by_id[22m, [1mrtbl_add_column[22m, [1mrtbl_add_column_by_id[22m,
     [1mrtbl_add_column_entry[22m, [1mrtbl_add_column_entry_by_id[22m, [1mrtbl_new_row[22m,
     [1mrtbl_format [22m-- format data in simple tables

[1mLIBRARY[0m
     The roken library (libroken, -lroken)

[1mSYNOPSIS[0m
     [1m#include <rtbl.h>[0m

     [4mint[0m
     [1mrtbl_add_column[22m([4mrtbl_t[24m [4mtable[24m, [4mconst[24m [4mchar[24m [4m*column_name[24m,
         [4munsigned[24m [4mint[24m [4mflags[24m);

     [4mint[0m
     [1mrtbl_add_column_by_id[22m([4mrtbl_t[24m [4mtable[24m, [4munsigned[24m [4mint[24m [4mcolumn_id[24m,
         [4mconst[24m [4mchar[24m [4m*column_header[24m, [4munsigned[24m [4mint[24m [4mflags[24m);

     [4mint[0m
     [1mrtbl_add_column_entry[22m([4mrtbl_t[24m [4mtable[24m, [4mconst[24m [4mchar[24m [4m*column_name[24m,
         [4mconst[24m [4mchar[24m [4m*cell_entry[24m);

     [4mint[0m
     [1mrtbl_add_column_entry_by_id[22m([4mrtbl_t[24m [4mtable[24m, [4munsigned[24m [4mint[24m [4mcolumn_id[24m,
         [4mconst[24m [4mchar[24m [4m*cell_entry[24m);

     [4mrtbl_t[0m
     [1mrtbl_create[22m([4mvoid[24m);

     [4mvoid[0m
     [1mrtbl_destroy[22m([4mrtbl_t[24m [4mtable[24m);

     [4mint[0m
     [1mrtbl_new_row[22m([4mrtbl_t[24m [4mtable[24m);

     [4mint[0m
     [1mrtbl_set_column_affix_by_id[22m([4mrtbl_t[24m [4mtable[24m, [4munsigned[24m [4mint[24m [4mcolumn_id[24m, [4mconst[24m,
         [4mchar[24m, [4m*prefix"[24m, [4mconst[24m [4mchar[24m [4m*suffix[24m);

     [4mint[0m
     [1mrtbl_set_column_prefix[22m([4mrtbl_t[24m [4mtable[24m, [4mconst[24m [4mchar[24m [4m*column_name[24m,
         [4mconst[24m [4mchar[24m [4m*prefix[24m);

     [4munsigned[24m [4mint[0m
     [1mrtbl_get_flags[22m([4mrtbl_t[24m [4mtable[24m);

     [4mvoid[0m
     [1mrtbl_set_flags[22m([4mrtbl_t[24m [4mtable[24m, [4munsigned[24m [4mint[24m [4mflags[24m);

     [4mint[0m
     [1mrtbl_set_prefix[22m([4mrtbl_t[24m [4mtable[24m, [4mconst[24m [4mchar[24m [4m*prefix[24m);

     [4mint[0m
     [1mrtbl_set_separator[22m([4mrtbl_t[24m [4mtable[24m, [4mconst[24m [4mchar[24m [4m*separator[24m);

     [4mint[0m
     [1mrtbl_format[22m([4mrtbl_t[24m [4mtable[24m, [4mFILE[24m, [4m*file"[24m);

[1mDESCRIPTION[0m
     This set of functions assemble a simple table consisting of rows and col-
     umns, allowing it to be printed with certain options. Typical use would
     be output from tools such as ls(1) or netstat(1), where you have a fixed
     number of columns, but don't know the column widths before hand.

     A table is created with [1mrtbl_create[22m() and destroyed with [1mrtbl_destroy[22m().

     Global flags on the table are set with [4mrtbl_set_flags[24m and retrieved with
     [4mrtbl_get_flags[24m.  At present the only defined flag is
     RTBL_HEADER_STYLE_NONE which suppresses printing the header.

     Before adding data to the table, one or more columns need to be created.
     This would normally be done with [1mrtbl_add_column_by_id[22m(), [4mcolumn_id[24m is
     any number of your choice (it's used only to identify columns),
     [4mcolumn_header[24m is the header to print at the top of the column, and [4mflags[0m
     are flags specific to this column. Currently the only defined flag is
     RTBL_ALIGN_RIGHT, aligning column entries to the right. Columns are
     printed in the order they are added.

     There's also a way to add columns by column name with [1mrtbl_add_column[22m(),
     but this is less flexible (you need unique header names), and is consid-
     ered deprecated.

     To add data to a column you use [1mrtbl_add_column_entry_by_id[22m(), where the
     [4mcolumn_id[24m is the same as when the column was added (adding data to a non-
     existent column is undefined), and [4mcell_entry[24m is whatever string you wish
     to include in that cell. It should not include newlines.  For columns
     added with [1mrtbl_add_column[22m() you must use [1mrtbl_add_column_entry[22m() in-
     stead.

     [1mrtbl_new_row[22m() fills all columns with blank entries until they all have
     the same number of rows.

     Each column can have a separate prefix and suffix, set with
     [4mrtbl_set_column_affix_by_id[24m; [4mrtbl_set_column_prefix[24m allows setting the
     prefix only by column name. In addition to this, columns may be separated
     by a string set with [4mrtbl_set_separator[24m (by default columns are not
     seprated by anything).

     The finished table is printed to [4mfile[24m with [4mrtbl_format[24m.

[1mEXAMPLES[0m
     This program:

         #include <stdio.h>
         #include <rtbl.h>
         int
         main(int argc, char **argv)
         {
             rtbl_t table;
             table = rtbl_create();
             rtbl_set_separator(table, "  ");
             rtbl_add_column_by_id(table, 0, "Column A", 0);
             rtbl_add_column_by_id(table, 1, "Column B", RTBL_ALIGN_RIGHT);
             rtbl_add_column_by_id(table, 2, "Column C", 0);
             rtbl_add_column_entry_by_id(table, 0, "A-1");
             rtbl_add_column_entry_by_id(table, 0, "A-2");
             rtbl_add_column_entry_by_id(table, 0, "A-3");
             rtbl_add_column_entry_by_id(table, 1, "B-1");
             rtbl_add_column_entry_by_id(table, 2, "C-1");
             rtbl_add_column_entry_by_id(table, 2, "C-2");
             rtbl_add_column_entry_by_id(table, 1, "B-2");
             rtbl_add_column_entry_by_id(table, 1, "B-3");
             rtbl_add_column_entry_by_id(table, 2, "C-3");
             rtbl_add_column_entry_by_id(table, 0, "A-4");
             rtbl_new_row(table);
             rtbl_add_column_entry_by_id(table, 1, "B-4");
             rtbl_new_row(table);
             rtbl_add_column_entry_by_id(table, 2, "C-4");
             rtbl_new_row(table);
             rtbl_format(table, stdout);
             rtbl_destroy(table);
             return 0;
         }

     will output the following:

         Column A  Column B  Column C
         A-1            B-1  C-1
         A-2            B-2  C-2
         A-3            B-3  C-3
         A-4
                        B-4
                             C-4

HEIMDAL                          June 26, 2004                         HEIMDAL
