-.\" $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $
+.\" $Id: tbl.3,v 1.6 2018/12/14 06:33:14 schwarze Exp $
.\"
-.\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2013, 2015, 2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: June 1 2013 $
+.Dd $Mdocdate: December 14 2018 $
.Dt TBL 3
.Os
.Sh NAME
.Nm tbl_free
.Nd roff table parser library for mandoc
.Sh SYNOPSIS
-.In mandoc.h
-.In libmandoc.h
-.In libroff.h
+.In sys/types.h
+.In tbl.h
+.In tbl_parse.h
.Ft struct tbl_node *
.Fo tbl_alloc
.Fa "int pos"
.Fa "int line"
-.Fa "struct mparse *parse"
.Fc
-.Ft enum rofferr
+.Ft void
.Fo tbl_read
.Fa "struct tbl_node *tbl"
.Fa "int ln"
The present manual is intended as a reference for developers working on
.Xr mandoc 1 .
.Ss Data structures
-Unless otherwise noted, all of the following data structures are defined in
-.In mandoc.h
+Unless otherwise noted, all of the following data structures are declared in
+.In tbl.h
and are deleted in
.Fn tbl_free .
.Bl -tag -width Ds
.It Vt struct tbl_node
This structure describes a complete table.
-It is defined in
-.In libroff.h ,
+It is declared in
+.In tbl_int.h ,
created in
.Fn tbl_alloc ,
and stored in the members
-.Va first_tbl ,
-.Va last_tbl ,
+.Fa first_tbl ,
+.Fa last_tbl ,
and
-.Va tbl
+.Fa tbl
of
.Vt struct roff Bq Pa roff.c .
+.Pp
+The
+.Fa first_span ,
+.Fa current_span ,
+.Fa last_span ,
+and
+.Fa next
+members may be
+.Dv NULL .
+The
+.Fa first_row
+and
+.Fa last_row
+members may be
+.Dv NULL ,
+but if there is a span, the function
+.Fn tbl_layout
+guarantees that these pointers are not
+.Dv NULL .
.It Vt struct tbl_opts
This structure describes the options of one table.
It is used as a substructure of
and thus created and deleted together with it.
It is filled in
.Fn tbl_options .
-.It Vt struct tbl_head
-This structure describes one layout column in a table,
-in particular the vertical line to its left.
-It is allocated and filled in
-.Fn cell_alloc Bq Pa tbl_layout.c
-and referenced from the
-.Va first_head
-and
-.Va last_head
-members of
-.Vt struct tbl_node .
.It Vt 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
.Fn row Bq Pa tbl_layout.c
and referenced from the
-.Va layout
+.Fa layout
member of
.Vt struct tbl_node .
+.Pp
+The
+.Fa next
+member may be
+.Dv NULL .
+The function
+.Fn tbl_layout
+guarantees that the
+.Fa first
+and
+.Fa last
+members are not NULL.
.It Vt struct tbl_cell
This structure describes one layout cell in a table,
in particular its alignment, membership in spans, and
It is allocated and filled in
.Fn cell_alloc Bq Pa tbl_layout.c
and referenced from the
-.Va first
+.Fa first
and
-.Va last
+.Fa last
members of
.Vt struct tbl_row .
+.Pp
+The
+.Fa next
+member may be
+.Dv NULL .
.It Vt struct tbl_span
This structure describes one data line in a table
by maintaining a list of all data cells in that line
which is called from
.Fn tbl_data
and referenced from the
-.Va first_span ,
-.Va current_span ,
+.Fa first_span ,
+.Fa current_span ,
and
-.Va last_span
+.Fa last_span
members of
.Vt struct tbl_node ,
and from the
-.Va span
+.Fa span
members of
.Vt struct man_node
and
.In man.h
and
.In mdoc.h .
+.Pp
+The
+.Fa first ,
+.Fa last ,
+.Fa prev ,
+and
+.Fa next
+members may be
+.Dv NULL .
+The function
+.Fn newspan Bq Pa tbl_data.c
+guarantees that the
+.Fa opts
+and
+.Fa layout
+members are not
+.Dv NULL .
.It Vt 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
-.Fn data
+.Fn tbl_data
and referenced from the
-.Va first
+.Fa first
and
-.Va last
+.Fa last
members of
.Vt struct tbl_span .
+.Pp
+The
+.Fa string
+and
+.Fa next
+members may be
+.Dv NULL .
+The function
+.Fn getdata
+guarantees that the
+.Fa layout
+member is not
+.Dv NULL .
.El
.Ss Interface functions
The following functions are implemented in
.Pa tbl.c ,
-and all callers in
+and all callers are in
.Pa roff.c .
.Bl -tag -width Ds
.It Fn tbl_alloc
.Fn roff_parseln .
.It Fn tbl_restart
Resets the
-.Va part
+.Fa part
member of
.Vt struct tbl_node
to
.It Fn tbl_free
Frees the specified
.Vt struct tbl_node
-and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures
+and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures
referenced from it.
Called from
.Fn roff_free
.Fn roff_reset .
.El
.Ss Private functions
+The following functions are declared in
+.In tbl_int.h .
.Bl -tag -width Ds
.It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
Parses the options line into
.Fn tbl_read .
.It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
Allocates and fills one
-.Vt struct tbl_head
-for each layout column, one
.Vt struct tbl_row
-for each layout line, and one
+for each layout line and one
.Vt struct tbl_cell
for each layout cell.
Implemented in
Allocates one
.Vt struct tbl_span
for each data line and calls
-.Fn data
-on that line.
+.Fn getdata
+for each data cell.
Implemented in
.Pa tbl_data.c ,
called from
switches back to
.Dv TBL_PART_DATA
mode and calls
-.Fn data
+.Fn getdata
if there are more data cells on the line.
Otherwise, appends the data to the current data cell.
Implemented in
.Fn tbl_read .
.It Xo
.Ft int
-.Fo data
+.Fo getdata
.Fa "struct tbl_node *tbl"
.Fa "struct tbl_span *dp"
.Fa "int ln"
git.ckatri.com / mandoc.git / blobdiff