1TBL(3) BSD Library Functions Manual TBL(3)
2
4 tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, tbl_free — roff ta‐
5 ble parser library for mandoc
6
8 #include <mandoc.h>
9 #include <libmandoc.h>
10 #include <libroff.h>
11 struct tbl_node *
13 tbl_alloc(int pos, int line, struct mparse *parse);
14 enum rofferr
16 tbl_read(struct tbl_node *tbl, int ln, const char *p, int offs);
17 void
19 tbl_restart(int line, int pos, struct tbl_node *tbl);
20 const struct tbl_span *
22 tbl_span(struct tbl_node *tbl);
23 void
25 tbl_end(struct tbl_node **tblp);
26 void
28 tbl_free(struct tbl_node *tbl);
29
31 This library is tightly integrated into the mandoc(1) utility and not
32 designed for stand-alone use. The present manual is intended as a refer‐
33 ence for developers working on mandoc(1).
34 Data structures
36 Unless otherwise noted, all of the following data structures are defined
37 in <mandoc.h> and are deleted in tbl_free().
38 struct tbl_node
40 This structure describes a complete table. It is defined in
41 <libroff.h>, created in tbl_alloc(), and stored in the members
42 first_tbl, last_tbl, and tbl of struct roff [roff.c].
43 The first_span, current_span, last_span, and next members may be
45 NULL. The first_row and last_row members may be NULL, but if
46 there is a span, the function tbl_layout() guarantees that these
47 pointers are not NULL. The function tbl_alloc() guarantees that
48 the parse member is not NULL.
49 struct tbl_opts
51 This structure describes the options of one table. It is used as
52 a substructure of struct tbl_node and thus created and deleted
53 together with it. It is filled in tbl_options().
54 struct tbl_row
56 This structure describes one layout line in a table by maintain‐
57 ing a list of all the cells in that line. It is allocated and
58 filled in row() [tbl_layout.c] and referenced from the layout
59 member of struct tbl_node.
60 The next member may be NULL. The function tbl_layout() guaran‐
62 tees that the first and last members are not NULL.
63 struct tbl_cell
65 This structure describes one layout cell in a table, in particu‐
66 lar its alignment, membership in spans, and usage for lines. It
67 is allocated and filled in cell_alloc() [tbl_layout.c] and refer‐
68 enced from the first and last members of struct tbl_row.
69 The next member may be NULL.
71 struct tbl_span
73 This structure describes one data line in a table by maintaining
74 a list of all data cells in that line or by specifying that it is
75 a horizontal line. It is allocated and filled in newspan()
76 [tbl_data.c] which is called from tbl_data() and referenced from
77 the first_span, current_span, and last_span members of struct
78 tbl_node, and from the span members of struct man_node and struct
79 mdoc_node from <man.h> and <mdoc.h>.
80 The first, last, prev, and next members may be NULL. The func‐
82 tion newspan() [tbl_data.c] guarantees that the opts and layout
83 members are not NULL.
84 struct tbl_dat
86 This structure describes one data cell in a table by specifying
87 whether it contains a line or data, whether it spans additional
88 layout cells, and by storing the data. It is allocated and
89 filled in tbl_data() and referenced from the first and last mem‐
90 bers of struct tbl_span.
91 The string and next members may be NULL. The function getdata()
93 guarantees that the layout member is not NULL.
94 Interface functions
96 The following functions are implemented in tbl.c, and all callers in
97 roff.c.
98 tbl_alloc()
100 Allocates, initializes, and returns a new struct tbl_node.
101 Called from roff_TS().
102 tbl_read()
104 Dispatches to tbl_option(), tbl_layout(), tbl_cdata(), and
105 tbl_data(), see below. Called from roff_parseln().
106 tbl_restart()
108 Resets the part member of struct tbl_node to TBL_PART_LAYOUT.
109 Called from roff_T_().
110 tbl_span()
112 On the first call, return the first struct tbl_span; for later
113 calls, return the next one or NULL. Called from roff_span().
114 tbl_end()
116 Flags the last span as TBL_SPAN_LAST and clears the pointer
117 passed as an argment. Called from roff_TE() and roff_endparse().
118 tbl_free()
120 Frees the specified struct tbl_node and all the tbl_row,
121 tbl_cell, tbl_span, and tbl_dat structures referenced from it.
122 Called from roff_free() and roff_reset().
123 Private functions
125 int tbl_options(struct tbl_node *tbl, int ln, const char *p)
126 Parses the options line into struct tbl_opts. Implemented in
127 tbl_opts.c, called from tbl_read().
128 int tbl_layout(struct tbl_node *tbl, int ln, const char *p)
130 Allocates and fills one struct tbl_row for each layout line and
131 one struct tbl_cell for each layout cell. Implemented in
132 tbl_layout.c, called from tbl_read().
133 int tbl_data(struct tbl_node *tbl, int ln, const char *p)
135 Allocates one struct tbl_span for each data line and calls
136 getdata() for each data cell. Implemented in tbl_data.c, called
137 from tbl_read().
138 int tbl_cdata(struct tbl_node *tbl, int ln, const char *p)
140 Continues parsing a data line: When finding ‘T}’, switches back
141 to TBL_PART_DATA mode and calls getdata() if there are more data
142 cells on the line. Otherwise, appends the data to the current
143 data cell. Implemented in tbl_data.c, called from tbl_read().
144 int getdata(struct tbl_node *tbl, struct tbl_span *dp, int ln,
146 const char *p, int *pos)
147 Parses one data cell into one struct tbl_dat. Implemented in
148 tbl_data.c, called from tbl_data() and tbl_cdata().
149
151 mandoc(1), mandoc(3), tbl(7)
152
154 The tbl library was written by Kristaps Dzonsons <kristaps@bsd.lv> with
155 contributions from Ingo Schwarze <schwarze@openbsd.org>.
156BSD June 20, 2019 BSD