TBL(3)

✨ TBL(3) — Library Functions Manual ✨

okay bestie, gather round, because today we're talking about tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, and tbl_free — aka the roff table parser library for mandoc. no cap, this is the whole vibe. 🎀

---

🌸 NAME 🌸

tbl_alloc, tbl_read, tbl_restart, tbl_span, tbl_end, tbl_free — the 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 💜

so like, this library is tightly integrated into the mandoc(1) utility — it is not designed for stand-alone use, bestie. it's giving "built-in, not a plugin." this whole manual is meant as a reference for the devs working on mandoc(1), periodt. 👑

🧚 Data structures

unless noted otherwise, literally all of these data structures live in <tbl.h>, and they all get deleted in tbl_free(). so they're a package deal, okay? 💖

• struct tbl_node — this one describes a complete table. it's 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 too, but if there is a span, the function tbl_layout() guarantees those pointers are not NULL. so like, either both or neither, iykyk. 🌈
• struct tbl_opts — describes the options of one table. it's used as a substructure of struct tbl_node, so it gets created and deleted right along with it. it's filled in tbl_options(). 🎀
• struct tbl_row — describes one layout line in a table by maintaining a list of all the cells in that line. it's 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 — describes one layout cell in a table, specifically its alignment, its membership in spans, and its usage for lines. it's 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 — describes one data line in a table, either by maintaining a list of all data cells in that line or by specifying that it's a horizontal line. it's allocated and filled in newspan() [tbl_data.c], which is called from tbl_data(), and it's referenced from the first_span, current_span, and last_span members of struct tbl_node, plus 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 — 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's 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

these ones are implemented in tbl.c, and every single caller lives in roff.c. slay. 🎀

• tbl_alloc() — allocates, initializes, and returns a brand-new struct tbl_node. called from roff_TS().
• tbl_read() — dispatches to tbl_option(), tbl_layout(), tbl_cdata(), and tbl_data() (more on those below, bestie). 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, it returns the first struct tbl_span; for later calls, it returns the next one, or NULL. called from roff_span().
• tbl_end() — flags the last span as TBL_SPAN_LAST and clears the pointer passed in as an argument. called from roff_TE() and roff_endparse().
• tbl_free() — frees the specified struct tbl_node plus all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures referenced from it. called from roff_free() and roff_reset(). bye bestie, it was iconic 👋

🌈 Private functions

these ones are declared in <tbl_int.h>. shhh, they're the backstage crew. 🧚

• 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) — keeps parsing a data line: when it finds T}, it switches back to TBL_PART_DATA mode and calls getdata() if there are more data cells on the line. otherwise, it 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>. legends, honestly. 🫶👑

---

and that's the whole page, bestie — this one shipped with Debian, dated December 14, 2018. go forth and parse those tables, you absolute main character 💅✨🎀