Generate Text from Boilerplate

This function generates text by retrieving and combining text from a boilerplate database. It allows for template variable substitution and customisation through overrides. Supports arbitrarily nested section paths using dot notation.

Usage

boilerplate_generate_text(
  category = c("measures", "methods", "results", "discussion", "appendix", "template"),
  sections,
  global_vars = list(),
  section_vars = list(),
  text_overrides = list(),
  db = NULL,
  data_path = NULL,
  warn_missing = TRUE,
  add_headings = FALSE,
  heading_level = "###",
  custom_headings = list(),
  quiet = FALSE,
  create_dirs = FALSE,
  confirm = TRUE,
  copy_bibliography = FALSE,
  bibliography_path = "."
)

Arguments

category

Character. Category of text to generate.

sections

Character vector. The sections to include (can use dot notation for nesting).

global_vars

List. Variables available to all sections.

section_vars

List. Section-specific variables.

text_overrides

List. Direct text overrides for specific sections.

db

List. Optional database to use. Can be either a category-specific database or a unified database. If a unified database is provided, the appropriate category will be extracted.

data_path

Character. Path to the directory where database files are stored. If NULL (default), uses here::here("boilerplate", "data").

warn_missing

Logical. Whether to warn about missing template variables.

add_headings

Logical. Whether to add markdown headings to sections. Default is FALSE.

heading_level

Character. The heading level to use (e.g., "###"). Default is "###".

custom_headings

List. Custom headings for specific sections. Names should match section names.

quiet

Logical. If TRUE, suppresses all CLI alerts. Default is FALSE.

create_dirs

Logical. If TRUE, creates directories that don't exist. Default is FALSE.

confirm

Logical. If TRUE, asks for confirmation before creating directories. Default is TRUE.

copy_bibliography

Logical. If TRUE, copies bibliography file to the project. Default is FALSE.

bibliography_path

Character. Directory to copy bibliography file to. Default is "." (current directory).

Value

Character. The combined text with optional headings.

Examples

# Create a temporary directory and initialise databases
temp_dir <- tempdir()
data_path <- file.path(temp_dir, "boilerplate_text_example", "data")

# Initialise with default content
boilerplate_init(
  categories = c("methods", "results"),
  data_path = data_path,
  create_dirs = TRUE,
  create_empty = FALSE,
  confirm = FALSE,
  quiet = TRUE
)

# Import the databases
unified_db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Basic usage with methods sections
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c("sample"),
  global_vars = list(
    exposure_var = "political_conservative",
    population = "university students"
  ),
  db = unified_db,
  quiet = TRUE
)
#> Warning: unresolved template variables: timeframe

# Check the output
cat(substr(methods_text, 1, 100), "...\n")
#> Participants were recruited from university students during {{timeframe}}. ...

# Using just the methods database with headings
methods_db <- boilerplate_import("methods", data_path = data_path, quiet = TRUE)
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c("sample"),
  global_vars = list(exposure_var = "treatment"),
  db = methods_db,
  add_headings = TRUE,
  heading_level = "##",
  quiet = TRUE
)
#> Warning: unresolved template variables: population, timeframe

# Clean up
unlink(file.path(temp_dir, "boilerplate_text_example"), recursive = TRUE)