Man page - tbl(3)

Packages contains this manual

Manual

TBL (3) Library Functions Manual TBL (3)

NAME

tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, tbl_free ā€” roff table parser library for mandoc

SYNOPSIS

#include <sys/types.h>
#include <tbl.h>
#include <tbl_parse.h>

struct tbl_node *

tbl_alloc ( intĀ pos , intĀ line );

void

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 reference for developers working on mandoc (1).

Data structures

Unless otherwise noted, all of the following data structures are declared in < tbl.h > and are deleted in tbl_free ().

struct tbl_node

This structure describes a complete table. It is declared in < tbl_int.h >, created in tbl_alloc (), and stored in the members first_tbl , last_tbl , and tbl of struct roff [ roff.c ].

The first_span , current_span , last_span , and next members may be NULL. The first_row and last_row members may be NULL, but if there is a span, the function tbl_layout () guarantees that these pointers are not NULL.

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_row

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 row () [ tbl_layout.c ] and referenced from the layout member of struct tbl_node .

The next member may be NULL. The function tbl_layout () guarantees that the first and last members are not NULL.

struct tbl_cell

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 cell_alloc () [ tbl_layout.c ] and referenced from the first and last members of struct tbl_row .

The next member may be NULL.

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 >.

The first , last , prev , and next members may be NULL. The function newspan () [ tbl_data.c ] guarantees that the opts and layout members are not NULL.

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 tbl_data () and referenced from the first and last members of struct tbl_span .

The string and next members may be NULL. The function getdata () guarantees that the layout member is not NULL.

Interface functions

The following functions are implemented in tbl.c , and all callers are 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, and tbl_dat structures referenced from it. Called from roff_free () and roff_reset ().

Private functions

The following functions are declared in < tbl_int.h >.

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_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 getdata () for each data cell. 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 getdata () 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
getdata ( 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 ALSO

mandoc (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 >. Debian DecemberĀ 14, 2018 TBL (3)