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 <sys/types.h>
9     #include <tbl.h>
10     #include <tbl_parse.h>
11
12     struct tbl_node *
13     tbl_alloc(int pos, int line);
14
15     void
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 declared
37     in <tbl.h> and are deleted in tbl_free().
38
39     struct tbl_node
40             This structure describes a complete table.  It is declared in
41             <tbl_int.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.
48
49     struct tbl_opts
50             This structure describes the options of one table.  It is used as
51             a substructure of struct tbl_node and thus created and deleted
52             together with it.  It is filled in tbl_options().
53
54     struct tbl_row
55             This structure describes one layout line in a table by maintain‐
56             ing a list of all the cells in that line.  It is allocated and
57             filled in row() [tbl_layout.c] and referenced from the layout
58             member of struct tbl_node.
59
60             The next member may be NULL.  The function tbl_layout() guaran‐
61             tees that the first and last members are not NULL.
62
63     struct tbl_cell
64             This structure describes one layout cell in a table, in particu‐
65             lar its alignment, membership in spans, and usage for lines.  It
66             is allocated and filled in cell_alloc() [tbl_layout.c] and refer‐
67             enced from the first and last members of struct tbl_row.
68
69             The next member may be NULL.
70
71     struct tbl_span
72             This structure describes one data line in a table by maintaining
73             a list of all data cells in that line or by specifying that it is
74             a horizontal line.  It is allocated and filled in newspan()
75             [tbl_data.c] which is called from tbl_data() and referenced from
76             the first_span, current_span, and last_span members of struct
77             tbl_node, and from the span members of struct man_node and struct
78             mdoc_node from <man.h> and <mdoc.h>.
79
80             The first, last, prev, and next members may be NULL.  The func‐
81             tion newspan() [tbl_data.c] guarantees that the opts and layout
82             members are not NULL.
83
84     struct tbl_dat
85             This structure describes one data cell in a table by specifying
86             whether it contains a line or data, whether it spans additional
87             layout cells, and by storing the data.  It is allocated and
88             filled in tbl_data() and referenced from the first and last mem‐
89             bers of struct tbl_span.
90
91             The string and next members may be NULL.  The function getdata()
92             guarantees that the layout member is not NULL.
93
94   Interface functions
95     The following functions are implemented in tbl.c, and all callers are in
96     roff.c.
97
98     tbl_alloc()
99             Allocates, initializes, and returns a new struct tbl_node.
100             Called from roff_TS().
101
102     tbl_read()
103             Dispatches to tbl_option(), tbl_layout(), tbl_cdata(), and
104             tbl_data(), see below.  Called from roff_parseln().
105
106     tbl_restart()
107             Resets the part member of struct tbl_node to TBL_PART_LAYOUT.
108             Called from roff_T_().
109
110     tbl_span()
111             On the first call, return the first struct tbl_span; for later
112             calls, return the next one or NULL.  Called from roff_span().
113
114     tbl_end()
115             Flags the last span as TBL_SPAN_LAST and clears the pointer
116             passed as an argment.  Called from roff_TE() and roff_endparse().
117
118     tbl_free()
119             Frees the specified struct tbl_node and all the tbl_row,
120             tbl_cell, tbl_span, and tbl_dat structures referenced from it.
121             Called from roff_free() and roff_reset().
122
123   Private functions
124     The following functions are declared in <tbl_int.h>.
125
126     int tbl_options(struct tbl_node *tbl, int ln, const char *p)
127             Parses the options line into struct tbl_opts.  Implemented in
128             tbl_opts.c, called from tbl_read().
129
130     int tbl_layout(struct tbl_node *tbl, int ln, const char *p)
131             Allocates and fills one struct tbl_row for each layout line and
132             one struct tbl_cell for each layout cell.  Implemented in
133             tbl_layout.c, called from tbl_read().
134
135     int tbl_data(struct tbl_node *tbl, int ln, const char *p)
136             Allocates one struct tbl_span for each data line and calls
137             getdata() for each data cell.  Implemented in tbl_data.c, called
138             from tbl_read().
139
140     int tbl_cdata(struct tbl_node *tbl, int ln, const char *p)
141             Continues parsing a data line: When finding ‘T}’, switches back
142             to TBL_PART_DATA mode and calls getdata() if there are more data
143             cells on the line.  Otherwise, appends the data to the current
144             data cell.  Implemented in tbl_data.c, called from tbl_read().
145
146     int getdata(struct tbl_node *tbl, struct tbl_span *dp, int ln,
147             const char *p, int *pos)
148             Parses one data cell into one struct tbl_dat.  Implemented in
149             tbl_data.c, called from tbl_data() and tbl_cdata().
150

SEE ALSO

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

AUTHORS

155     The tbl library was written by Kristaps Dzonsons <kristaps@bsd.lv> with
156     contributions from Ingo Schwarze <schwarze@openbsd.org>.
157
158BSD                              May 10, 2020                              BSD
Impressum