| blob | 1c0fc678b74c755aa2d3def8f903f30dab330500 |
1 .\" Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp
2 .\"
3 .\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd June 1, 2013
18 .Dt TBL 3
19 .Os
20 .Sh NAME
21 .Nm tbl_alloc ,
22 .Nm tbl_read ,
23 .Nm tbl_restart ,
24 .Nm tbl_span ,
25 .Nm tbl_end ,
26 .Nm tbl_free
27 .Nd roff table parser library for mandoc
28 .Sh SYNOPSIS
29 .In mandoc.h
30 .In libmandoc.h
31 .In libroff.h
32 .Ft struct tbl_node *
33 .Fo tbl_alloc
34 .Fa "int pos"
35 .Fa "int line"
36 .Fa "struct mparse *parse"
37 .Fc
38 .Ft enum rofferr
39 .Fo tbl_read
40 .Fa "struct tbl_node *tbl"
41 .Fa "int ln"
42 .Fa "const char *p"
43 .Fa "int offs"
44 .Fc
45 .Ft void
46 .Fo tbl_restart
47 .Fa "int line"
48 .Fa "int pos"
49 .Fa "struct tbl_node *tbl"
50 .Fc
51 .Ft const struct tbl_span *
52 .Fo tbl_span
53 .Fa "struct tbl_node *tbl"
54 .Fc
55 .Ft void
56 .Fo tbl_end
57 .Fa "struct tbl_node **tblp"
58 .Fc
59 .Ft void
60 .Fo tbl_free
61 .Fa "struct tbl_node *tbl"
62 .Fc
63 .Sh DESCRIPTION
64 This library is tightly integrated into the
65 .Xr mandoc 1
66 utility and not designed for stand-alone use.
67 The present manual is intended as a reference for developers working on
68 .Xr mandoc 1 .
69 .Ss Data structures
70 Unless otherwise noted, all of the following data structures are defined in
71 .In mandoc.h
72 and are deleted in
73 .Fn tbl_free .
74 .Bl -tag -width Ds
75 .It Vt struct tbl_node
76 This structure describes a complete table.
77 It is defined in
78 .In libroff.h ,
79 created in
80 .Fn tbl_alloc ,
81 and stored in the members
82 .Va first_tbl ,
83 .Va last_tbl ,
84 and
85 .Va tbl
86 of
87 .Vt struct roff Bq Pa roff.c .
88 .It Vt struct tbl_opts
89 This structure describes the options of one table.
90 It is used as a substructure of
91 .Vt struct tbl_node
92 and thus created and deleted together with it.
93 It is filled in
94 .Fn tbl_options .
95 .It Vt struct tbl_head
96 This structure describes one layout column in a table,
97 in particular the vertical line to its left.
98 It is allocated and filled in
99 .Fn cell_alloc Bq Pa tbl_layout.c
100 and referenced from the
101 .Va first_head
102 and
103 .Va last_head
104 members of
105 .Vt struct tbl_node .
106 .It Vt struct tbl_row
107 This structure describes one layout line in a table
108 by maintaining a list of all the cells in that line.
109 It is allocated and filled in
110 .Fn row Bq Pa tbl_layout.c
111 and referenced from the
112 .Va layout
113 member of
114 .Vt struct tbl_node .
115 .It Vt struct tbl_cell
116 This structure describes one layout cell in a table,
117 in particular its alignment, membership in spans, and
118 usage for lines.
119 It is allocated and filled in
120 .Fn cell_alloc Bq Pa tbl_layout.c
121 and referenced from the
122 .Va first
123 and
124 .Va last
125 members of
126 .Vt struct tbl_row .
127 .It Vt struct tbl_span
128 This structure describes one data line in a table
129 by maintaining a list of all data cells in that line
130 or by specifying that it is a horizontal line.
131 It is allocated and filled in
132 .Fn newspan Bq Pa tbl_data.c
133 which is called from
134 .Fn tbl_data
135 and referenced from the
136 .Va first_span ,
137 .Va current_span ,
138 and
139 .Va last_span
140 members of
141 .Vt struct tbl_node ,
142 and from the
143 .Va span
144 members of
145 .Vt struct man_node
146 and
147 .Vt struct mdoc_node
148 from
149 .In man.h
150 and
151 .In mdoc.h .
152 .It Vt struct tbl_dat
153 This structure describes one data cell in a table by specifying
154 whether it contains a line or data, whether it spans additional
155 layout cells, and by storing the data.
156 It is allocated and filled in
157 .Fn data
158 and referenced from the
159 .Va first
160 and
161 .Va last
162 members of
163 .Vt struct tbl_span .
164 .El
165 .Ss Interface functions
166 The following functions are implemented in
167 .Pa tbl.c ,
168 and all callers in
169 .Pa roff.c .
170 .Bl -tag -width Ds
171 .It Fn tbl_alloc
172 Allocates, initializes, and returns a new
173 .Vt struct tbl_node .
174 Called from
175 .Fn roff_TS .
176 .It Fn tbl_read
177 Dispatches to
178 .Fn tbl_option ,
179 .Fn tbl_layout ,
180 .Fn tbl_cdata ,
181 and
182 .Fn tbl_data ,
183 see below.
184 Called from
185 .Fn roff_parseln .
186 .It Fn tbl_restart
187 Resets the
188 .Va part
189 member of
190 .Vt struct tbl_node
191 to
192 .Dv TBL_PART_LAYOUT .
193 Called from
194 .Fn roff_T_ .
195 .It Fn tbl_span
196 On the first call, return the first
197 .Vt struct tbl_span ;
198 for later calls, return the next one or
199 .Dv NULL .
200 Called from
201 .Fn roff_span .
202 .It Fn tbl_end
203 Flags the last span as
204 .Dv TBL_SPAN_LAST
205 and clears the pointer passed as an argment.
206 Called from
207 .Fn roff_TE
208 and
209 .Fn roff_endparse .
210 .It Fn tbl_free
211 Frees the specified
212 .Vt struct tbl_node
213 and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures
214 referenced from it.
215 Called from
216 .Fn roff_free
217 and
218 .Fn roff_reset .
219 .El
220 .Ss Private functions
221 .Bl -tag -width Ds
222 .It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
223 Parses the options line into
224 .Vt struct tbl_opts .
225 Implemented in
226 .Pa tbl_opts.c ,
227 called from
228 .Fn tbl_read .
229 .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
230 Allocates and fills one
231 .Vt struct tbl_head
232 for each layout column, one
233 .Vt struct tbl_row
234 for each layout line, and one
235 .Vt struct tbl_cell
236 for each layout cell.
237 Implemented in
238 .Pa tbl_layout.c ,
239 called from
240 .Fn tbl_read .
241 .It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p"
242 Allocates one
243 .Vt struct tbl_span
244 for each data line and calls
245 .Fn data
246 on that line.
247 Implemented in
248 .Pa tbl_data.c ,
249 called from
250 .Fn tbl_read .
251 .It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p"
252 Continues parsing a data line:
253 When finding
254 .Sq T} ,
255 switches back to
256 .Dv TBL_PART_DATA
257 mode and calls
258 .Fn data
259 if there are more data cells on the line.
260 Otherwise, appends the data to the current data cell.
261 Implemented in
262 .Pa tbl_data.c ,
263 called from
264 .Fn tbl_read .
265 .It Xo
266 .Ft int
267 .Fo data
268 .Fa "struct tbl_node *tbl"
269 .Fa "struct tbl_span *dp"
270 .Fa "int ln"
271 .Fa "const char *p"
272 .Fa "int *pos"
273 .Fc
274 .Xc
275 Parses one data cell into one
276 .Vt struct tbl_dat .
277 Implemented in
278 .Pa tbl_data.c ,
279 called from
280 .Fn tbl_data
281 and
282 .Fn tbl_cdata .
283 .El
284 .Sh SEE ALSO
285 .Xr mandoc 1 ,
286 .Xr mandoc 3 ,
287 .Xr tbl 7
288 .Sh AUTHORS
289 .An -nosplit
290 The
291 .Nm tbl
292 library was written by
293 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
294 with contributions from
295 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .