contrib/mandoc/tbl.3

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