1TBL(3)                   BSD Library Functions Manual                   TBL(3)
2

NAME

4     tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, tbl_free — roff ta‐
5     ble parser library for mandoc
6

SYNOPSIS

8     #include <mandoc.h>
9     #include <libmandoc.h>
10     #include <libroff.h>
11
12     struct tbl_node *
13     tbl_alloc(int pos, int line, struct mparse *parse);
14
15     enum rofferr
16     tbl_read(struct tbl_node *tbl, int ln, const char *p, int offs);
17
18     void
19     tbl_restart(int line, int pos, struct tbl_node *tbl);
20
21     const struct tbl_span *
22     tbl_span(struct tbl_node *tbl);
23
24     void
25     tbl_end(struct tbl_node **tblp);
26
27     void
28     tbl_free(struct tbl_node *tbl);
29

DESCRIPTION

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
35   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
39     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
44             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
50     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
55     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
61             The next member may be NULL.  The function tbl_layout() guaran‐
62             tees that the first and last members are not NULL.
63
64     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
70             The next member may be NULL.
71
72     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
81             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
85     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
92             The string and next members may be NULL.  The function getdata()
93             guarantees that the layout member is not NULL.
94
95   Interface functions
96     The following functions are implemented in tbl.c, and all callers in
97     roff.c.
98
99     tbl_alloc()
100             Allocates, initializes, and returns a new struct tbl_node.
101             Called from roff_TS().
102
103     tbl_read()
104             Dispatches to tbl_option(), tbl_layout(), tbl_cdata(), and
105             tbl_data(), see below.  Called from roff_parseln().
106
107     tbl_restart()
108             Resets the part member of struct tbl_node to TBL_PART_LAYOUT.
109             Called from roff_T_().
110
111     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
115     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
119     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
124   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
129     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
134     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
139     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
145     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

SEE ALSO

151     mandoc(1), mandoc(3), tbl(7)
152

AUTHORS

154     The tbl library was written by Kristaps Dzonsons <kristaps@bsd.lv> with
155     contributions from Ingo Schwarze <schwarze@openbsd.org>.
156
157BSD                              June 20, 2019                             BSD
Impressum