Print a tabular_spec

Renders a tabular_spec interactively. The default behaviour mirrors gt::gt(): convert the spec to an htmltools tag list and let htmltools dispatch — RStudio + Positron viewer panes, Quarto / Rmd notebook inline, Databricks displayHTML, and plain-console cat() are all handled without any IDE- specific branching.

Arguments

x

The tabular_spec to render. <tabular_spec>: required. The same object you'd hand to emit().

...

Forwarded to htmltools::print / as.tags(). Use this to pass id, style, class overrides to the wrapping <div>.

view

Open the viewer? <logical(1)>: default interactive()“. Same role as gt::gt's `view` argument: passes through to htmltools as `browse = view`. Set `view = FALSE` to suppress the viewer for one call (e.g. to capture the HTML string without launching a window).

output

Force a specific preview format. <character(1) | NULL>: default NULL (auto). See the output argument section below for the full list. The session default can be set via options(tabular_print_output = "cli") for users who prefer the structural summary over the HTML preview.

Value

Invisibly returns x. Side effect: opens the viewer, inlines under a chunk, or cat()s output.

Details

Dispatch. print() delegates to as.tags.tabular_spec() which returns an htmltools::tagList. That tag list is handed to htmltools's own print method with browse = view: htmltools opens the IDE viewer when one is registered, inlines under a Quarto / Rmd chunk when running inside one, or cat()s the HTML when neither applies. No is_rstudio() / is_positron() / is_notebook() heuristics — htmltools already knows.

view argument. Defaults to interactive(), the same universal off-switch gt::gt() uses. Non-interactive contexts (Rscript, R CMD check, CI, devtools::test) bypass the viewer automatically. Pass view = FALSE explicitly at an interactive prompt to suppress the viewer for a single call.

output argument. Forces a specific preview format instead of the default HTML-via-htmltools path. One of:

• "html" — same as the default, but explicit.

• "md" / "markdown" — cat() the markdown source to the console (round-trips through backend_md).

• "latex" — cat() the markdown source as a temporary placeholder (real LaTeX preview lands with backend_latex).

• "rtf" / "docx" / "pdf" — render an HTML preview and emit a cli note pointing at emit() for the real artefact. The viewer pane cannot render RTF / OOXML, and we deliberately do not compile through tinytex on every autoprint.

• "cli" — print the structural cli-tree summary (props, headers, sort, pagination, preset). Useful for debugging spec composition without paying the HTML render cost.

Robustness. The HTML render is wrapped in tryCatch; if rendering fails for any reason the printer falls back to the cli-tree summary and a cli::cli_warn() describing the failure, so a broken spec never crashes the REPL.

Tempdir. Preview HTML files live under getOption("tabular_preview_dir", default = tempdir()). Override the option to keep them in a stable location (handy on Linux distros where browsers don't have read access to /tmp/).

See also

Tag conversion: as.tags.tabular_spec() — the htmltools tag list that print() delegates to. Call it directly to embed the table in a custom htmltools::tagList or Shiny UI.

Terminal verb: emit() writes the resolved artefact to disk; print() is for in-session preview only.

Pipeline shape: as_grid() resolves the engine pipeline to a tabular_grid without I/O.

Examples

# ---- Example 1: Build + autoprint (HTML preview) ----
#
# Build a spec and let autoprint render it. Inside RStudio /
# Positron the HTML lands in the viewer pane; inside a
# Quarto / Rmd chunk it inlines under the chunk; at a plain
# console the HTML source is `cat()`-ed.
tabular(
  cdisc_saf_demo,
  titles = c("Table 14.1.1", "Demographics"),
  footnotes = "Safety Population."
)
 
Table 14.1.1
Demographics
 

variable
stat_label
placebo
drug_50
drug_100
Total
Age (years)
n
86
96
72
254
Age (years)
Mean (SD)
75.2 (8.59)
76.0 (8.11)
73.8 (7.94)
75.1 (8.25)
Age (years)
Median
76.0
78.0
75.5
77.0
Age (years)
Q1, Q3
69.2, 81.8
71.0, 82.0
70.5, 79.0
70.0, 81.0
Age (years)
Min, Max
52, 89
51, 88
56, 88
51, 89
Sex, n (%)
F
53 (61.6)
55 (57.3)
35 (48.6)
143 (56.3)
Sex, n (%)
M
33 (38.4)
41 (42.7)
37 (51.4)
111 (43.7)
Race, n (%)
WHITE
78 (90.7)
90 (93.8)
62 (86.1)
230 (90.6)
Race, n (%)
BLACK OR AFRICAN AMERICAN
8 (9.3)
6 (6.2)
9 (12.5)
23 (9.1)
Race, n (%)
ASIAN
0 (0.0)
0 (0.0)
0 (0.0)
0 (0.0)
Race, n (%)
AMERICAN INDIAN OR ALASKA NATIVE
0 (0.0)
0 (0.0)
1 (1.4)
1 (0.4)
Safety Population.

# ---- Example 2: Force the cli-tree structural view ----
#
# The cli-tree summary shows props at a glance. Useful for
# debugging spec composition without paying the HTML render
# cost.
spec <- tabular(cdisc_saf_demo, titles = "Demographics") |>
  cols(variable = col_spec(usage = "group", label = "Characteristic"))

print(spec, output = "cli")
#> 
#> ── <tabular_spec> 
#> Data: 11 rows x 6 columns
#> Titles (1):
#> 1. "Demographics"
#> Config: cols (1)