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 64This library is tightly integrated into the 65.Xr mandoc 1 66utility and not designed for stand-alone use. 67The present manual is intended as a reference for developers working on 68.Xr mandoc 1 . 69.Ss Data structures 70Unless otherwise noted, all of the following data structures are defined in 71.In mandoc.h 72and are deleted in 73.Fn tbl_free . 74.Bl -tag -width Ds 75.It Vt struct tbl_node 76This structure describes a complete table. 77It is defined in 78.In libroff.h , 79created in 80.Fn tbl_alloc , 81and stored in the members 82.Va first_tbl , 83.Va last_tbl , 84and 85.Va tbl 86of 87.Vt struct roff Bq Pa roff.c . 88.It Vt struct tbl_opts 89This structure describes the options of one table. 90It is used as a substructure of 91.Vt struct tbl_node 92and thus created and deleted together with it. 93It is filled in 94.Fn tbl_options . 95.It Vt struct tbl_head 96This structure describes one layout column in a table, 97in particular the vertical line to its left. 98It is allocated and filled in 99.Fn cell_alloc Bq Pa tbl_layout.c 100and referenced from the 101.Va first_head 102and 103.Va last_head 104members of 105.Vt struct tbl_node . 106.It Vt struct tbl_row 107This structure describes one layout line in a table 108by maintaining a list of all the cells in that line. 109It is allocated and filled in 110.Fn row Bq Pa tbl_layout.c 111and referenced from the 112.Va layout 113member of 114.Vt struct tbl_node . 115.It Vt struct tbl_cell 116This structure describes one layout cell in a table, 117in particular its alignment, membership in spans, and 118usage for lines. 119It is allocated and filled in 120.Fn cell_alloc Bq Pa tbl_layout.c 121and referenced from the 122.Va first 123and 124.Va last 125members of 126.Vt struct tbl_row . 127.It Vt struct tbl_span 128This structure describes one data line in a table 129by maintaining a list of all data cells in that line 130or by specifying that it is a horizontal line. 131It is allocated and filled in 132.Fn newspan Bq Pa tbl_data.c 133which is called from 134.Fn tbl_data 135and referenced from the 136.Va first_span , 137.Va current_span , 138and 139.Va last_span 140members of 141.Vt struct tbl_node , 142and from the 143.Va span 144members of 145.Vt struct man_node 146and 147.Vt struct mdoc_node 148from 149.In man.h 150and 151.In mdoc.h . 152.It Vt struct tbl_dat 153This structure describes one data cell in a table by specifying 154whether it contains a line or data, whether it spans additional 155layout cells, and by storing the data. 156It is allocated and filled in 157.Fn data 158and referenced from the 159.Va first 160and 161.Va last 162members of 163.Vt struct tbl_span . 164.El 165.Ss Interface functions 166The following functions are implemented in 167.Pa tbl.c , 168and all callers in 169.Pa roff.c . 170.Bl -tag -width Ds 171.It Fn tbl_alloc 172Allocates, initializes, and returns a new 173.Vt struct tbl_node . 174Called from 175.Fn roff_TS . 176.It Fn tbl_read 177Dispatches to 178.Fn tbl_option , 179.Fn tbl_layout , 180.Fn tbl_cdata , 181and 182.Fn tbl_data , 183see below. 184Called from 185.Fn roff_parseln . 186.It Fn tbl_restart 187Resets the 188.Va part 189member of 190.Vt struct tbl_node 191to 192.Dv TBL_PART_LAYOUT . 193Called from 194.Fn roff_T_ . 195.It Fn tbl_span 196On the first call, return the first 197.Vt struct tbl_span ; 198for later calls, return the next one or 199.Dv NULL . 200Called from 201.Fn roff_span . 202.It Fn tbl_end 203Flags the last span as 204.Dv TBL_SPAN_LAST 205and clears the pointer passed as an argment. 206Called from 207.Fn roff_TE 208and 209.Fn roff_endparse . 210.It Fn tbl_free 211Frees the specified 212.Vt struct tbl_node 213and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures 214referenced from it. 215Called from 216.Fn roff_free 217and 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" 223Parses the options line into 224.Vt struct tbl_opts . 225Implemented in 226.Pa tbl_opts.c , 227called from 228.Fn tbl_read . 229.It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p" 230Allocates and fills one 231.Vt struct tbl_head 232for each layout column, one 233.Vt struct tbl_row 234for each layout line, and one 235.Vt struct tbl_cell 236for each layout cell. 237Implemented in 238.Pa tbl_layout.c , 239called from 240.Fn tbl_read . 241.It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p" 242Allocates one 243.Vt struct tbl_span 244for each data line and calls 245.Fn data 246on that line. 247Implemented in 248.Pa tbl_data.c , 249called from 250.Fn tbl_read . 251.It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p" 252Continues parsing a data line: 253When finding 254.Sq T} , 255switches back to 256.Dv TBL_PART_DATA 257mode and calls 258.Fn data 259if there are more data cells on the line. 260Otherwise, appends the data to the current data cell. 261Implemented in 262.Pa tbl_data.c , 263called 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 275Parses one data cell into one 276.Vt struct tbl_dat . 277Implemented in 278.Pa tbl_data.c , 279called from 280.Fn tbl_data 281and 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 290The 291.Nm tbl 292library was written by 293.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 294with contributions from 295.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 296