.TH "TBL" "3" "$Mdocdate: January 30 2015 $" "Debian" "Library Functions Manual"
.nh
.if n .ad l
.SH "NAME"
\fBtbl_alloc\fR,
\fBtbl_read\fR,
\fBtbl_restart\fR,
\fBtbl_span\fR,
\fBtbl_end\fR,
\fBtbl_free\fR
\- roff table parser library for mandoc
.SH "SYNOPSIS"
\fB#include <mandoc.h>\fR
.br
\fB#include <libmandoc.h>\fR
.br
\fB#include <libroff.h>\fR
.sp
\fIstruct tbl_node *\fR
.PD 0
.HP 4n
\fBtbl_alloc\fR(\fIint\ pos\fR,
\fIint\ line\fR,
\fIstruct\ mparse\ *parse\fR);
.PD
.PP
\fIenum rofferr\fR
.PD 0
.HP 4n
\fBtbl_read\fR(\fIstruct\ tbl_node\ *tbl\fR,
\fIint\ ln\fR,
\fIconst\ char\ *p\fR,
\fIint\ offs\fR);
.PD
.PP
\fIvoid\fR
.PD 0
.HP 4n
\fBtbl_restart\fR(\fIint\ line\fR,
\fIint\ pos\fR,
\fIstruct\ tbl_node\ *tbl\fR);
.PD
.PP
\fIconst struct tbl_span *\fR
.PD 0
.HP 4n
\fBtbl_span\fR(\fIstruct\ tbl_node\ *tbl\fR);
.PD
.PP
\fIvoid\fR
.PD 0
.HP 4n
\fBtbl_end\fR(\fIstruct\ tbl_node\ **tblp\fR);
.PD
.PP
\fIvoid\fR
.PD 0
.HP 4n
\fBtbl_free\fR(\fIstruct\ tbl_node\ *tbl\fR);
.PD
.SH "DESCRIPTION"
This library is tightly integrated into the
mandoc(1)
utility and not designed for stand-alone use.
The present manual is intended as a reference for developers working on
mandoc(1).
.SS "Data structures"
Unless otherwise noted, all of the following data structures are defined in
<\fImandoc.h\fR>
and are deleted in
\fBtbl_free\fR().
.TP 8n
\fIstruct tbl_node\fR
This structure describes a complete table.
It is defined in
<\fIlibroff.h\fR>,
created in
\fBtbl_alloc\fR(),
and stored in the members
\fIfirst_tbl\fR,
\fIlast_tbl\fR,
and
\fItbl\fR
of
\fIstruct roff\fR [\fIroff.c\fR].
.sp
The
\fIfirst_span\fR,
\fIcurrent_span\fR,
\fIlast_span\fR,
and
\fInext\fR
members may be
\fRNULL\fR.
The
\fIfirst_row\fR
and
\fIlast_row\fR
members may be
\fRNULL\fR,
but if there is a span, the function
\fBtbl_layout\fR()
guarantees that these pointers are not
\fRNULL\fR.
The function
\fBtbl_alloc\fR()
guarantees that the
\fIparse\fR
member is not
\fRNULL\fR.
.TP 8n
\fIstruct tbl_opts\fR
This structure describes the options of one table.
It is used as a substructure of
\fIstruct tbl_node\fR
and thus created and deleted together with it.
It is filled in
\fBtbl_options\fR().
.TP 8n
\fIstruct tbl_row\fR
This structure describes one layout line in a table
by maintaining a list of all the cells in that line.
It is allocated and filled in
\fBrow\fR() [\fItbl_layout.c\fR]
and referenced from the
\fIlayout\fR
member of
\fIstruct tbl_node\fR.
.sp
The
\fInext\fR
member may be
\fRNULL\fR.
The function
\fBtbl_layout\fR()
guarantees that the
\fIfirst\fR
and
\fIlast\fR
members are not NULL.
.TP 8n
\fIstruct tbl_cell\fR
This structure describes one layout cell in a table,
in particular its alignment, membership in spans, and
usage for lines.
It is allocated and filled in
\fBcell_alloc\fR() [\fItbl_layout.c\fR]
and referenced from the
\fIfirst\fR
and
\fIlast\fR
members of
\fIstruct tbl_row\fR.
.sp
The
\fInext\fR
member may be
\fRNULL\fR.
.TP 8n
\fIstruct tbl_span\fR
This structure describes one data line in a table
by maintaining a list of all data cells in that line
or by specifying that it is a horizontal line.
It is allocated and filled in
\fBnewspan\fR() [\fItbl_data.c\fR]
which is called from
\fBtbl_data\fR()
and referenced from the
\fIfirst_span\fR,
\fIcurrent_span\fR,
and
\fIlast_span\fR
members of
\fIstruct tbl_node\fR,
and from the
\fIspan\fR
members of
\fIstruct man_node\fR
and
\fIstruct mdoc_node\fR
from
<\fIman.h\fR>
and
<\fImdoc.h\fR>.
.sp
The
\fIfirst\fR,
\fIlast\fR,
\fIprev\fR,
and
\fInext\fR
members may be
\fRNULL\fR.
The function
\fBnewspan\fR() [\fItbl_data.c\fR]
guarantees that the
\fIopts\fR
and
\fIlayout\fR
members are not
\fRNULL\fR.
.TP 8n
\fIstruct tbl_dat\fR
This structure describes one data cell in a table by specifying
whether it contains a line or data, whether it spans additional
layout cells, and by storing the data.
It is allocated and filled in
\fBtbl_data\fR()
and referenced from the
\fIfirst\fR
and
\fIlast\fR
members of
\fIstruct tbl_span\fR.
.sp
The
\fIstring\fR
and
\fInext\fR
members may be
\fRNULL\fR.
The function
\fBgetdata\fR()
guarantees that the
\fIlayout\fR
member is not
\fRNULL\fR.
.SS "Interface functions"
The following functions are implemented in
\fItbl.c\fR,
and all callers in
\fIroff.c\fR.
.TP 8n
\fBtbl_alloc\fR()
Allocates, initializes, and returns a new
\fIstruct tbl_node\fR.
Called from
\fBroff_TS\fR().
.TP 8n
\fBtbl_read\fR()
Dispatches to
\fBtbl_option\fR(),
\fBtbl_layout\fR(),
\fBtbl_cdata\fR(),
and
\fBtbl_data\fR(),
see below.
Called from
\fBroff_parseln\fR().
.TP 8n
\fBtbl_restart\fR()
Resets the
\fIpart\fR
member of
\fIstruct tbl_node\fR
to
\fRTBL_PART_LAYOUT\fR.
Called from
\fBroff_T_\fR().
.TP 8n
\fBtbl_span\fR()
On the first call, return the first
\fIstruct tbl_span\fR;
for later calls, return the next one or
\fRNULL\fR.
Called from
\fBroff_span\fR().
.TP 8n
\fBtbl_end\fR()
Flags the last span as
\fRTBL_SPAN_LAST\fR
and clears the pointer passed as an argment.
Called from
\fBroff_TE\fR()
and
\fBroff_endparse\fR().
.TP 8n
\fBtbl_free\fR()
Frees the specified
\fIstruct tbl_node\fR
and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures
referenced from it.
Called from
\fBroff_free\fR()
and
\fBroff_reset\fR().
.SS "Private functions"
.TP 8n
\fIint\fR \fBtbl_options\fR(\fIstruct tbl_node *tbl\fR, \fIint ln\fR, \fIconst char *p\fR)
Parses the options line into
\fIstruct tbl_opts\fR.
Implemented in
\fItbl_opts.c\fR,
called from
\fBtbl_read\fR().
.TP 8n
\fIint\fR \fBtbl_layout\fR(\fIstruct tbl_node *tbl\fR, \fIint ln\fR, \fIconst char *p\fR)
Allocates and fills one
\fIstruct tbl_row\fR
for each layout line and one
\fIstruct tbl_cell\fR
for each layout cell.
Implemented in
\fItbl_layout.c\fR,
called from
\fBtbl_read\fR().
.TP 8n
\fIint\fR \fBtbl_data\fR(\fIstruct tbl_node *tbl\fR, \fIint ln\fR, \fIconst char *p\fR)
Allocates one
\fIstruct tbl_span\fR
for each data line and calls
\fBgetdata\fR()
for each data cell.
Implemented in
\fItbl_data.c\fR,
called from
\fBtbl_read\fR().
.TP 8n
\fIint\fR \fBtbl_cdata\fR(\fIstruct tbl_node *tbl\fR, \fIint ln\fR, \fIconst char *p\fR)
Continues parsing a data line:
When finding
\(oqT}\(cq,
switches back to
\fRTBL_PART_DATA\fR
mode and calls
\fBgetdata\fR()
if there are more data cells on the line.
Otherwise, appends the data to the current data cell.
Implemented in
\fItbl_data.c\fR,
called from
\fBtbl_read\fR().
.TP 8n
\fIint\fR
\fBgetdata\fR(\fIstruct\ tbl_node\ *tbl\fR,
\fIstruct\ tbl_span\ *dp\fR,
\fIint\ ln\fR,
\fIconst\ char\ *p\fR,
\fIint\ *pos\fR)
Parses one data cell into one
\fIstruct tbl_dat\fR.
Implemented in
\fItbl_data.c\fR,
called from
\fBtbl_data\fR()
and
\fBtbl_cdata\fR().
.SH "SEE ALSO"
mandoc(1),
mandoc(3),
tbl(7)
.SH "AUTHORS"
The
\fBtbl\fR
library was written by
Kristaps Dzonsons <\fIkristaps@bsd.lv\fR>
with contributions from
Ingo Schwarze <\fIschwarze@openbsd.org\fR>.