R API

Installation

# From source (requires Rust toolchain):
install.packages("gridwell", repos = NULL, type = "source")

Parsing

library(gridwell)

json <- paste(readLines("table.json", warn = FALSE), collapse = "\n")
tbl <- gw_parse_ir(json)

Validation

errors <- gw_validate(tbl)
if (length(errors) > 0) {
  message("Errors: ", paste(errors, collapse = "; "))
}

Text Rendering

html   <- gw_render_html(tbl)
latex  <- gw_render_latex(tbl)
typst  <- gw_render_typst(tbl)
rtf    <- gw_render_rtf(tbl)
svg    <- gw_render_svg(tbl)
ansi   <- gw_render_ansi(tbl)
pandoc <- gw_render_pandoc(tbl)
quarto <- gw_render_quarto(tbl)

# Generic by name
html <- gw_render(tbl, "html")

# Writer options: a named list, a JSON string, or named arguments
html <- gw_render(tbl, "html", list(inline_styles = TRUE))
html <- gw_render(tbl, "html", '{"inline_styles": true}')
html <- gw_render_html(tbl, inline_styles = TRUE)

# Every format, with its options and defaults (a data frame)
gw_formats()

Passing options as a list needs the jsonlite package. See Writer Options for each format’s options.

Binary Rendering

docx_raw <- gw_render_docx(tbl)    # raw vector
xlsx_raw <- gw_render_xlsx(tbl)
pptx_raw <- gw_render_pptx(tbl)

# Generic by name
docx_raw <- gw_render_binary(tbl, "docx")

Saving to a File

gw_save() renders and writes in one call, for every format: the format comes from the file extension and the bytes are written unchanged (UTF-8 text, no re-encoding, no added newline), so there is no writeLines() versus writeBin() to choose. It takes a gt table directly, or a parsed table, and returns path invisibly.

gt(exibble) |> gw_save("table.rtf")

gw_save(tbl, "output.docx")
gw_save(tbl, "table.tex", booktabs = FALSE)              # writer options as arguments
gw_save(tbl, "table.json", format = "quarto")            # .json is pandoc or quarto
gw_save(tbl, "table.txt")                                # plain text, no ANSI escapes
gw_save(tbl, "table.txt", color = TRUE)                  # keep the escapes
gw_save(tbl, "table.html", standalone = TRUE)            # a full document, not a fragment

# Many tables at once
purrr::walk2(tables, paths, gw_save)

Extension	Format
`.html`	html
`.tex`	latex
`.typ`	typst
`.rtf`	rtf
`.svg`	svg
`.txt`	ansi (plain text unless `color = TRUE`)
`.docx`, `.xlsx`, `.pptx`	docx, xlsx, pptx
`.json`	pandoc or quarto: pass `format`

Extensions are case-insensitive, and format overrides the extension. A missing, unknown or ambiguous extension is an error, and nothing is written if the table, format or options are invalid.

Serialization

json_out <- gw_to_json(tbl)

gt Integration

library(gt)
library(gridwell)

tbl <- gt(exibble, rowname_col = "row", groupname_col = "group")
ir_json <- gt_to_ir(tbl)
table_ptr <- gw_parse_ir(ir_json)
html <- gw_render_html(table_ptr)

Error Handling

Every gw_render*() function validates the table first and signals an R error listing the validation errors if the IR is invalid. Use gw_validate() to get them as a character vector instead. Unknown format names, a binary format passed to gw_render() (or a text one to gw_render_binary()), and invalid options are errors too. gw_save() adds errors for an extension it can’t infer a format from and for a file it can’t write (naming the path).

tryCatch(
  gw_parse_ir("invalid json"),
  error = function(e) message("Parse error: ", conditionMessage(e))
)