Man page - rtbl_add_column(3)

Packages contains this manual

Manual

RTBL (3) Library Functions Manual RTBL (3)

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)