1.\" $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $
| 1.\" $Id: tbl.3,v 1.2 2015/01/30 04:11:50 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.\"
| 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 $Mdocdate: June 1 2013 $
| 17.Dd $Mdocdate: January 30 2015 $
|
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
| 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 ,
| 82.Fa first_tbl , 83.Fa last_tbl ,
|
84and
| 84and
|
85.Va tbl
| 85.Fa tbl
|
86of 87.Vt struct roff Bq Pa roff.c .
| 86of 87.Vt struct roff Bq Pa roff.c .
|
| 88.Pp 89The 90.Fa first_span , 91.Fa current_span , 92.Fa last_span , 93and 94.Fa next 95members may be 96.Dv NULL . 97The 98.Fa first_row 99and 100.Fa last_row 101members may be 102.Dv NULL , 103but if there is a span, the function 104.Fn tbl_layout 105guarantees that these pointers are not 106.Dv NULL . 107The function 108.Fn tbl_alloc 109guarantees that the 110.Fa parse 111member is not 112.Dv NULL .
|
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 .
| 113.It Vt struct tbl_opts 114This structure describes the options of one table. 115It is used as a substructure of 116.Vt struct tbl_node 117and thus created and deleted together with it. 118It is filled in 119.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
| 120.It Vt struct tbl_row 121This structure describes one layout line in a table 122by maintaining a list of all the cells in that line. 123It is allocated and filled in 124.Fn row Bq Pa tbl_layout.c 125and referenced from the
|
112.Va layout
| 126.Fa layout
|
113member of 114.Vt struct tbl_node .
| 127member of 128.Vt struct tbl_node .
|
| 129.Pp 130The 131.Fa next 132member may be 133.Dv NULL . 134The function 135.Fn tbl_layout 136guarantees that the 137.Fa first 138and 139.Fa last 140members are not NULL.
|
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
| 141.It Vt struct tbl_cell 142This structure describes one layout cell in a table, 143in particular its alignment, membership in spans, and 144usage for lines. 145It is allocated and filled in 146.Fn cell_alloc Bq Pa tbl_layout.c 147and referenced from the
|
122.Va first
| 148.Fa first
|
123and
| 149and
|
124.Va last
| 150.Fa last
|
125members of 126.Vt struct tbl_row .
| 151members of 152.Vt struct tbl_row .
|
| 153.Pp 154The 155.Fa next 156member may be 157.Dv NULL .
|
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
| 158.It Vt struct tbl_span 159This structure describes one data line in a table 160by maintaining a list of all data cells in that line 161or by specifying that it is a horizontal line. 162It is allocated and filled in 163.Fn newspan Bq Pa tbl_data.c 164which is called from 165.Fn tbl_data 166and referenced from the
|
136.Va first_span , 137.Va current_span ,
| 167.Fa first_span , 168.Fa current_span ,
|
138and
| 169and
|
139.Va last_span
| 170.Fa last_span
|
140members of 141.Vt struct tbl_node , 142and from the
| 171members of 172.Vt struct tbl_node , 173and from the
|
143.Va span
| 174.Fa span
|
144members of 145.Vt struct man_node 146and 147.Vt struct mdoc_node 148from 149.In man.h 150and 151.In mdoc.h .
| 175members of 176.Vt struct man_node 177and 178.Vt struct mdoc_node 179from 180.In man.h 181and 182.In mdoc.h .
|
| 183.Pp 184The 185.Fa first , 186.Fa last , 187.Fa prev , 188and 189.Fa next 190members may be 191.Dv NULL . 192The function 193.Fn newspan Bq Pa tbl_data.c 194guarantees that the 195.Fa opts 196and 197.Fa layout 198members are not 199.Dv NULL .
|
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
| 200.It Vt struct tbl_dat 201This structure describes one data cell in a table by specifying 202whether it contains a line or data, whether it spans additional 203layout cells, and by storing the data. 204It is allocated and filled in
|
157.Fn data
| 205.Fn tbl_data
|
158and referenced from the
| 206and referenced from the
|
159.Va first
| 207.Fa first
|
160and
| 208and
|
161.Va last
| 209.Fa last
|
162members of 163.Vt struct tbl_span .
| 210members of 211.Vt struct tbl_span .
|
| 212.Pp 213The 214.Fa string 215and 216.Fa next 217members may be 218.Dv NULL . 219The function 220.Fn getdata 221guarantees that the 222.Fa layout 223member is not 224.Dv NULL .
|
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
| 225.El 226.Ss Interface functions 227The following functions are implemented in 228.Pa tbl.c , 229and all callers in 230.Pa roff.c . 231.Bl -tag -width Ds 232.It Fn tbl_alloc 233Allocates, initializes, and returns a new 234.Vt struct tbl_node . 235Called from 236.Fn roff_TS . 237.It Fn tbl_read 238Dispatches to 239.Fn tbl_option , 240.Fn tbl_layout , 241.Fn tbl_cdata , 242and 243.Fn tbl_data , 244see below. 245Called from 246.Fn roff_parseln . 247.It Fn tbl_restart 248Resets the
|
188.Va part
| 249.Fa 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
| 250member of 251.Vt struct tbl_node 252to 253.Dv TBL_PART_LAYOUT . 254Called from 255.Fn roff_T_ . 256.It Fn tbl_span 257On the first call, return the first 258.Vt struct tbl_span ; 259for later calls, return the next one or 260.Dv NULL . 261Called from 262.Fn roff_span . 263.It Fn tbl_end 264Flags the last span as 265.Dv TBL_SPAN_LAST 266and clears the pointer passed as an argment. 267Called from 268.Fn roff_TE 269and 270.Fn roff_endparse . 271.It Fn tbl_free 272Frees the specified 273.Vt struct tbl_node
|
213and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures
| 274and all the tbl_row, tbl_cell, tbl_span, and tbl_dat 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
| 275referenced from it. 276Called from 277.Fn roff_free 278and 279.Fn roff_reset . 280.El 281.Ss Private functions 282.Bl -tag -width Ds 283.It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p" 284Parses the options line into 285.Vt struct tbl_opts . 286Implemented in 287.Pa tbl_opts.c , 288called from 289.Fn tbl_read . 290.It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p" 291Allocates and fills one
|
231.Vt struct tbl_head 232for each layout column, one
| |
233.Vt struct tbl_row
| 292.Vt struct tbl_row
|
234for each layout line, and one
| 293for 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
| 294.Vt struct tbl_cell 295for each layout cell. 296Implemented in 297.Pa tbl_layout.c , 298called from 299.Fn tbl_read . 300.It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p" 301Allocates one 302.Vt struct tbl_span 303for each data line and calls
|
245.Fn data 246on that line.
| 304.Fn getdata 305for each data cell.
|
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
| 306Implemented in 307.Pa tbl_data.c , 308called from 309.Fn tbl_read . 310.It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p" 311Continues parsing a data line: 312When finding 313.Sq T} , 314switches back to 315.Dv TBL_PART_DATA 316mode and calls
|
258.Fn data
| 317.Fn getdata
|
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
| 318if there are more data cells on the line. 319Otherwise, appends the data to the current data cell. 320Implemented in 321.Pa tbl_data.c , 322called from 323.Fn tbl_read . 324.It Xo 325.Ft int
|
267.Fo data
| 326.Fo getdata
|
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 .
| 327.Fa "struct tbl_node *tbl" 328.Fa "struct tbl_span *dp" 329.Fa "int ln" 330.Fa "const char *p" 331.Fa "int *pos" 332.Fc 333.Xc 334Parses one data cell into one 335.Vt struct tbl_dat . 336Implemented in 337.Pa tbl_data.c , 338called from 339.Fn tbl_data 340and 341.Fn tbl_cdata . 342.El 343.Sh SEE ALSO 344.Xr mandoc 1 , 345.Xr mandoc 3 , 346.Xr tbl 7 347.Sh AUTHORS 348.An -nosplit 349The 350.Nm tbl 351library was written by 352.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 353with contributions from 354.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
|