contrib/mdocml/tbl.3

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