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
