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