TBL(3) BSD Library Functions Manual TBL(3)NAME
tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, tbl_free — roff ta‐
ble parser library for mandoc
SYNOPSIS
#include <mandoc.h>
#include <libmandoc.h>
#include <libroff.h>
struct tbl_node *
tbl_alloc(int pos, int line, struct mparse *parse);
enum rofferr
tbl_read(struct tbl_node *tbl, int ln, const char *p, int offs);
void
tbl_restart(int line, int pos, struct tbl_node *tbl);
const struct tbl_span *
tbl_span(struct tbl_node *tbl);
void
tbl_end(struct tbl_node **tblp);
void
tbl_free(struct tbl_node *tbl);
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 refer‐
ence for developers working on mandoc(1).
Data structures
Unless otherwise noted, all of the following data structures are defined
in <mandoc.h> and are deleted in tbl_free().
struct tbl_node
This structure describes a complete table. It is defined in
<libroff.h>, created in tbl_alloc(), and stored in the members
first_tbl, last_tbl, and tbl of struct roff [roff.c].
struct tbl_opts
This structure describes the options of one table. It is used as
a substructure of struct tbl_node and thus created and deleted
together with it. It is filled in tbl_options().
struct tbl_head
This structure describes one layout column in a table, in partic‐
ular the vertical line to its left. It is allocated and filled
in cell_alloc() [tbl_layout.c] and referenced from the first_head
and last_head members of struct tbl_node.
struct tbl_row
This structure describes one layout line in a table by maintain‐
ing a list of all the cells in that line. It is allocated and
filled in row() [tbl_layout.c] and referenced from the layout
member of struct tbl_node.
struct tbl_cell
This structure describes one layout cell in a table, in particu‐
lar its alignment, membership in spans, and usage for lines. It
is allocated and filled in cell_alloc() [tbl_layout.c] and refer‐
enced from the first and last members of struct tbl_row.
struct tbl_span
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 newspan()
[tbl_data.c] which is called from tbl_data() and referenced from
the first_span, current_span, and last_span members of struct
tbl_node, and from the span members of struct man_node and struct
mdoc_node from <man.h> and <mdoc.h>.
struct tbl_dat
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 data() and referenced from the first and last members
of struct tbl_span.
Interface functions
The following functions are implemented in tbl.c, and all callers in
roff.c.
tbl_alloc()
Allocates, initializes, and returns a new struct tbl_node.
Called from roff_TS().
tbl_read()
Dispatches to tbl_option(), tbl_layout(), tbl_cdata(), and
tbl_data(), see below. Called from roff_parseln().
tbl_restart()
Resets the part member of struct tbl_node to TBL_PART_LAYOUT.
Called from roff_T_().
tbl_span()
On the first call, return the first struct tbl_span; for later
calls, return the next one or NULL. Called from roff_span().
tbl_end()
Flags the last span as TBL_SPAN_LAST and clears the pointer
passed as an argment. Called from roff_TE() and roff_endparse().
tbl_free()
Frees the specified struct tbl_node and all the tbl_row,
tbl_cell, tbl_span, tbl_dat and tbl_head structures referenced
from it. Called from roff_free() and roff_reset().
Private functions
int tbl_options(struct tbl_node *tbl, int ln, const char *p)
Parses the options line into struct tbl_opts. Implemented in
tbl_opts.c, called from tbl_read().
int tbl_layout(struct tbl_node *tbl, int ln, const char *p)
Allocates and fills one struct tbl_head for each layout column,
one struct tbl_row for each layout line, and one struct tbl_cell
for each layout cell. Implemented in tbl_layout.c, called from
tbl_read().
int tbl_data(struct tbl_node *tbl, int ln, const char *p)
Allocates one struct tbl_span for each data line and calls data()
on that line. Implemented in tbl_data.c, called from tbl_read().
int tbl_cdata(struct tbl_node *tbl, int ln, const char *p)
Continues parsing a data line: When finding ‘T}’, switches back
to TBL_PART_DATA mode and calls data() if there are more data
cells on the line. Otherwise, appends the data to the current
data cell. Implemented in tbl_data.c, called from tbl_read().
int data(struct tbl_node *tbl, struct tbl_span *dp, int ln,
const char *p, int *pos)
Parses one data cell into one struct tbl_dat. Implemented in
tbl_data.c, called from tbl_data() and tbl_cdata().
SEE ALSOmandoc(1), mandoc(3), tbl(7)AUTHORS
The tbl library was written by Kristaps Dzonsons ⟨kristaps@bsd.lv⟩ with
contributions from Ingo Schwarze ⟨schwarze@openbsd.org⟩.
BSD April 28, 2024 BSD
