source: heimdal/trunk/lib/roken/rtbl.cat3

Last change on this file was 1, checked in by Paul Smedley, 10 years ago

Initial commit of Heimdal 1.5.3
File size: 8.0 KB
Line 
1
2RTBL(3) BSD Library Functions Manual RTBL(3)
3
4NNAAMMEE
5 rrttbbll__ccrreeaattee, rrttbbll__ddeessttrrooyy, rrttbbll__sseett__ffllaaggss, rrttbbll__ggeett__ffllaaggss,
6 rrttbbll__sseett__pprreeffiixx, rrttbbll__sseett__sseeppaarraattoorr, rrttbbll__sseett__ccoolluummnn__pprreeffiixx,
7 rrttbbll__sseett__ccoolluummnn__aaffffiixx__bbyy__iidd, rrttbbll__aadddd__ccoolluummnn, rrttbbll__aadddd__ccoolluummnn__bbyy__iidd,
8 rrttbbll__aadddd__ccoolluummnn__eennttrryy, rrttbbll__aadddd__ccoolluummnn__eennttrryy__bbyy__iidd, rrttbbll__nneeww__rrooww,
9 rrttbbll__ffoorrmmaatt -- format data in simple tables
10
11LLIIBBRRAARRYY
12 The roken library (libroken, -lroken)
13
14SSYYNNOOPPSSIISS
15 ##iinncclluuddee <<rrttbbll..hh>>
16
17 _i_n_t
18 rrttbbll__aadddd__ccoolluummnn(_r_t_b_l___t _t_a_b_l_e, _c_o_n_s_t _c_h_a_r _*_c_o_l_u_m_n___n_a_m_e,
19 _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s);
20
21 _i_n_t
22 rrttbbll__aadddd__ccoolluummnn__bbyy__iidd(_r_t_b_l___t _t_a_b_l_e, _u_n_s_i_g_n_e_d _i_n_t _c_o_l_u_m_n___i_d,
23 _c_o_n_s_t _c_h_a_r _*_c_o_l_u_m_n___h_e_a_d_e_r, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s);
24
25 _i_n_t
26 rrttbbll__aadddd__ccoolluummnn__eennttrryy(_r_t_b_l___t _t_a_b_l_e, _c_o_n_s_t _c_h_a_r _*_c_o_l_u_m_n___n_a_m_e,
27 _c_o_n_s_t _c_h_a_r _*_c_e_l_l___e_n_t_r_y);
28
29 _i_n_t
30 rrttbbll__aadddd__ccoolluummnn__eennttrryy__bbyy__iidd(_r_t_b_l___t _t_a_b_l_e, _u_n_s_i_g_n_e_d _i_n_t _c_o_l_u_m_n___i_d,
31 _c_o_n_s_t _c_h_a_r _*_c_e_l_l___e_n_t_r_y);
32
33 _r_t_b_l___t
34 rrttbbll__ccrreeaattee(_v_o_i_d);
35
36 _v_o_i_d
37 rrttbbll__ddeessttrrooyy(_r_t_b_l___t _t_a_b_l_e);
38
39 _i_n_t
40 rrttbbll__nneeww__rrooww(_r_t_b_l___t _t_a_b_l_e);
41
42 _i_n_t
43 rrttbbll__sseett__ccoolluummnn__aaffffiixx__bbyy__iidd(_r_t_b_l___t _t_a_b_l_e, _u_n_s_i_g_n_e_d _i_n_t _c_o_l_u_m_n___i_d, _c_o_n_s_t,
44 _c_h_a_r, _*_p_r_e_f_i_x_", _c_o_n_s_t _c_h_a_r _*_s_u_f_f_i_x);
45
46 _i_n_t
47 rrttbbll__sseett__ccoolluummnn__pprreeffiixx(_r_t_b_l___t _t_a_b_l_e, _c_o_n_s_t _c_h_a_r _*_c_o_l_u_m_n___n_a_m_e,
48 _c_o_n_s_t _c_h_a_r _*_p_r_e_f_i_x);
49
50 _u_n_s_i_g_n_e_d _i_n_t
51 rrttbbll__ggeett__ffllaaggss(_r_t_b_l___t _t_a_b_l_e);
52
53 _v_o_i_d
54 rrttbbll__sseett__ffllaaggss(_r_t_b_l___t _t_a_b_l_e, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s);
55
56 _i_n_t
57 rrttbbll__sseett__pprreeffiixx(_r_t_b_l___t _t_a_b_l_e, _c_o_n_s_t _c_h_a_r _*_p_r_e_f_i_x);
58
59 _i_n_t
60 rrttbbll__sseett__sseeppaarraattoorr(_r_t_b_l___t _t_a_b_l_e, _c_o_n_s_t _c_h_a_r _*_s_e_p_a_r_a_t_o_r);
61
62 _i_n_t
63 rrttbbll__ffoorrmmaatt(_r_t_b_l___t _t_a_b_l_e, _F_I_L_E, _*_f_i_l_e_");
64
65DDEESSCCRRIIPPTTIIOONN
66 This set of functions assemble a simple table consisting of rows and col-
67 umns, allowing it to be printed with certain options. Typical use would
68 be output from tools such as ls(1) or netstat(1), where you have a fixed
69 number of columns, but don't know the column widths before hand.
70
71 A table is created with rrttbbll__ccrreeaattee() and destroyed with rrttbbll__ddeessttrrooyy().
72
73 Global flags on the table are set with _r_t_b_l___s_e_t___f_l_a_g_s and retrieved with
74 _r_t_b_l___g_e_t___f_l_a_g_s. At present the only defined flag is
75 RTBL_HEADER_STYLE_NONE which suppresses printing the header.
76
77 Before adding data to the table, one or more columns need to be created.
78 This would normally be done with rrttbbll__aadddd__ccoolluummnn__bbyy__iidd(), _c_o_l_u_m_n___i_d is
79 any number of your choice (it's used only to identify columns),
80 _c_o_l_u_m_n___h_e_a_d_e_r is the header to print at the top of the column, and _f_l_a_g_s
81 are flags specific to this column. Currently the only defined flag is
82 RTBL_ALIGN_RIGHT, aligning column entries to the right. Columns are
83 printed in the order they are added.
84
85 There's also a way to add columns by column name with rrttbbll__aadddd__ccoolluummnn(),
86 but this is less flexible (you need unique header names), and is consid-
87 ered deprecated.
88
89 To add data to a column you use rrttbbll__aadddd__ccoolluummnn__eennttrryy__bbyy__iidd(), where the
90 _c_o_l_u_m_n___i_d is the same as when the column was added (adding data to a non-
91 existent column is undefined), and _c_e_l_l___e_n_t_r_y is whatever string you wish
92 to include in that cell. It should not include newlines. For columns
93 added with rrttbbll__aadddd__ccoolluummnn() you must use rrttbbll__aadddd__ccoolluummnn__eennttrryy()
94 instead.
95
96 rrttbbll__nneeww__rrooww() fills all columns with blank entries until they all have
97 the same number of rows.
98
99 Each column can have a separate prefix and suffix, set with
100 _r_t_b_l___s_e_t___c_o_l_u_m_n___a_f_f_i_x___b_y___i_d; _r_t_b_l___s_e_t___c_o_l_u_m_n___p_r_e_f_i_x allows setting the
101 prefix only by column name. In addition to this, columns may be separated
102 by a string set with _r_t_b_l___s_e_t___s_e_p_a_r_a_t_o_r (by default columns are not
103 seprated by anything).
104
105 The finished table is printed to _f_i_l_e with _r_t_b_l___f_o_r_m_a_t.
106
107EEXXAAMMPPLLEESS
108 This program:
109
110 #include <stdio.h>
111 #include <rtbl.h>
112 int
113 main(int argc, char **argv)
114 {
115 rtbl_t table;
116 table = rtbl_create();
117 rtbl_set_separator(table, " ");
118 rtbl_add_column_by_id(table, 0, "Column A", 0);
119 rtbl_add_column_by_id(table, 1, "Column B", RTBL_ALIGN_RIGHT);
120 rtbl_add_column_by_id(table, 2, "Column C", 0);
121 rtbl_add_column_entry_by_id(table, 0, "A-1");
122 rtbl_add_column_entry_by_id(table, 0, "A-2");
123 rtbl_add_column_entry_by_id(table, 0, "A-3");
124 rtbl_add_column_entry_by_id(table, 1, "B-1");
125 rtbl_add_column_entry_by_id(table, 2, "C-1");
126 rtbl_add_column_entry_by_id(table, 2, "C-2");
127 rtbl_add_column_entry_by_id(table, 1, "B-2");
128 rtbl_add_column_entry_by_id(table, 1, "B-3");
129 rtbl_add_column_entry_by_id(table, 2, "C-3");
130 rtbl_add_column_entry_by_id(table, 0, "A-4");
131 rtbl_new_row(table);
132 rtbl_add_column_entry_by_id(table, 1, "B-4");
133 rtbl_new_row(table);
134 rtbl_add_column_entry_by_id(table, 2, "C-4");
135 rtbl_new_row(table);
136 rtbl_format(table, stdout);
137 rtbl_destroy(table);
138 return 0;
139 }
140
141 will output the following:
142
143 Column A Column B Column C
144 A-1 B-1 C-1
145 A-2 B-2 C-2
146 A-3 B-3 C-3
147 A-4
148 B-4
149 C-4
150
151HEIMDAL June 26, 2004 HEIMDAL
Note: See TracBrowser for help on using the repository browser.