build_ascii_table: Build a formatted ASCII table

Description

Low-level internal function that constructs a visually aligned ASCII table from a data.frame. It supports Unicode characters, ANSI colors, dynamic width adjustment, left/right alignment, and spacing control. This function is primarily used internally by higher-level wrappers such as spicy_print_table() or print.spicy_freq_table().

Usage

build_ascii_table(
  x,
  padding = 2L,
  first_column_line = TRUE,
  row_total_line = TRUE,
  column_total_line = TRUE,
  bottom_line = FALSE,
  lines_color = "darkgrey",
  align_left_cols = c(1L, 2L),
  align_center_cols = integer(0),
  group_sep_rows = integer(0),
  total_row_idx = NULL,
  ...
)

Value

A single character string containing the full ASCII-formatted table, suitable for direct printing with cat().

Arguments

x

A data.frame or spicy_table object containing the table to format. Typically, this includes columns such as Category, Values, Freq., Percent, etc.

padding

Non-negative integer giving the number of extra characters added to each column's auto-computed width (the maximum of the cell-content width and the header width). Defaults to 2L, which gives a Stata- / cli-like compact look. Each cell additionally receives a one-space gutter on each side, so a padding = 2L column whose content is at most 5 characters wide occupies 9 characters in total (1 + 5 + 2 + 1).

The string choices "compact", "normal" and "wide" from spicy < 0.11.0 were removed; pass 0L, 2L or 4L instead. Passing a string raises an actionable error.

first_column_line

Logical. If TRUE (the default), a vertical separator is drawn after the first column (useful for separating categories from data).

row_total_line, column_total_line

Logical. Control horizontal rules before total rows or columns. Both default to TRUE.

bottom_line

Logical. If FALSE (the default), no closing line is drawn. If TRUE, draws a closing line at the bottom of the table.

lines_color

Character. Color used for table separators. Defaults to "darkgrey". The color is applied only when ANSI color support is available (see crayon::has_color()).

align_left_cols

Integer vector of column indices to left-align. Defaults to c(1, 2) for frequency tables (Category + Values).

align_center_cols

Integer vector of column indices to center-align. Defaults to integer(0) (no centered columns). Columns not in align_left_cols or align_center_cols are right-aligned.

group_sep_rows

Integer vector of row indices before which a light dashed separator line is drawn. Defaults to integer(0).

total_row_idx

Optional integer vector of 1-based row indices identifying the totals rows; a horizontal rule is drawn just before each. When NULL (the default), falls back to a regex match on "Total" / "Column_Total" in the formatted row text, which can mis-fire if a user category is literally named "Total" or "Sub-Total". Cross-tabs and frequency tables built by cross_tab() and freq() set this attribute on their result so the print methods are immune to that false positive.

...

Additional arguments (currently ignored).

Details

build_ascii_table() is the rendering engine that produces the aligned text layout of spicy-formatted tables. It automatically detects cell widths (including colored text), inserts Unicode separators, and applies a configurable amount of horizontal padding.

For most users, this function should not be called directly. Instead, use spicy_print_table() which adds headers, notes, and alignment logic automatically.

Examples

Run this code

# Internal usage example (for developers)
df <- data.frame(
  Category = c("Valid", "", "Missing", "Total"),
  Values = c("Yes", "No", "NA", ""),
  Freq. = c(12, 8, 1, 21),
  Percent = c(57.1, 38.1, 4.8, 100.0)
)

cat(build_ascii_table(df, padding = 0L))