NAME

       rtbl_create,   rtbl_destroy,   rtbl_set_flags,   rtbl_get_flags,   rtbl_set_prefix,   rtbl_set_separator,
       rtbl_set_column_prefix,     rtbl_set_column_affix_by_id,     rtbl_add_column,      rtbl_add_column_by_id,
       rtbl_add_column_entry,  rtbl_add_column_entry_by_id,  rtbl_new_row,  rtbl_format  — format data in simple
       tables

LIBRARY

       The roken library (libroken, -lroken)

SYNOPSIS

       #include <rtbl.h>

       int
       rtbl_add_column(rtbl_t table, const char *column_name, unsigned int flags);

       int
       rtbl_add_column_by_id(rtbl_t   table,   unsigned    int    column_id,    const    char    *column_header,
           unsigned int flags);

       int
       rtbl_add_column_entry(rtbl_t table, const char *column_name, const char *cell_entry);

       int
       rtbl_add_column_entry_by_id(rtbl_t table, unsigned int column_id, const char *cell_entry);

       rtbl_t
       rtbl_create(void);

       void
       rtbl_destroy(rtbl_t table);

       int
       rtbl_new_row(rtbl_t table);

       int
       rtbl_set_column_affix_by_id(rtbl_t    table,    unsigned    int   column_id,   const,   char,   *prefix",
           const char *suffix);

       int
       rtbl_set_column_prefix(rtbl_t table, const char *column_name, const char *prefix);

       unsigned int
       rtbl_get_flags(rtbl_t table);

       void
       rtbl_set_flags(rtbl_t table, unsigned int flags);

       int
       rtbl_set_prefix(rtbl_t table, const char *prefix);

       int
       rtbl_set_separator(rtbl_t table, const char *separator);

       int
       rtbl_format(rtbl_t table, FILE, *file");

DESCRIPTION

       This set of functions assemble a simple table consisting of rows and columns, 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 rtbl_create() and destroyed with rtbl_destroy().

       Global flags on the table are set with rtbl_set_flags and retrieved with rtbl_get_flags.  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
       rtbl_add_column_by_id(),  column_id  is  any  number of your choice (it's used only to identify columns),
       column_header is the header to print at the top of the column, and  flags  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 rtbl_add_column(), but this is less  flexible  (you
       need unique header names), and is considered deprecated.

       To  add  data  to a column you use rtbl_add_column_entry_by_id(), where the column_id is the same as when
       the column was added (adding data to a non-existent column is  undefined),  and  cell_entry  is  whatever
       string  you  wish  to  include  in  that  cell.  It  should not include newlines.  For columns added with
       rtbl_add_column() you must use rtbl_add_column_entry() instead.

       rtbl_new_row() 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   rtbl_set_column_affix_by_id;
       rtbl_set_column_prefix allows setting the prefix only by column name. In addition to this, columns may be
       separated by a string set with rtbl_set_separator (by default columns are not seprated by anything).

       The finished table is printed to file with rtbl_format.

EXAMPLES

       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                                          RTBL(3)