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
)

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.

Value

Character. The combined text with optional headings.

Examples

# Import unified database
unified_db <- boilerplate_import()
#> ℹ importing all categories
#> ℹ using default path: /Users/joseph/GIT/boilerplate/boilerplate/data
#> ! data directory does not exist: /Users/joseph/GIT/boilerplate/boilerplate/data
#> ℹ importing measures database
#> ! measures database file not found, using default
#> ℹ importing methods database
#> ! methods database file not found, using default
#> ℹ importing results database
#> ! results database file not found, using default
#> ℹ importing discussion database
#> ! discussion database file not found, using default
#> ℹ importing appendix database
#> ! appendix database file not found, using default
#> ℹ importing template database
#> ! template database file not found, using default

# Basic usage with methods sections
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c("sample", "causal_assumptions.identification"),
  global_vars = list(
    exposure_var = "political_conservative",
    population = "university students"
  ),
  db = unified_db  # Pass the unified database
)
#> ℹ generating methods text with 2 sections
#> ℹ using methods from unified database
#> ℹ processing section: sample
#> ℹ applying template variables to sample
#> Warning: unresolved template variables: timeframe
#> ℹ processing section: causal_assumptions.identification
#> ℹ applying template variables to causal_assumptions.identification
#> ✔ successfully generated methods text with 2 section(s)

# Using just the methods database
methods_db <- boilerplate_import("methods")
#> ℹ using default path: /Users/joseph/GIT/boilerplate/boilerplate/data
#> ! data directory does not exist: /Users/joseph/GIT/boilerplate/boilerplate/data
#> ℹ importing methods database
#> ! methods database file not found, using default
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c(
    "sample",
    "statistical.longitudinal.lmtp"
  ),
  global_vars = list(exposure_var = "treatment"),
  db = methods_db  # Pass just the methods database
)
#> ℹ generating methods text with 2 sections
#> ℹ processing section: sample
#> ℹ applying template variables to sample
#> Warning: unresolved template variables: population, timeframe
#> ℹ processing section: statistical.longitudinal.lmtp
#> ℹ applying template variables to statistical.longitudinal.lmtp
#> ✔ successfully generated methods text with 2 section(s)