framework: Structured Data Science Project Scaffolding

Description

Project scaffolding and workflow tools for reproducible data science. Manages packages, tracks data integrity, handles database connections, generates notebooks, and publishes to S3-compatible storage. More information at https://framework.table1.org.

Author(s)

Maintainer: Erik Westlund erik@table1.org [copyright holder]

See Also

Useful links:

• https://framework.table1.org

• https://github.com/table1/framework

• Report bugs at https://github.com/table1/framework/issues

Apply auto-fix for common issues

Description

Apply auto-fix for common issues

Usage

.apply_auto_fix(findings, verbose)

Build directory table from config

Description

Build directory table from config

Usage

.build_directory_table(dirs, project_type)

Calculate hash of a file

Description

Calculate hash of a file

Usage

.calculate_file_hash(file_path)

Arguments

Value

The hash of the file as a character string

Retrieve a default value from the catalog, falling back when missing

Description

Retrieve a default value from the catalog, falling back when missing

Usage

.catalog_field_default(catalog, field_id, fallback = NULL)

Convenience accessor for catalog field definitions

Description

Convenience accessor for catalog field definitions

Usage

.catalog_find_field(catalog, field_id)

Convert catalog project type metadata into default configuration values

Description

Convert catalog project type metadata into default configuration values

Usage

.catalog_project_type_defaults(project_types)

Check if a DuckDB database exists

Description

Check if a DuckDB database exists

Usage

.check_duckdb_exists(config)

Arguments

Value

TRUE if database exists, FALSE otherwise

Check if .env is gitignored

Description

Checks if .env is listed in .gitignore and warns if not.

Usage

.check_env_gitignored()

Value

Invisibly returns logical indicating if .env is gitignored

Check if git is available

Description

Check if git is available

Usage

.check_git_available()

Check git history for leaked data files

Description

Check git history for leaked data files

Usage

.check_git_history(data_dirs, extensions, history_depth, verbose)

Check git status and provide helpful reminder

Description

Check git status and provide helpful reminder

Usage

.check_git_status()

Check gitignore coverage for data files

Description

Check gitignore coverage for data files

Usage

.check_gitignore_coverage(data_dirs, extensions, verbose)

Check if a MySQL/MariaDB database exists

Description

Check if a MySQL/MariaDB database exists

Usage

.check_mysql_exists(config)

Arguments

Value

TRUE if database exists, FALSE otherwise

Check if path is ignored by .gitignore patterns

Description

Check if path is ignored by .gitignore patterns

Usage

.check_path_ignored(path, gitignore_patterns)

Check if a PostgreSQL database exists

Description

Check if a PostgreSQL database exists

Usage

.check_postgres_exists(config)

Arguments

Value

TRUE if database exists, FALSE otherwise

Check if private data is tracked by git

Description

Check if private data is tracked by git

Usage

.check_private_data_exposure(data_dirs, git_available, verbose)

Check if a SQLite database exists

Description

Check if a SQLite database exists

Usage

.check_sqlite_exists(config)

Arguments

Value

TRUE if database exists, FALSE otherwise

Check if a SQL Server database exists

Description

Check if a SQL Server database exists

Usage

.check_sqlserver_exists(config)

Arguments

Value

TRUE if database exists, FALSE otherwise

Remove .gitkeep files from data/ and functions/ directories

Description

Remove .gitkeep files from data/ and functions/ directories

Usage

.cleanup_gitkeep_files(target_dir = ".")

Collect all S3 connections from config

Description

Gathers all S3/storage bucket connections from configuration, along with the default bucket name if specified.

Usage

.collect_all_s3_connections(config)

Arguments

Value

List with connections and default_bucket fields.

Create initial commit after first successful scaffold

Description

Create initial commit after first successful scaffold

Usage

.commit_after_scaffold()

Note

This function is now deprecated. Initial commits are created during project_create() instead of scaffold(). Kept for backward compatibility with older projects.

Configure git hooks based on environment variables

Description

Configure git hooks based on environment variables

Usage

.configure_git_hooks(target_dir = ".")

Connect to a DuckDB database

Description

Connect to a DuckDB database

Usage

.connect_duckdb(config)

Arguments

Value

A DuckDB database connection

Connect to a MySQL or MariaDB database

Description

Connect to a MySQL or MariaDB database

Usage

.connect_mysql(config)

Arguments

Value

A MySQL/MariaDB database connection

Connect to a PostgreSQL database

Description

Connect to a PostgreSQL database

Usage

.connect_postgres(config)

Arguments

Value

A PostgreSQL database connection

Connect to a SQLite database

Description

Connect to a SQLite database

Usage

.connect_sqlite(config)

Arguments

Value

A SQLite database connection

Connect to a SQL Server database

Description

Connect to a SQL Server database

Usage

.connect_sqlserver(config)

Arguments

Value

A SQL Server database connection via ODBC

Copy config files between directories

Description

Copy config files between directories

Usage

.copy_config_files(from_dir, to_dir, overwrite = FALSE)

Arguments

Create AI context files

Description

Create AI context files

Usage

.create_ai_files(project_dir, assistants, canonical_content, type)

Create AI Assistant Instruction Files

Description

Internal function called during project_create() to create AI assistant instruction files based on user preferences.

Usage

.create_ai_instructions(
  assistants,
  target_dir = ".",
  project_name = NULL,
  project_type = "project"
)

Arguments

Create .code-workspace file for VSCode/Positron

Description

Create .code-workspace file for VSCode/Positron

Usage

.create_code_workspace(project_dir, name)

Create settings.yml from template

Description

Create settings.yml from template

Usage

.create_config_file(type = "analysis", attach_defaults = TRUE, subdir = NULL)

Create development .Rprofile

Description

Create development .Rprofile

Usage

.create_dev_rprofile(subdir = NULL)

Create a new DuckDB database

Description

Create a new DuckDB database

Usage

.create_duckdb_db(config)

Arguments

Value

TRUE if successful

Create .gitignore file

Description

Create .gitignore file

Usage

.create_gitignore(project_dir, content)

Create IDE configuration files

Description

Create IDE configuration files

Usage

.create_ide_configs(project_name, target_dir = ".", python = FALSE)

Arguments

Create init.R from template

Description

Create init.R from template

Usage

.create_init_file(project_name, type, lintr, subdir = NULL)

Create initial git commit after all initialization is complete

Description

Create initial git commit after all initialization is complete

Usage

.create_initial_commit(target_dir = ".")

Create a new MySQL/MariaDB database

Description

Create a new MySQL/MariaDB database

Usage

.create_mysql_db(config)

Arguments

Value

TRUE if successful

Create a new PostgreSQL database

Description

Create a new PostgreSQL database

Usage

.create_postgres_db(config)

Arguments

Value

TRUE if successful

Create project config.yml

Description

Create project config.yml

Usage

.create_project_config(
  project_dir,
  name,
  type,
  author,
  packages,
  directories,
  extra_directories,
  ai,
  git,
  scaffold,
  settings_dir,
  connections = NULL,
  connections_file = NULL,
  render_dirs = NULL,
  quarto = NULL
)

Create project subdirectories

Description

Create project subdirectories

Usage

.create_project_directories(
  project_dir,
  directories,
  extra_directories,
  render_dirs = NULL
)

Create .renvignore file for Framework projects

Description

Creates a .renvignore file that excludes Framework data and output directories from renv dependency scanning.

Usage

.create_renvignore()

Value

Invisibly returns NULL

Create .Rproj file

Description

Create .Rproj file

Usage

.create_rproj_file(project_dir, name)

Create scaffold.R file

Description

Create scaffold.R file

Usage

.create_scaffold_file(project_dir, scaffold)

Create a new SQLite database

Description

Create a new SQLite database

Usage

.create_sqlite_db(config)

Arguments

Value

TRUE if successful

Create a new SQL Server database

Description

Create a new SQL Server database

Usage

.create_sqlserver_db(config)

Arguments

Value

TRUE if successful

Create stub files for specific project types

Description

Create stub files for specific project types

Usage

.create_stub_files(project_dir, type, name, author)

Create the template SQLite database

Description

Create the template SQLite database

Usage

.create_template_db(delete_existing = FALSE)

Create VS Code settings.json

Description

Create VS Code settings.json

Usage

.create_vscode_settings(target_dir = ".", python = FALSE)

Arguments

Create VS Code workspace file

Description

Create VS Code workspace file

Usage

.create_vscode_workspace(project_name, target_dir = ".", python = FALSE)

Arguments

Customize project files with user-specific substitutions

Description

Customize project files with user-specific substitutions

Usage

.customize_project_files(
  target_dir,
  author_name = NULL,
  author_email = NULL,
  author_affiliation = NULL
)

Update data spec in the correct YAML file

Description

Traverses a dot-notated key like "final.public.test" and updates or inserts the given spec in the corresponding YAML file (either embedded in settings.yml or in an external settings/data.yml file). Automatically handles nested paths and creates intermediate structures as needed.

Usage

.data_spec_update(path, spec)

Arguments

Value

Invisibly returns NULL. Function is called for its side effect of updating the YAML configuration file.

Get default directory table for project type

Description

Get default directory table for project type

Usage

.default_directory_table(project_type)

Resolve default render directory mappings for a project type from the catalog

Description

Resolve default render directory mappings for a project type from the catalog

Usage

.default_render_dirs_for_type(type)

Resolve default root render_dir (if defined) for a project type

Description

Resolve default root render_dir (if defined) for a project type

Usage

.default_root_render_dir_for_type(type)

Delete init.R after successful initialization

Description

Delete init.R after successful initialization

Usage

.delete_init_file(subdir = NULL)

Convert data frame to list of lists for YAML serialization JSON arrays of objects become data frames in R, but YAML needs list of lists

Description

Convert data frame to list of lists for YAML serialization JSON arrays of objects become data frames in R, but YAML needs list of lists

Usage

.df_to_list_of_lists(df)

Display next steps after initialization

Description

Display next steps after initialization

Usage

.display_next_steps(project_name = NULL, type = "project", use_renv = FALSE)

Ensure framework database exists with all required tables

Description

Ensure framework database exists with all required tables

Usage

.ensure_framework_db(project_root = NULL)

Arguments

Ensure the requested template exists in the user config directory

Description

Ensure the requested template exists in the user config directory

Usage

.ensure_framework_template(name)

Ensure a directory exists, creating it lazily with feedback

Description

Ensure a directory exists, creating it lazily with feedback

Usage

.ensure_output_dir(dir_path, dir_type = "output")

Arguments

Value

The directory path (invisibly)

Find project root by walking up directory tree

Description

Find project root by walking up directory tree

Usage

.find_project_root(start_dir)

Arguments

Value

Path to project root, or NULL if not found

Find Stub Template

Description

Searches for stub templates in user stubs/ directory first, then framework inst/stubs/ directory.

Usage

.find_stub_template(stub, ext)

Arguments

Value

Path to stub template file

Get the path to the packaged settings catalog YAML

Description

Get the path to the packaged settings catalog YAML

Usage

.framework_catalog_default_path()

Get the path to the user-editable settings catalog override

Description

Get the path to the user-editable settings catalog override

Usage

.framework_catalog_user_path()

Get the Framework templates directory

Description

Get the Framework templates directory

Usage

.framework_templates_dir(...)

Generate Data Management section

Description

Generate Data Management section

Usage

.generate_data_section(config, project_type)

Generate Framework Environment section

Description

Generate Framework Environment section

Usage

.generate_environment_section(config, project_type)

Generate Function Reference section

Description

Generate Function Reference section

Usage

.generate_function_reference()

Generate header section

Description

Generate header section

Usage

.generate_header_section(project_name)

Generate pre-commit hook script

Description

Generate pre-commit hook script

Usage

.generate_hook_script(
  ai_sync_enabled,
  data_security_enabled,
  check_sensitive_dirs_enabled
)

Generate notes section (user-editable)

Description

Generate notes section (user-editable)

Usage

.generate_notes_section()

Generate Installed Packages section

Description

Generate Installed Packages section

Usage

.generate_packages_section(config)

Generate project-type specific section

Description

Generate project-type specific section

Usage

.generate_project_type_section(project_type)

Get a cache value

Description

Get a cache value

Usage

.get_cache(name, file = NULL, expire_after = NULL)

Arguments

Value

The cached result, or NULL if not found, expired, or hash mismatch

Get the cache directory, respecting FW_CACHE_DIR environment variable

Description

Get the cache directory, respecting FW_CACHE_DIR environment variable

Usage

.get_cache_dir()

Value

The cache directory path

Get data directories from config

Description

Get data directories from config

Usage

.get_data_directories(config, verbose)

Get suggestions for available data paths

Description

Helper function that extracts all available data paths from config. Used to provide helpful suggestions when data_read() fails.

Usage

.get_data_path_suggestions(attempted_path = NULL)

Arguments

Value

Character vector of available data paths

Get a data value

Description

Get a data value

Usage

.get_data_record(name)

Arguments

Value

The data metadata (hash), or NULL if not found

Get a connection to the framework database

Description

Get a connection to the framework database

Usage

.get_db_connection(project_root = NULL)

Arguments

Get driver information for a given database type

Description

Internal helper to map database driver names to their R packages and human-readable names.

Usage

.get_driver_info(driver)

Arguments

Value

Named list with package, name, and optionally install_command

Get example data path based on config

Description

Get example data path based on config

Usage

.get_example_data_path(dirs, project_type, path_type)

Get git hook setting with optional alias fallback

Description

Get git hook setting with optional alias fallback

Usage

.get_hook_setting(key, alias = NULL, config_file = NULL, default = FALSE)

Get a metadata value

Description

Get a metadata value

Usage

.get_metadata(key, project_root = NULL)

Arguments

Value

The metadata value, or NULL if not found

Get Notebook Directory from Config

Description

Reads config to determine where notebooks should be created. Falls back to "notebooks", "work", or current directory if config unavailable.

Usage

.get_notebook_dir_from_config()

Value

Character path to notebook directory

Extract package list from config

Description

Handles two config structures:

1. New: packages = list(use_renv = ..., default_packages = ...)

2. Old: packages as a flat list of package specs

Usage

.get_package_list_from_config(config)

Arguments

Value

List of package specifications, or empty list if none

Get package requirements from config

Description

Get package requirements from config

Usage

.get_package_requirements(config)

Arguments

Generate database-appropriate parameter placeholders

Description

Generate database-appropriate parameter placeholders

Usage

.get_placeholders(conn, n)

Arguments

Value

Character vector of placeholders

Retrieve scaffold metadata from the database

Description

Retrieve scaffold metadata from the database

Usage

.get_scaffold_history(project_root = NULL)

Get settings file path

Description

Returns path to settings.yml (preferred) or config.yml (backward compatibility). Walks up directory tree to find project root if not found in current directory.

Usage

.get_settings_file(path = ".")

Arguments

Value

Path to settings file, or NULL if neither exists

Check if git is available on the system

Description

Check if git is available on the system

Usage

.git_available()

Value

TRUE if git is available, FALSE otherwise

Guess content type from file extension

Description

Guess content type from file extension

Usage

.guess_content_type(file)

Arguments

Value

Character. MIME type.

Check if settings file exists

Description

Checks for settings.yml (preferred) or settings.yml (backward compatibility).

Usage

.has_settings_file(path = ".")

Arguments

Value

TRUE if either file exists, FALSE otherwise

Identify directories that should be treated as private/sensitive

Description

Identify directories that should be treated as private/sensitive

Usage

.identify_private_dirs(data_dirs)

Initialize the framework database

Description

Initialize the framework database

Usage

.init_db()

Initialize git repository

Description

Initialize git repository

Initialize git repository

Usage

.init_git_repo(project_dir, hooks)

.init_git_repo(project_dir, hooks)

Initialize renv

Description

Initialize renv

Usage

.init_renv(project_dir)

Standard initialization process (shared by both paths)

Description

Standard initialization process (shared by both paths)

Usage

.init_standard(
  project_name,
  type,
  lintr,
  author_name = NULL,
  author_email = NULL,
  author_affiliation = NULL,
  default_notebook_format = NULL,
  subdir,
  force,
  use_git = TRUE
)

Install a package if not already installed

Description

Install a package if not already installed

Usage

.install_package(pkg_spec)

Arguments

Install package without renv

Description

Installs a package using base R functions, handling version pinning and GitHub sources.

Usage

.install_package_base(spec)

Arguments

Value

Invisibly returns TRUE on success

Install package via renv

Description

Installs a package using renv, handling version pinning and GitHub sources.

Usage

.install_package_renv(spec)

Arguments

Value

Invisibly returns TRUE on success

Install required packages from config

Description

Install required packages from config

Usage

.install_required_packages(config)

Arguments

Check if file is a data file based on extension

Description

Check if file is a data file based on extension

Usage

.is_data_file(file, extensions)

Check if current directory is a git repository

Description

Check if current directory is a git repository

Usage

.is_git_repo()

Check if project is initialized

Description

Checks for existence of settings.yml/settings.yml to determine initialization status.

Usage

.is_initialized(subdir = NULL)

Arguments

Value

Logical indicating if project is initialized.

List Available Stub Templates

Description

List Available Stub Templates

Usage

.list_available_stubs(ext = NULL)

Arguments

Value

Character vector of stub names

Load AI context template for a project type

Description

Load AI context template for a project type

Usage

.load_ai_template(project_type, project_name = "My Project")

Arguments

Value

Character string with template content

Load configuration from settings file

Description

Load configuration from settings file

Usage

.load_configuration(config_file = NULL)

Load environment variables from .env file

Description

Load environment variables from .env file

Usage

.load_environment(config_file = NULL, project_root = NULL)

Load all R files from functions directories

Description

Load all R files from functions directories

Usage

.load_functions(config_file = NULL, project_root = NULL)

Load all libraries specified in config

Description

Load all libraries specified in config

Usage

.load_libraries(config)

Arguments

Load template content from inst/templates

Description

Load template content from inst/templates

Usage

.load_template_content(template_name)

Create or append to .env file

Description

Creates a .env file (if it doesn't exist) and appends environment variables. Warns if .env is not in .gitignore to prevent accidental secret exposure.

Usage

.make_env(..., comment = NULL, check_gitignore = TRUE)

Arguments

Value

Invisibly returns TRUE on success

Mark project as scaffolded

Description

Mark project as scaffolded

Usage

.mark_scaffolded(project_root = NULL)

Arguments

Migrate config from previous R versions or legacy location

Description

Checks for configs in legacy ~/.config/framework location and copies them to the current R_user_dir location if found.

Usage

.migrate_config_from_previous(target_dir)

Arguments

Value

TRUE if migration occurred, FALSE otherwise

Normalize expire_after input to numeric hours

Description

Normalize expire_after input to numeric hours

Usage

.normalize_expire_after(expire_after, default = NULL)

Arguments

Normalize Notebook Name and Detect Type

Description

Normalize Notebook Name and Detect Type

Usage

.normalize_notebook_name(name, type = c("quarto", "rmarkdown", "script"))

Arguments

Value

List with name, type, and ext

Normalize package specification from config

Description

Converts the various package representations supported in settings.yml into a consistent structure that downstream helpers can rely on.

Usage

.normalize_package_spec(spec)

Arguments

Value

List with fields: name, source, version, repo, ref, auto_attach

Parse Assistant Selection from User Input

Description

Helper to convert user input like "1,3" or "4" into assistant names.

Usage

.parse_assistant_selection(selection)

Arguments

Value

Character vector of assistant names

Parse package specification with source detection

Description

Parses package specifications that may include explicit sources, version pins, or GitHub/Bioconductor references. Supports both scalar strings and list-style entries from settings.yml.

Usage

.parse_package_spec(spec)

Arguments

Details

Examples:

• "dplyr" -> list(name = "dplyr", source = "cran")

• "dplyr@1.1.0" -> list(name = "dplyr", version = "1.1.0", source = "cran")

• "tidyverse/dplyr@main" -> list(name = "dplyr", repo = "tidyverse/dplyr", ref = "main", source = "github")

• list(name = "DESeq2", source = "bioc") -> list(name = "DESeq2", source = "bioc")

Value

List with normalized components (name, source, version, repo, ref, auto_attach)

Parse markdown into sections based on ## headings

Description

Parse markdown into sections based on ## headings

Usage

.parse_sections(content)

Pretty-print configuration values (internal)

Description

Intelligently formats configuration output based on session type. In interactive sessions, pretty-prints nested structures. In scripts, returns raw values.

Usage

.pretty_print_config(value)

Arguments

Value

In interactive mode with complex values: invisible return after printing. Otherwise: raw value.

Print audit summary

Description

Print audit summary

Usage

.print_audit_summary(result)

Get AI Support Preferences (Non-interactive)

Description

Called during project_create() to check if AI instructions should be created. NO prompting - just returns saved preferences.

Usage

.prompt_ai_support_init()

Set AI Support Preferences (Non-interactive)

Description

Called from bash CLI to set AI preferences. NO prompting - bash handles all user interaction.

Usage

.prompt_ai_support_install(support = "never", assistants = character(0))

Arguments

Read a framework template

Description

Read a framework template

Usage

.read_framework_template(name)

Remove a cache value

Description

Remove a cache value

Usage

.remove_cache(name, file = NULL)

Arguments

Remove a data value

Description

Remove a data value

Usage

.remove_data(name)

Arguments

Remove initialization

Description

Removes settings.yml/settings.yml to mark project as uninitialized. WARNING: This will delete your project configuration!

Usage

.remove_init(subdir = NULL)

Arguments

Value

Logical indicating if removal was successful.

Remove a metadata value

Description

Remove a metadata value

Usage

.remove_metadata(key, project_root = NULL)

Arguments

Replace moustache-style placeholders in template content

Description

Supports both {{name}} and {{ name }} styles by trimming whitespace around the variable identifier before replacement.

Usage

.replace_moustache_placeholders(content, replacements)

Arguments

Value

Character vector with placeholders replaced.

Replace content of a specific section

Description

Replace content of a specific section

Usage

.replace_section(content, heading, new_content)

Check if a database driver package is available

Description

Internal helper to check if a required database driver package is installed. Throws an informative error if the package is missing.

Usage

.require_driver(driver_name, package_name, install_command = NULL)

Arguments

Value

NULL (invisible). Throws error if package not available.

Require git repository or stop

Description

Require git repository or stop

Usage

.require_git_repo()

Reset a template back to its packaged default

Description

Reset a template back to its packaged default

Usage

.reset_framework_template(name)

Create an S3 client from connection configuration

Description

Creates an S3 client object using credentials from the connection configuration. Credentials are resolved from connection config, falling back to environment variables. Loads .env file if present to ensure env vars are available.

Usage

.s3_client(conn_config)

Arguments

Value

An S3 client object (from aws.s3 package)

Generate public URL for S3 object

Description

Generate public URL for S3 object

Usage

.s3_public_url(key, s3_config)

Arguments

Value

Character. Public URL.

Upload a directory to S3

Description

Recursively uploads all files in a directory to S3.

Usage

.s3_upload_dir(dir, dest, s3_config, pattern = NULL)

Arguments

Value

Character vector. S3 URIs of uploaded files.

Upload a file to S3

Description

Uploads a single file to an S3 bucket.

Usage

.s3_upload_file(file, dest, s3_config, content_type = NULL)

Arguments

Value

Character. The S3 URI of the uploaded file.

Save audit result to framework database

Description

Save audit result to framework database

Usage

.save_audit_result(result)

Log a saved result to the framework database

Description

Internal function called by save_table(), save_figure(), etc. to track saved outputs in the results table.

Usage

.save_result(name, path, type, public = FALSE, comment = NULL)

Arguments

Value

NULL invisibly

Scan for orphaned data files outside configured directories

Description

Scan for orphaned data files outside configured directories

Usage

.scan_for_orphaned_files(data_dirs, extensions, verbose)

Set a cache value

Description

Set a cache value

Usage

.set_cache(name, value, file = NULL, expire_after = NULL)

Arguments

Set a data value

Description

Set a data value

Usage

.set_data(
  name,
  path = NULL,
  type = NULL,
  delimiter = NULL,
  locked = FALSE,
  hash = NULL
)

Arguments

Set ggplot2 theme for consistent styling

Description

Sets ggplot2 theme if configured. Checks for theme settings in this order:

1. Project settings.yml (ggplot_theme and set_theme_on_scaffold)

2. Skip if set_theme_on_scaffold is FALSE or theme is empty

Usage

.set_ggplot_theme(config)

Arguments

Set a metadata value

Description

Set a metadata value

Usage

.set_metadata(key, value, project_root = NULL)

Arguments

Set random seed for reproducibility

Description

Sets the random seed for reproducibility. Checks for seed in this order:

1. Project settings.yml (seed: value)

2. Global ~/.frameworkrc (FW_SEED)

3. Skip seeding if both are NULL or empty

Usage

.set_random_seed(config)

Arguments

Slugify a String

Description

Converts a string to a filesystem-safe slug:

• Converts to lowercase

• Replaces spaces and special characters with hyphens

• Removes consecutive hyphens

• Trims leading/trailing hyphens

Usage

.slugify(text)

Arguments

Value

Character. Slugified string

Sync packages from settings.yml to renv

Description

Reads the packages list from settings.yml and installs them via renv, then snapshots the result to renv.lock.

Usage

.sync_packages_to_renv()

Value

Invisibly returns TRUE on success

Convert string to kebab-case

Description

Convert string to kebab-case

Usage

.to_kebab_case(str)

Update data with hash in the data table

Description

Update data with hash in the data table

Update data with hash in the data table

Usage

.update_data_with_hash(name, hash)

.update_data_with_hash(name, hash)

Arguments

Update ~/.frameworkrc with AI Preferences

Description

Helper to update the frameworkrc file with AI support settings.

Usage

.update_frameworkrc(frameworkrc_path, support, assistants)

Arguments

Update .gitignore for renv

Description

Adds renv-related entries to .gitignore if they don't already exist.

Usage

.update_gitignore_for_renv()

Value

Invisibly returns NULL

Update hook configuration in settings.yml/settings.yml

Description

Update hook configuration in settings.yml/settings.yml

Usage

.update_hook_config(hook_name, enabled, config_file)

Determine if a project field uses split file or inline settings

Description

Determine if a project field uses split file or inline settings

Usage

.uses_split_file(project_path, field_name)

Arguments

Value

List with use_split, main_file, split_file, and has_default

Validate driver availability before connection

Description

Internal helper that combines driver info lookup and availability check. Used by connection functions to ensure required packages are installed.

Usage

.validate_driver(driver)

Arguments

Value

NULL (invisible). Throws error if driver package not available.

Validate refresh parameter

Description

Validate refresh parameter

Usage

.validate_refresh(refresh)

Arguments

Value

Boolean indicating if refresh is needed

Basic validation for the settings catalog structure

Description

Basic validation for the settings catalog structure

Usage

.validate_settings_catalog(catalog)

Write (overwrite) a framework template

Description

Write (overwrite) a framework template

Usage

.write_framework_template(name, contents)

Add project to global configuration

Description

Add project to global configuration

Usage

add_project_to_config(project_dir, project_name = NULL, project_type = NULL)

Arguments

Value

Invisibly returns the project ID

Generate AI Context File

Description

Generates a complete AI context file (CLAUDE.md, AGENTS.md, etc.) from scratch for a new project. The content is tailored to the project type and configuration.

Usage

ai_generate_context(
  project_path = ".",
  project_name = NULL,
  project_type = NULL,
  config = NULL
)

Arguments

Value

Character string with the complete AI context content

Examples

if (FALSE) {
# Generate AI context for current project
content <- ai_generate_context()

# Generate for a specific project type
content <- ai_generate_context(project_type = "project_sensitive")
}

Regenerate Dynamic Sections in AI Context File

Description

Updates only the sections marked with ⁠<!-- @framework:regenerate -->⁠ in an existing AI context file, preserving user customizations in unmarked sections.

Usage

ai_regenerate_context(project_path = ".", sections = NULL, ai_file = NULL)

Arguments

Value

Invisible TRUE on success

Examples

if (file.exists("CLAUDE.md")) {
  # Regenerate all dynamic sections
  ai_regenerate_context()

  # Regenerate only packages section
  ai_regenerate_context(sections = "packages")
}

Sync AI Assistant Context Files

Description

Copies content from the canonical AI assistant file to all other AI files, adding a warning header to non-canonical files.

Usage

ai_sync_context(config_file = NULL, force = FALSE, verbose = TRUE)

Arguments

Details

This function reads the ai.canonical_file setting from settings.yml and copies its content to all other AI assistant instruction files that exist in the project.

The canonical file is copied as-is. Non-canonical files receive a warning header indicating they are auto-synced and should not be edited directly.

Supported files:

• AGENTS.md - Cross-platform AI assistants

• CLAUDE.md - Claude Code

• .github/copilot-instructions.md - GitHub Copilot

Value

Invisible list with sync results

Examples

if (FALSE) {
# Sync AI context files
ai_sync_context()

# Force sync even if targets are newer
ai_sync_context(force = TRUE)

# Silent sync (for git hooks)
ai_sync_context(verbose = FALSE)
}

Bootstrap project initialization file

Description

Generates an init.R file showing the initialization logic. Useful for documentation and understanding how the project was set up.

Usage

bootstrap_project_init(output_file = "init.R")

Arguments

Value

Invisibly returns TRUE on success

Cache a value

Description

Cache a value

Usage

cache(name, value, file = NULL, expire_after = NULL)

Arguments

Value

The cached value

Clear all cached values

Description

Clear all cached values

Usage

cache_flush()

Value

Invisibly returns NULL.

Remove a cached value

Description

Remove a cached value

Usage

cache_forget(name, file = NULL)

Arguments

Value

Invisibly returns NULL.

Get a cached value

Description

Get a cached value

Usage

cache_get(name, file = NULL, expire_after = NULL)

Arguments

Value

The cached value, or NULL if not found, expired, or hash mismatch

List all cached values

Description

Returns a data frame of all cache entries with their names, expiration times, and status (expired or active).

Usage

cache_list()

Value

A data frame with columns:

name

Cache key name

expire_at

Expiration timestamp (NA if no expiration)

created_at

When the cache was created

updated_at

When the cache was last updated

last_read_at

When the cache was last read

status

Either "active" or "expired"

Returns an empty data frame if no cache entries exist.

Examples

if (FALSE) {
# List all cache entries
cache_list()

# Filter to see only expired caches
cache_list() |> dplyr::filter(status == "expired")
}

Remember a value (get from cache or compute and store)

Description

Attempts to retrieve a cached value by name. If the cache doesn't exist, is expired, or a refresh is requested, evaluates the expression and caches the result. This is the primary caching interface for expensive computations.

Usage

cache_remember(
  name,
  expr,
  file = NULL,
  expire_after = NULL,
  refresh = FALSE,
  expire = NULL
)

Arguments

Value

The cached value (if cache hit) or the result of evaluating expr (if cache miss or refresh requested)

Examples

if (FALSE) {
# Cache expensive computation
result <- cache_remember("my_analysis", {
  expensive_computation()
})

# Force refresh when data changes
result <- cache_remember("analysis", {
  run_analysis()
}, refresh = file.mtime("data.csv") > cache_time)
}

Capture console output and errors from an expression

Description

Capture console output and errors from an expression

Usage

capture_output(expr)

Arguments

Value

List containing status (boolean), console_output (character vector), and result (return value or error)

Get configuration value (alias for settings)

Description

Internal alias for settings.

Usage

config(key = NULL, default = NULL, config_file = NULL)

Arguments

Value

The configuration value

Configure AI Assistant Support

Description

Non-interactive function to configure AI assistant support. Should be called from bash CLI with parameters, not directly from R.

Usage

configure_ai_agents(support = NULL, assistants = NULL)

Arguments

Details

Supported AI assistants:

• Claude Code: Creates CLAUDE.md in project root

• GitHub Copilot: Creates .github/copilot-instructions.md

• AGENTS.md: Creates AGENTS.md (cross-platform, industry standard)

Configure Author Information

Description

Interactively set author information in settings.yml (or settings.yml for legacy projects). This information is used in notebooks, reports, and other documents.

Usage

configure_author(
  name = NULL,
  email = NULL,
  affiliation = NULL,
  interactive = TRUE
)

Arguments

Value

Invisibly returns updated config

Configure Database Connection

Description

Interactively add a database connection to settings.yml (or settings.yml for legacy projects). Connections can be defined inline or in a split file (settings/connections.yml).

Usage

configure_connection(
  name = NULL,
  driver = NULL,
  host = NULL,
  port = NULL,
  database = NULL,
  user = NULL,
  password = NULL,
  interactive = TRUE
)

Arguments

Value

Invisibly returns updated config

Configure Data Source

Description

Interactively add a data source to settings.yml (or settings.yml for legacy projects). Data sources are defined with dot-notation paths (e.g., "source.private.survey") and include metadata like file path, type, and whether the data is locked.

Usage

configure_data(
  path = NULL,
  file = NULL,
  type = NULL,
  locked = FALSE,
  interactive = TRUE
)

Arguments

Value

Invisibly returns updated config

Configure Project Directories

Description

Interactively configure project directory structure in settings.yml (or settings.yml for legacy projects). Directories control where Framework creates and looks for files.

Usage

configure_directories(directory = NULL, path = NULL, interactive = TRUE)

Arguments

Details

Standard Directories

• notebooks - Where make_notebook() creates files

• scripts - Where make_script() creates files

• functions - Where scaffold() looks for custom functions

• inputs_raw - Source data (gitignored)

• inputs_intermediate - Cleaned-but-input datasets

• inputs_final - Curated analytic datasets

• inputs_reference - External documentation/codebooks

• outputs_private - Working artifacts (tables/figures/models)

• outputs_public - Share-ready artifacts

• outputs_docs - Narrative/report outputs (private)

• outputs_docs_public - Narrative/report outputs (public)

• cache - Cached computation results

• scratch - Temporary workspace

Value

Invisibly returns updated config

Configure Global Framework Settings

Description

Unified function for reading and writing global Framework settings to ~/.frameworkrc.json. This function provides a single source of truth for global configuration, used by both the CLI and GUI interfaces.

Usage

configure_global(settings = NULL, validate = TRUE)

Arguments

Details

Global Settings Structure

• author - Author information (name, email, affiliation)

• defaults - Project defaults

  • project_type - Default project type ("project", "presentation", "course")

  • notebook_format - Default notebook format ("quarto", "rmarkdown")

  • ide - IDE preference ("vscode", "rstudio", "both", "none")

  • use_git - Initialize git repositories by default

  • use_renv - Enable renv by default

  • seed - Default random seed

  • seed_on_scaffold - Set seed during scaffold()

  • ai_support - Enable AI assistant support

  • ai_assistants - List of AI assistants ("claude", "agents", etc.)

  • ai_canonical_file - Canonical AI instruction file

  • packages - Default package list

  • directories - Default directory structure

  • git_hooks - Git hook preferences

• projects - Registered projects list

• active_project - Currently active project path

Value

Invisibly returns updated global configuration

Examples

if (FALSE) {
# Update author information
configure_global(settings = list(
  author = list(
    name = "Jane Doe",
    email = "jane@example.com"
  )
))

# Update default project type
configure_global(settings = list(
  defaults = list(
    project_type = "presentation"
  )
))

# Get current settings (read-only)
current <- configure_global()
}

Configure Package Dependencies

Description

Interactively add package dependencies to settings.yml (or settings.yml for legacy projects). Packages can be installed from CRAN, GitHub, or Bioconductor, with version pinning support.

Usage

configure_packages(
  package = NULL,
  auto_attach = TRUE,
  version = NULL,
  interactive = TRUE
)

Arguments

Details

Package Specifications

• CRAN: "dplyr", "ggplot2"

• CRAN with version: "dplyr@1.1.0"

• GitHub: "tidyverse/dplyr", "user/repo@branch"

• GitHub with tag: "user/repo@v1.2.3"

Value

Invisibly returns updated config

Begin a database transaction

Description

Manually begin a database transaction. You must call connection_commit() to save changes or connection_rollback() to discard them.

Usage

connection_begin(conn)

Arguments

Details

Note: Using db_transaction() is preferred as it automatically handles commit/rollback.

Value

NULL (invisible)

Check if a connection is ready to use

Description

Diagnoses whether a configured database connection can be established. Checks driver availability and configuration validity without actually connecting to the database.

Usage

connection_check(connection_name)

Arguments

Value

A list with diagnostic information:

• ready: Logical. TRUE if connection appears ready

• driver: Driver name

• package: Required package

• package_installed: Whether package is available

• config_valid: Whether configuration appears valid

• messages: Character vector of diagnostic messages

Check for leaked database connections

Description

Scans the global environment and parent frames for open database connections. Useful for debugging connection leaks in interactive sessions or long-running scripts.

Usage

connection_check_leaks(warn = TRUE)

Arguments

Value

A data frame with information about open connections:

• object_name: Name of the variable holding the connection

• class: Connection class (e.g., "PqConnection", "SQLiteConnection")

• valid: Whether connection is still valid

Close all open database connections

Description

Safely closes all open database connections in the global environment. Useful for cleaning up after interactive sessions or when resetting state.

Usage

connection_close_all(force = FALSE, quiet = FALSE)

Arguments

Value

Invisibly returns the number of connections closed

Commit a database transaction

Description

Commits the current transaction, making all changes permanent.

Usage

connection_commit(conn)

Arguments

Value

NULL (invisible)

Delete a record from a table

Description

Deletes a record from a table. Supports soft-delete pattern where records have a deleted_at column. Hard-delete can be forced with soft = FALSE.

Usage

connection_delete(conn, table_name, id, soft = TRUE)

Arguments

Value

Number of rows affected

Find a record by ID

Description

Finds a single record in a table by its ID. Supports soft-delete patterns where records have a deleted_at column.

Usage

connection_find(conn, table_name, id, with_trashed = FALSE)

Arguments

Value

A data frame with the record, or empty data frame if not found

Find records by column values

Description

Finds records in a table matching specified column values. Supports soft-delete patterns where records have a deleted_at column.

Usage

connection_find_by(conn, table_name, ..., with_trashed = FALSE)

Arguments

Value

A data frame with matching records, or empty data frame if none found

Insert a record into a table

Description

Inserts a new record into a table with automatic timestamp handling. If the table has created_at/updated_at columns, they will be set automatically.

Usage

connection_insert(conn, table_name, values, auto_timestamps = TRUE)

Arguments

Value

The ID of the inserted record (if auto-increment ID exists), or number of rows affected

Get or create a connection pool

Description

Returns a connection pool for the specified database connection. Connection pools automatically manage connection lifecycle, reuse connections across operations, and handle cleanup. This is the recommended way to work with databases in Framework.

Usage

connection_pool(
  name,
  min_size = 1,
  max_size = Inf,
  idle_timeout = 60,
  validation_interval = 60,
  recreate = FALSE
)

Arguments

Details

Connection pools are stored in a package environment and reused across calls. You don't need to manage pool lifecycle - Framework handles it automatically.

Advantages of connection pools:

• Automatic connection reuse (faster than creating new connections)

• Handles connection failures gracefully (auto-reconnects)

• Thread-safe for Shiny apps

• No need to manually disconnect

• Health checking prevents using stale connections

When to use:

• Long-running R sessions (notebooks, Shiny apps)

• Multiple database operations

• Any production code

When NOT to use:

• One-off queries (use query_get() instead)

• Short scripts (overhead not worth it)

Value

A pool object that can be used like a regular DBI connection

Close a specific connection pool

Description

Closes and removes a connection pool. All connections in the pool are gracefully closed.

Usage

connection_pool_close(name, quiet = FALSE)

Arguments

Value

Invisibly returns TRUE if pool was closed, FALSE if it didn't exist

Close all connection pools

Description

Closes all active connection pools. Useful for cleanup when shutting down R sessions or resetting state.

Usage

connection_pool_close_all(quiet = FALSE)

Arguments

Value

Invisibly returns the number of pools closed

List active connection pools

Description

Shows all currently active connection pools with their status.

Usage

connection_pool_list()

Value

A data frame with pool information:

• name: Pool name

• valid: Whether pool is valid

• connections: Number of active connections (if available)

Restore a soft-deleted record

Description

Restores a soft-deleted record by setting deleted_at to NULL. Only works on tables with a deleted_at column.

Usage

connection_restore(conn, table_name, id)

Arguments

Value

Number of rows affected

Rollback a database transaction

Description

Rolls back the current transaction, discarding all changes.

Usage

connection_rollback(conn)

Arguments

Value

NULL (invisible)

Update a record in a table

Description

Updates an existing record in a table with automatic timestamp handling. If the table has an updated_at column, it will be set automatically.

Usage

connection_update(conn, table_name, id, values, auto_timestamps = TRUE)

Arguments

Value

Number of rows affected

Execute code with a connection pool

Description

Convenience wrapper for working with connection pools. Gets or creates a pool and makes it available as pool within the code block.

Usage

connection_with_pool(connection_name, code, ...)

Arguments

Value

The result of evaluating code

Execute code with transaction if not already in one

Description

Similar to db_transaction(), but only starts a new transaction if not already in one. Useful for functions that can be called both standalone and within an existing transaction.

Usage

connection_with_transaction(conn, code)

Arguments

Value

The result of the code expression

List all connections (databases and object storage)

Description

Prints both database connections defined under ⁠connections:⁠ and object storage profiles (S3-compatible buckets). Use this to see everything Framework can talk to from your config.

Usage

connections_list()

Value

Invisibly returns NULL after printing summaries.

S3 Connection Functions

Description

Functions for connecting to and interacting with S3-compatible storage.

Add an existing file to the data catalog

Description

Registers an existing data file with the Framework data catalog. This allows you to track files that were created outside of Framework (e.g., downloaded from external sources, copied from other projects) and use them with data_read() using dot notation.

Usage

data_add(
  file_path,
  name = NULL,
  type = NULL,
  delimiter = "comma",
  locked = TRUE,
  update_config = TRUE
)

Arguments

Value

Invisibly returns the data spec that was created

Examples

if (FALSE) {
# Add a downloaded CSV file to the catalog
data_add("inputs/raw/survey_results.csv", name = "inputs.raw.survey_results")

# Now you can read it with dot notation
data_read("inputs.raw.survey_results")

# Add with auto-generated name
data_add("inputs/intermediate/cleaned_data.rds")
# Name will be derived as "inputs.intermediate.cleaned_data"
}

Get data specification from config

Description

Gets the data specification for a given dot notation path from settings.yml. Supports dot notation (e.g., "source.private.example"), relative paths, and absolute paths. Auto-detects file type from extension and applies intelligent defaults for common formats.

Usage

data_info(path)

Arguments

Value

A list with data specification including:

• path - Full file path

• type - File type (csv, rds, stata, spss, sas, etc.)

• delimiter - Delimiter for CSV files (comma, tab, etc.)

• locked - Whether file is locked for integrity checking

• private - Whether file is in private data directory

• description - Optional description of the dataset (displayed when loading)

Examples

if (FALSE) {
# Get info from dot notation
info <- data_info("source.private.my_data")

# Get info from file path
info <- data_info("data/public/example.csv")
}

List all data entries from config

Description

Lists all data specifications defined in the configuration, showing the data key, path, type, and description (if available).

Usage

data_list()

Value

A data frame with columns: name, path, type, locked, description

Examples

if (FALSE) {
# List all data entries
data_list()

# Use the alias
list_data()
}

Read data using dot notation path or direct file path

Description

Supports CSV, TSV, RDS, Excel (.xlsx, .xls), Stata (.dta), SPSS (.sav, .zsav, .por), and SAS (.sas7bdat, .xpt) file formats.

Usage

data_read(path, delim = NULL, keep_attributes = FALSE, ...)

Arguments

Value

The loaded data, typically a data frame or tibble.

Read data with caching (DEPRECATED)

Description

This function is deprecated. Use cache_remember() with data_read() instead:

df <- cache_remember("my_data", data_read("source.private.example"))

Usage

data_read_or_cache(path, expire_after = NULL, refresh = FALSE)

Arguments

Value

The loaded data, either from cache or file

Save data using dot notation or file path

Description

Save data using dot notation or file path

Usage

data_save(
  data,
  path,
  type = NULL,
  delimiter = "comma",
  locked = TRUE,
  force = FALSE
)

Arguments

Value

Invisibly returns the saved data.

Get data specification (DEPRECATED)

Description

This function has been renamed to data_info(). Please use that instead.

Usage

data_spec_get(path)

Arguments

Value

A list with data specification

Get a database connection

Description

Gets a database connection based on the connection name in config.yml. For most use cases, prefer db_query() or db_execute() which handle connection lifecycle automatically.

Usage

db_connect(name)

Arguments

Value

A database connection object (DBIConnection)

Examples

if (FALSE) {
# Preferred: use db_query() which auto-disconnects
users <- db_query("SELECT * FROM users", "postgres")

# Manual connection management (remember to disconnect!)
conn <- db_connect("postgres")
DBI::dbListTables(conn)
DBI::dbDisconnect(conn)
}

Install database drivers

Description

Interactive helper to install one or more database drivers. Provides helpful instructions and handles special cases (like ODBC).

Usage

db_drivers_install(drivers = NULL, repos = getOption("repos"))

Arguments

Value

NULL (invisible). Installs packages as side effect.

Examples

if (FALSE) {
# Install specific drivers
db_drivers_install(c("postgres", "mysql"))

# Interactive mode
db_drivers_install()
}

Check if database drivers are installed

Description

Checks which database drivers are currently available on the system. Returns a data frame showing the status of all supported database drivers.

Usage

db_drivers_status(quiet = FALSE)

Arguments

Value

A data frame with columns:

• driver: Database driver name

• package: Required R package

• installed: Whether the package is installed

• version: Package version (if installed)

Examples

# Check all drivers
db_drivers_status()

# Quiet mode (no messages)
db_drivers_status(quiet = TRUE)

Execute a database statement

Description

Executes a SQL statement on a database without returning results. The connection is created, used, and automatically closed.

Usage

db_execute(query, connection_name, ...)

Arguments

Value

Number of rows affected

Examples

if (FALSE) {
rows <- db_execute("DELETE FROM cache WHERE expired = TRUE", "my_db")
}

List all database connections from configuration

Description

Lists all database connections defined in the configuration, showing the connection name, driver, host, and database name (if applicable).

Usage

db_list()

Value

Invisibly returns NULL after printing connection list

Examples

if (FALSE) {
# List all connections
db_list()
}

Get data from a database query

Description

Gets data from a database using a query and connection name. The connection is created, used, and automatically closed.

Usage

db_query(query, connection_name, ...)

Arguments

Value

A data frame with the query results

Examples

if (FALSE) {
users <- db_query("SELECT * FROM users", "my_db")
}

Execute code within a database transaction

Description

Wraps code execution in a database transaction with automatic commit on success and rollback on error. This ensures atomicity of multiple database operations.

Usage

db_transaction(conn, code)

Arguments

Details

The function automatically:

• Begins a transaction with DBI::dbBegin()

• Executes the provided code

• Commits the transaction on success with DBI::dbCommit()

• Rolls back the transaction on error with DBI::dbRollback()

Transactions are essential for maintaining data integrity when performing multiple related operations. If any operation fails, all changes are rolled back.

Value

The result of the code expression

Examples

if (FALSE) {
conn <- db_connect("postgres")

# Basic transaction
db_transaction(conn, {
  DBI::dbExecute(conn, "INSERT INTO users (name, age) VALUES ('Alice', 30)")
  DBI::dbExecute(conn, "INSERT INTO users (name, age) VALUES ('Bob', 25)")
})

# Transaction with error handling - auto-rollback on error
tryCatch({
  db_transaction(conn, {
    DBI::dbExecute(conn, "INSERT INTO users (name) VALUES ('Alice')")
    stop("Something went wrong")  # This will trigger rollback
  })
}, error = function(e) {
  message("Transaction failed: ", e$message)
})

DBI::dbDisconnect(conn)
}

Execute code with a managed database connection

Description

Provides automatic connection lifecycle management. The connection is automatically closed when the code block finishes, even if an error occurs. This prevents connection leaks and ensures proper resource cleanup.

Usage

db_with(connection_name, code)

Arguments

Value

The result of evaluating code

Examples

if (FALSE) {
# Safe - connection auto-closes
users <- db_with("my_db", {
  DBI::dbGetQuery(conn, "SELECT * FROM users WHERE active = TRUE")
})

# Multiple operations with same connection
result <- db_with("my_db", {
  DBI::dbExecute(conn, "INSERT INTO users (name) VALUES ('Alice')")
  DBI::dbGetQuery(conn, "SELECT * FROM users")
})

# Connection closes even on error
tryCatch(
  db_with("my_db", {
    stop("Something went wrong")  # Connection still closes
  }),
  error = function(e) message(e$message)
)
}

Export Package Documentation to Database

Description

Parses roxygen2-generated .Rd files and exports structured documentation to SQLite (for GUI) or other formats. This enables searchable documentation in the Framework GUI and powers the public documentation website.

Usage

docs_export(
  output_path = "docs.db",
  man_dir = "man",
  package_name = "framework",
  package_version = NULL,
  include_internal = FALSE,
  verbose = TRUE
)

Arguments

Details

The exporter reads all .Rd files from the man/ directory and extracts:

• Function name, title, description, details

• Arguments/parameters with descriptions

• Usage signatures

• Examples (with dontrun detection)

• See Also references

• Custom sections and subsections

• Keywords

The SQLite output includes FTS5 full-text search for fast querying.

Value

Invisibly returns the database connection path

Examples

if (FALSE) {
# Export to default location (exported functions only)
docs_export()

# Export to custom location
docs_export("inst/gui/docs.db")

# Include internal/private functions too
docs_export("all_docs.db", include_internal = TRUE)

# Query the exported docs
con <- DBI::dbConnect(RSQLite::SQLite(), "docs.db")
DBI::dbGetQuery(con, "SELECT name, title FROM functions WHERE name LIKE 'data_%'")
DBI::dbDisconnect(con)
}

Check if a column exists in a table (S3 generic)

Description

Cross-database method to check if a column exists in a table. Uses database-specific introspection methods via S3 dispatch.

Usage

.has_column(conn, table_name, column_name)

## S3 method for class 'SQLiteConnection'
.has_column(conn, table_name, column_name)

## S3 method for class 'PqConnection'
.has_column(conn, table_name, column_name)

## S3 method for class 'MariaDBConnection'
.has_column(conn, table_name, column_name)

## S3 method for class ''Microsoft SQL Server''
.has_column(conn, table_name, column_name)

## S3 method for class 'duckdb_connection'
.has_column(conn, table_name, column_name)

## Default S3 method:
.has_column(conn, table_name, column_name)

Arguments

Value

Logical. TRUE if column exists, FALSE otherwise

Functions

• .has_column(SQLiteConnection): SQLite implementation using PRAGMA

• .has_column(PqConnection): PostgreSQL implementation using information_schema

• .has_column(MariaDBConnection): MySQL/MariaDB implementation using information_schema

• .has_column(`Microsoft SQL Server`): SQL Server implementation using information_schema

• .has_column(duckdb_connection): DuckDB implementation using information_schema

• .has_column(default): Default implementation for unknown database types

Examples

if (FALSE) {
conn <- connection_get("my_db")
has_deleted_at <- .has_column(conn, "users", "deleted_at")
DBI::dbDisconnect(conn)
}

List all columns in a table (S3 generic)

Description

Cross-database method to list all columns in a table. Uses database-specific introspection methods via S3 dispatch.

Usage

.list_columns(conn, table_name)

## S3 method for class 'SQLiteConnection'
.list_columns(conn, table_name)

## S3 method for class 'PqConnection'
.list_columns(conn, table_name)

## S3 method for class 'MariaDBConnection'
.list_columns(conn, table_name)

## S3 method for class ''Microsoft SQL Server''
.list_columns(conn, table_name)

## S3 method for class 'duckdb_connection'
.list_columns(conn, table_name)

## Default S3 method:
.list_columns(conn, table_name)

Arguments

Value

Character vector of column names

Functions

• .list_columns(SQLiteConnection): SQLite implementation using PRAGMA

• .list_columns(PqConnection): PostgreSQL implementation using information_schema

• .list_columns(MariaDBConnection): MySQL/MariaDB implementation using information_schema

• .list_columns(`Microsoft SQL Server`): SQL Server implementation using information_schema

• .list_columns(duckdb_connection): DuckDB implementation using information_schema

• .list_columns(default): Default implementation using information_schema

Examples

if (FALSE) {
conn <- connection_get("my_db")
columns <- .list_columns(conn, "users")
DBI::dbDisconnect(conn)
}

List all tables in a database (S3 generic)

Description

Cross-database method to list all tables. Uses database-specific methods via S3 dispatch.

Usage

.list_tables(conn)

## Default S3 method:
.list_tables(conn)

Arguments

Value

Character vector of table names

Functions

• .list_tables(default): Default implementation using DBI::dbListTables

Examples

if (FALSE) {
conn <- connection_get("my_db")
tables <- .list_tables(conn)
DBI::dbDisconnect(conn)
}

Clear R environment

Description

Cleans up the R environment by removing objects, closing plots, detaching packages, and running garbage collection. Does not clear the console.

Usage

env_clear(keep = character(), envir)

Arguments

Value

Invisibly returns NULL

Examples

if (FALSE) {
# Clean a specific environment
env_clear(envir = my_env)

# Keep specific objects
env_clear(keep = c("config", "data"), envir = my_env)
}

Default Framework .env template lines

Description

Provides the baseline .env content that ships with Framework. Other helper functions (project_create(), GUI scaffolders) reuse these lines when users haven't customized their own template.

Usage

env_default_template_lines()

Convert env() configuration into file lines

Description

Convert env() configuration into file lines

Usage

env_lines_from_variables(vars)

Resolve env template lines from configuration

Description

Resolve env template lines from configuration

Usage

env_resolve_lines(env_config = NULL)

Arguments

Value

Character vector of lines ready to be written to .env

Summarize R environment

Description

Displays a summary of the current R environment including loaded packages, objects in the global environment, and memory usage.

Usage

env_summary(envir)

Arguments

Value

Invisibly returns a list with environment information

Examples

if (FALSE) {
env_summary(envir = my_env)
}

Get the user-editable path for a Framework template

Description

Get the user-editable path for a Framework template

Usage

framework_template_path(name)

Arguments

Value

Absolute path to the template file, ensuring it exists.

(Deprecated) Use view_create() or view_detail() instead

Description

framework_view() was renamed to view_create() to follow the package's noun_verb naming convention for better discoverability and consistency.

Recommended: Use view_detail() for the clearest, most user-friendly name.

Usage

framework_view(x, title = NULL, max_rows = 5000)

Arguments

Value

Opens a browser window (called for side effects)

Get Framework config directory path

Description

Returns the path to Framework's global configuration directory. Uses tools::R_user_dir("framework", "config") by default (CRAN compliant). Can be overridden with the FW_CONFIG_HOME environment variable.

Usage

fw_config_dir()

Value

Character string with the config directory path

Get default global configuration structure

Description

Get default global configuration structure

Usage

get_default_global_config()

Value

List with default global configuration

Get Global Configuration Setting

Description

Retrieve a specific setting from the global configuration file (~/.frameworkrc.json). This is a helper function primarily for use by the CLI script.

Usage

get_global_setting(key, default = "", print = TRUE)

Arguments

Value

The setting value as a character string

Stage Files for Commit

Description

Add file contents to the staging area.

Usage

git_add(files = ".")

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
git_add()              # Stage all changes
git_add("README.md")   # Stage specific file
git_add(c("R/foo.R", "R/bar.R"))
}

Commit Staged Changes

Description

Record changes to the repository with a commit message.

Usage

git_commit(message, all = FALSE)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
git_commit("Fix bug in data loading")
git_commit("Update README", all = TRUE)  # Stage and commit
}

Show Changes (Diff)

Description

Show changes between commits, working tree, etc.

Usage

git_diff(staged = FALSE, file = NULL)

Arguments

Value

Invisibly returns the diff output as a character vector

Examples

if (FALSE) {
git_diff()             # Show unstaged changes
git_diff(staged = TRUE) # Show staged changes
git_diff(file = "R/foo.R")
}

Disable Specific Git Hook

Description

Disables a specific hook in settings and reinstalls the pre-commit hook.

Usage

git_hooks_disable(hook_name, config_file = NULL, verbose = TRUE)

Arguments

Value

Invisible TRUE on success

Enable Specific Git Hook

Description

Enables a specific hook in settings and reinstalls the pre-commit hook.

Usage

git_hooks_enable(hook_name, config_file = NULL, verbose = TRUE)

Arguments

Value

Invisible TRUE on success

Examples

if (FALSE) {
git_hooks_enable("ai_sync")
git_hooks_enable("data_security")
}

Install Git Pre-commit Hook

Description

Creates a pre-commit hook that runs Framework checks based on settings.yml settings.

Usage

git_hooks_install(config_file = NULL, force = FALSE, verbose = TRUE)

Arguments

Details

Creates or updates .git/hooks/pre-commit to run enabled Framework hooks:

• ai_sync: Sync AI assistant context files before commit

• data_security: Run security audit to catch data leaks

• check_sensitive_dirs: Warn about unignored sensitive directories

Hook behavior is controlled by ⁠git.hooks.*⁠ settings in settings.yml.

Value

Invisible TRUE on success, FALSE on failure

Examples

if (FALSE) {
# Install hooks based on settings.yml
git_hooks_install()

# Force reinstall (overwrites existing hook)
git_hooks_install(force = TRUE)
}

List Git Hook Status

Description

Shows which hooks are enabled and their current status.

Usage

git_hooks_list(config_file = NULL)

Arguments

Value

Data frame with hook information

Uninstall Git Pre-commit Hook

Description

Removes the Framework-managed pre-commit hook.

Usage

git_hooks_uninstall(verbose = TRUE)

Arguments

Value

Invisible TRUE if hook was removed, FALSE otherwise

Show Commit Log

Description

Show recent commit history.

Usage

git_log(n = 10, oneline = TRUE)

Arguments

Value

Invisibly returns the log output as a character vector

Examples

if (FALSE) {
git_log()
git_log(n = 5)
git_log(oneline = FALSE)  # Full format
}

Pull from Remote

Description

Fetch and integrate changes from the remote repository.

Usage

git_pull(remote = "origin", branch = NULL)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
git_pull()
git_pull(remote = "origin", branch = "main")
}

Push to Remote

Description

Push commits to the remote repository.

Usage

git_push(remote = "origin", branch = NULL)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
git_push()
git_push(remote = "origin", branch = "main")
}

Security audit for Framework projects

Description

Performs a comprehensive security audit of data files in Framework projects, checking for unignored data files, git history leaks, and orphaned data files outside configured directories.

Usage

git_security_audit(
  config_file = NULL,
  check_git_history = TRUE,
  history_depth = "all",
  auto_fix = FALSE,
  verbose = TRUE,
  extensions = c("csv", "rds", "tsv", "txt", "dat", "xlsx", "xls", "sqlite", "db", "dta",
    "sav", "zsav", "por", "sas7bdat", "sas7bcat", "xpt", "parquet", "feather", "arrow",
    "json", "xml", "h5", "hdf5")
)

Arguments

Details

The security audit performs the following checks:

• gitignore_coverage: Verifies all private data files are in .gitignore

• git_history: Scans git history for accidentally committed data files

• orphaned_files: Finds data files outside configured directories

• private_data_exposure: Checks if private data is tracked by git

Status levels:

• pass: No issues found

• warning: Potential issues that should be reviewed

• fail: Critical security issues requiring immediate action

Value

A structured list containing:

summary

Data frame with check names, status (pass/warning/fail), and counts

findings

List of data frames with detailed findings for each check

recommendations

Character vector of actionable recommendations

audit_metadata

List with audit timestamp, Framework version, and config info

Examples

if (FALSE) {
# Basic audit (report only)
audit <- git_security_audit()
print(audit$summary)
View(audit$findings$orphaned_files)

# Quick scan without git history
audit <- git_security_audit(check_git_history = FALSE)

# Verbose with limited git history
audit <- git_security_audit(history_depth = 100, verbose = TRUE)

# Auto-fix mode (updates .gitignore)
audit <- git_security_audit(auto_fix = TRUE)
}

Show Git Status

Description

Display the working tree status from the R console.

Usage

git_status(short = FALSE)

Arguments

Value

Invisibly returns the status output as a character vector

Examples

if (FALSE) {
git_status()
git_status(short = TRUE)
}

Launch Framework GUI

Description

Opens a beautiful web-based interface for Framework with documentation, project management, and settings configuration.

Usage

gui(port = 8080, host = "127.0.0.1", browse = TRUE, route = NULL)

Arguments

Value

Invisibly returns the plumber server object

See Also

setup() for first-time configuration

Examples

if (FALSE) {
# Launch the GUI
framework::gui()

# Launch on specific port
framework::gui(port = 8888)

# Open directly to settings
framework::gui(route = "#/settings/basics")

# Run as standalone server (no browser, accessible from network)
framework::gui(port = 8080, host = "0.0.0.0", browse = FALSE)
}

Initialize global Framework settings

Description

Creates the Framework config directory (via fw_config_dir()) and copies default settings files if they don't already exist. Also handles migration from previous R versions or legacy ⁠~/.config/framework⁠ location.

Usage

init_global_config(force = FALSE)

Arguments

Value

Invisibly returns NULL

List available framework templates

Description

List available framework templates

Usage

list_framework_templates()

List all metadata

Description

List all metadata

Usage

list_metadata()

Value

A data frame of metadata with keys, values, and timestamps

Read the Framework settings catalog

Description

The catalog defines metadata (labels, hints) and default values for settings sections. Users can override the packaged defaults by placing a settings-catalog.yml file in their Framework config directory (tools::R_user_dir("framework", "config")). When an override exists it is merged on top of the packaged catalog.

Usage

load_settings_catalog(include_user = TRUE, validate = TRUE)

Arguments

Value

A nested list representing the settings catalog.

Create a Notebook or Script from Stub Template

Description

Creates a new Quarto (.qmd), RMarkdown (.Rmd) notebook, or R script (.R) from stub templates. Searches for user-provided stubs first (in ⁠stubs/⁠ directory), then falls back to framework defaults.

Usage

make_notebook(
  name,
  type = NULL,
  dir = NULL,
  stub = "default",
  overwrite = FALSE,
  subdir = NULL
)

Arguments

Details

Convenient aliases: Use make_qmd() or make_rmd() for explicit Quarto or RMarkdown notebook creation. Use make_revealjs() or make_presentation() for reveal.js presentations.

Default Output

Notebooks are created in the ⁠notebooks/⁠ directory by default:

notebooks/
  1-data-cleaning.qmd
  2-analysis.qmd
  3-visualization.qmd

Extension Normalization

• If name includes .qmd or .Rmd, type is auto-detected

• If no extension provided, .qmd is used (Quarto-first)

• Use type = "rmarkdown" to default to .Rmd

Stub Template Resolution

The function searches for stub templates in this order:

1. User stubs: ⁠stubs/notebook-{stub}.qmd⁠ or ⁠stubs/notebook-{stub}.Rmd⁠

2. Framework stubs: ⁠inst/stubs/notebook-{stub}.qmd⁠ or ⁠inst/stubs/notebook-{stub}.Rmd⁠

Custom stub templates can use placeholders:

• {filename} - The notebook filename without extension

• {date} - Current date (YYYY-MM-DD)

Value

Invisible path to created notebook

See Also

make_qmd(), make_rmd(), make_revealjs(), make_presentation()

Examples

if (FALSE) {
# Create notebooks/1-init.qmd (defaults to Quarto)
make_notebook("1-init")

# Create notebooks/analysis.Rmd (RMarkdown, extension-based)
make_notebook("analysis.Rmd")

# Explicit type parameter
make_notebook("report", type = "rmarkdown")

# Use custom stub template
make_notebook("report", stub = "minimal")

# Create in specific directory
make_notebook("explore", dir = "work")

# Convenient aliases (recommended for explicit types)
make_qmd("analysis")       # Always creates .qmd
make_rmd("report")         # Always creates .Rmd
make_revealjs("slides")    # Creates reveal.js presentation
make_presentation("deck")  # Alias for make_revealjs()
}

Create a Presentation

Description

Alias for make_revealjs(). Creates a Quarto reveal.js presentation.

Usage

make_presentation(name, dir = NULL, overwrite = FALSE, subdir = NULL)

Arguments

Value

Invisible path to created presentation

See Also

make_notebook(), make_revealjs()

Examples

if (FALSE) {
# Create notebooks/deck.qmd with reveal.js format
make_presentation("deck")
}

Create a Quarto Notebook

Description

Convenient alias for make_notebook(type = "quarto"). Creates a .qmd file from stub templates.

Usage

make_qmd(name, dir = NULL, stub = "default", overwrite = FALSE, subdir = NULL)

Arguments

Value

Invisible path to created notebook

See Also

make_notebook(), make_rmd()

Examples

if (FALSE) {
# Create notebooks/analysis.qmd
make_qmd("analysis")

# Use custom stub
make_qmd("report", stub = "minimal")

# Create in specific directory
make_qmd("explore", dir = "work")
}

Create a Reveal.js Presentation

Description

Convenient alias for creating reveal.js presentations. Always creates a Quarto notebook with the revealjs stub template.

Usage

make_revealjs(name, dir = NULL, overwrite = FALSE, subdir = NULL)

Arguments

Value

Invisible path to created presentation

See Also

make_notebook(), make_qmd(), make_presentation()

Examples

if (FALSE) {
# Create notebooks/slides.qmd with reveal.js format
make_revealjs("slides")

# Create in specific directory
make_revealjs("presentation", dir = "presentations")
}

Create an RMarkdown Notebook

Description

Convenient alias for make_notebook(type = "rmarkdown"). Creates a .Rmd file from stub templates.

Usage

make_rmd(name, dir = NULL, stub = "default", overwrite = FALSE, subdir = NULL)

Arguments

Value

Invisible path to created notebook

See Also

make_notebook(), make_qmd()

Examples

if (FALSE) {
# Create notebooks/analysis.Rmd
make_rmd("analysis")

# Use custom stub
make_rmd("report", stub = "minimal")

# Create in specific directory
make_rmd("explore", dir = "work")
}

Create an R Script from Stub Template

Description

Convenience wrapper for make_notebook() that creates R scripts (.R files). This is identical to calling make_notebook("name.R").

Usage

make_script(name, dir = NULL, stub = "default", overwrite = FALSE)

Arguments

Details

This function is a convenience wrapper that:

1. Ensures the name ends with .R extension

2. Uses script_dir config option instead of notebook_dir

3. Calls make_notebook() with type = "script"

Default Output

Scripts are created in the ⁠scripts/⁠ directory by default:

scripts/
  process-data.R
  build-features.R
  run-model.R

Value

Invisible path to created script

See Also

make_notebook() for creating Quarto/RMarkdown notebooks

Examples

if (FALSE) {
# Create script (extension optional)
make_script("process-data")
make_script("process-data.R")

# Use custom stub
make_script("etl-pipeline", stub = "etl")

# Create in specific directory
make_script("analysis", dir = "analysis/")
}

Create a New Project (Master Wrapper)

Description

Flexible project creation interface. Alias for new_project() that accepts type as a parameter.

Usage

new(
  name = NULL,
  location = NULL,
  type = "project",
  browse = interactive(),
  ...
)

Arguments

Value

Invisibly returns the result from project_create()

See Also

new_project(), new_project_sensitive(), new_presentation(), new_course()

Examples

if (FALSE) {
# Create different project types
new("analysis", "~/projects/analysis")
new("study", "~/projects/study", type = "project_sensitive")
new("slides", "~/projects/slides", type = "presentation")
new("course-materials", "~/projects/course", type = "course")
}

Create a Course Project

Description

Shorthand for new_project(..., type = "course"). Creates a project structured for teaching materials with slides, assignments, and modules.

Usage

new_course(name = NULL, location = NULL, browse = interactive(), ...)

Arguments

Value

Invisibly returns the result from project_create()

See Also

new_project()

Examples

if (FALSE) {
new_course("stats-101", "~/projects/stats-101")
}

Create a Presentation Project

Description

Shorthand for new_project(..., type = "presentation"). Creates a project optimized for RevealJS presentations.

Usage

new_presentation(name = NULL, location = NULL, browse = interactive(), ...)

Arguments

Value

Invisibly returns the result from project_create()

See Also

new_project()

Examples

if (FALSE) {
new_presentation("quarterly-review", "~/projects/q4-review")
}

Create a New Framework Project

Description

Convenience wrapper for creating Framework projects from the command line. Uses global settings configured via setup() as defaults, prompts for missing required values (name and location).

Usage

new_project(
  name = NULL,
  location = NULL,
  type = "project",
  browse = interactive(),
  ...
)

Arguments

Details

This function is designed for the streamlined workflow:

remotes::install_github("table1/framework")
framework::setup()        # One-time global configuration
framework::new_project()  # Create projects using saved defaults

Global settings from tools::R_user_dir("framework", "config") are used for:

• Author information (name, email, affiliation

• Default packages

• Directory structure

• Git settings

• AI assistant configuration

• Quarto format preferences

Value

Invisibly returns the result from project_create() (list with success, path, and project_id)

See Also

setup() for initial configuration, project_create() for full control

Examples

if (FALSE) {
# Interactive - prompts for name and location
new_project()

# With name and location specified
new_project("my-analysis", "~/projects/my-analysis")

# Create a sensitive data project
new_project("medical-study", "~/projects/medical", type = "project_sensitive")
}

Create a Sensitive Data Project

Description

Shorthand for new_project(..., type = "project_sensitive"). Creates a project with additional privacy protections for handling sensitive data.

Usage

new_project_sensitive(
  name = NULL,
  location = NULL,
  browse = interactive(),
  ...
)

Arguments

Value

Invisibly returns the result from project_create()

See Also

new_project()

Examples

if (FALSE) {
new_project_sensitive("medical-study", "~/projects/medical")
}

Get current datetime

Description

Get current datetime

Usage

now()

Value

Current datetime as an ISO 8601 formatted character string

Output Save Functions

Description

First-class functions for saving tables, figures, models, and reports. These functions implement lazy directory creation with console feedback.

Install packages from configuration

Description

Installs all packages defined in the configuration that are not already installed. This is the same logic used in scaffold(), but exposed as a standalone function.

Usage

packages_install()

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
# Install all configured packages
packages_install()
}

List all packages from configuration

Description

Lists all packages defined in the configuration, showing the package name, version pin (if specified), and source (CRAN or GitHub).

Usage

packages_list()

Value

Invisibly returns NULL after printing package list

Examples

if (FALSE) {
# List all packages
packages_list()
}

Restore packages from renv.lock

Description

Wrapper around renv::restore() that requires Framework's renv integration to be enabled first.

Usage

packages_restore(prompt = FALSE)

Arguments

Value

Invisibly returns TRUE on success.

Snapshot current package library (renv)

Description

Wrapper around renv::snapshot() that requires Framework's renv integration to be enabled first.

Usage

packages_snapshot(prompt = FALSE)

Arguments

Value

Invisibly returns TRUE on success.

Show renv package status

Description

Wrapper around renv::status() that requires Framework's renv integration.

Usage

packages_status()

Value

The status object returned by renv::status().

Update packages from configuration

Description

Updates packages defined in the configuration. If renv is enabled, uses renv::update(). Otherwise, reinstalls packages using standard installation methods.

Usage

packages_update(packages = NULL)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
# Update all packages
packages_update()

# Update specific packages
packages_update(c("dplyr", "ggplot2"))
}

Add custom directories to an existing project

Description

Adds new directories to a project's configuration and creates them on the filesystem. This function is used by the GUI to allow users to add custom directories to their project structure without modifying existing directories.

Usage

project_add_directory(project_path, key, label, path)

Arguments

Details

This function performs the following steps:

1. Validates all input arguments

2. Reads the project's config.yml file

3. Checks for duplicate keys in existing directories

4. Adds the new directory to the directories section

5. Writes the updated config.yml back to disk

6. Creates the directory on the filesystem (with recursive creation)

The function follows a non-destructive, additive-only approach. It will not:

• Rename existing directories

• Delete existing directories

• Modify existing directory paths

• Change the project type

Value

List with success status and directory information:

• success: Logical indicating whether the operation succeeded

• directory: List containing key, label, path, absolute_path, and created flag

• error: Character string with error message (only present if success is FALSE)

Safety

The function includes several safety checks:

• Rejects absolute paths (must be relative)

• Rejects paths containing ".." (no directory traversal)

• Checks for duplicate keys before adding

• Wraps filesystem operations in error handling

Create a new Framework project (internal)

Description

Low-level function that creates a complete Framework project. This is called by the GUI and by user-facing functions like new() and new_project(). Users should typically use new() instead.

Usage

project_create(
  name,
  location,
  type = "project",
  author = list(name = "", email = "", affiliation = ""),
  packages = list(use_renv = FALSE, default_packages = list()),
  directories = list(),
  extra_directories = list(),
  ai = list(enabled = FALSE, assistants = c(), canonical_content = ""),
  git = list(use_git = TRUE, hooks = list(), gitignore_content = ""),
  scaffold = list(seed_on_scaffold = FALSE, seed = "", set_theme_on_scaffold = TRUE,
    ggplot_theme = "theme_minimal"),
  connections = NULL,
  env = NULL,
  quarto = NULL,
  render_dirs = NULL
)

Arguments

Value

List with success status, project path, and project ID

Display project structure information

Description

Shows configured directories and their status (created or pending lazy creation). Useful for understanding the project structure and discovering available paths.

Usage

project_info(verbose = FALSE)

Arguments

Value

A data frame with directory information (invisibly)

Examples

if (FALSE) {
# Show project structure
project_info()

# Get detailed info
project_info(verbose = TRUE)
}

List all projects in global configuration

Description

List all projects in global configuration

Usage

project_list()

Value

Data frame with project information

Publishing Functions

Description

Functions for publishing notebooks, data, and files to S3 storage.

Upload files or directories to an S3 bucket. This is the generic publishing function - use publish_notebook() for Quarto documents or publish_data() for data files.

Usage

publish(source, dest = NULL, connection = NULL, overwrite = TRUE)

Arguments

Value

Character. The public URL(s) of uploaded file(s).

Examples

if (FALSE) {
# Upload a single file
publish("outputs/report.html")
# -> https://bucket.s3.region.amazonaws.com/prefix/report.html

# Upload with custom destination
publish("outputs/report.html", dest = "reports/q4-2024.html")

# Upload a directory
publish("outputs/charts/", dest = "reports/charts/")

# Use specific connection
publish("data.csv", connection = "s3_backup")
}

Publish data to S3

Description

Uploads a data frame or existing data file to S3.

Usage

publish_data(data, dest, format = "csv", connection = NULL, compress = FALSE)

Arguments

Value

Character. Public URL of the published data.

Examples

if (FALSE) {
# Publish a data frame
publish_data(my_df, "datasets/customers.csv")

# Publish as RDS
publish_data(my_df, "datasets/customers.rds", format = "rds")

# Publish existing file
publish_data("outputs/model.rds", "models/v2/model.rds")
}

Publish a directory to S3

Description

Recursively uploads all files in a directory to S3.

Usage

publish_dir(
  dir,
  dest = NULL,
  connection = NULL,
  pattern = NULL,
  recursive = TRUE
)

Arguments

Value

Character vector. Public URLs of uploaded files.

Examples

if (FALSE) {
# Upload entire directory
publish_dir("outputs/dashboard/")

# Upload to specific location
publish_dir("outputs/dashboard/", dest = "dashboards/v2/")

# Upload only HTML files
publish_dir("outputs/", pattern = "\\.html$")
}

List published files in S3

Description

Lists files in an S3 bucket/prefix.

Usage

publish_list(prefix = NULL, connection = NULL, max = 1000L)

Arguments

Value

Data frame with columns: key, size, last_modified.

Examples

if (FALSE) {
# List all published files
publish_list()

# List files under a prefix
publish_list("reports/")

# List from specific connection
publish_list(connection = "s3_backup")
}

Publish a Quarto notebook to S3

Description

Renders a Quarto document and uploads it to S3. The notebook is rendered to a temporary directory, uploaded, then cleaned up.

Usage

publish_notebook(
  file,
  dest = NULL,
  connection = NULL,
  self_contained = TRUE,
  format = "html",
  ...
)

Arguments

Details

The URL format depends on the S3 connection's static_hosting setting:

• static_hosting: true -> uploads to dest/index.html, returns ⁠dest/⁠

• static_hosting: false (default) -> uploads as dest.html, returns dest.html

Value

Character. Public URL of the published notebook.

Examples

if (FALSE) {
# With static_hosting: true -> returns /analysis/
# With static_hosting: false -> returns /analysis.html
publish_notebook("notebooks/analysis.qmd")

# Publish to specific location
publish_notebook("notebooks/analysis.qmd", dest = "reports/2024/q4")

# Publish non-self-contained (only with static_hosting: true)
publish_notebook("notebooks/analysis.qmd", self_contained = FALSE)
}

Generate Quarto Configurations for Project

Description

Main entry point for generating all ⁠_quarto.yml⁠ files in a project. Generates root config and directory-specific configs based on project type.

Usage

quarto_generate_all(
  project_path,
  project_type,
  render_dirs = NULL,
  quarto_settings = NULL,
  directories = NULL,
  root_output_dir = NULL
)

Arguments

Value

List with success status and paths of generated files

Regenerate Quarto Configurations

Description

Regenerates all ⁠_quarto.yml⁠ files in a project. WARNING: This will overwrite any manual edits. Should only be called when user explicitly requests regeneration.

Usage

quarto_regenerate(project_path, backup = TRUE)

Arguments

Value

List with success status, backed up files, and regenerated files

Read the contents of a Framework template

Description

Read the contents of a Framework template

Usage

read_framework_template(name)

Arguments

Value

Character scalar containing template contents

Read global Framework configuration

Description

Read global Framework configuration

Usage

read_frameworkrc(use_defaults = TRUE)

Arguments

Value

List containing global configuration

Remove project from global configuration

Description

Remove project from global configuration

Usage

remove_project_from_config(project_id)

Arguments

Value

Invisibly returns NULL

Disable renv for this project

Description

Deactivates renv integration while preserving renv.lock for future use. Removes the .framework_renv_enabled marker file.

Usage

renv_disable(keep_renv = TRUE)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
renv_disable()
}

Enable renv for this project

Description

Initializes renv integration for the current Framework project. This:

• Creates .framework_renv_enabled marker file

• Initializes renv if not already initialized

• Syncs packages from settings.yml to renv.lock

• Updates .gitignore to exclude renv cache

Usage

renv_enable(sync = TRUE)

Arguments

Value

Invisibly returns TRUE on success

Examples

if (FALSE) {
renv_enable()
}

Check if renv is enabled for this project

Description

Determines whether renv integration is active by checking for the .framework_renv_enabled marker file in the project root.

Usage

renv_enabled()

Value

Logical indicating whether renv is enabled

Examples

if (renv_enabled()) {
  message("Using renv for package management")
}

Restore packages from renv.lock

Description

Internal wrapper around renv::restore(). Use packages_restore() instead.

Usage

renv_restore(prompt = FALSE)

Arguments

Value

Invisibly returns TRUE on success

Snapshot current package versions to renv.lock

Description

Internal wrapper around renv::snapshot(). Use packages_snapshot() instead.

Usage

renv_snapshot(prompt = FALSE)

Arguments

Value

Invisibly returns TRUE on success

Show package status

Description

Internal wrapper around renv::status(). Use packages_status() instead.

Usage

renv_status()

Value

Invisibly returns the status object from renv::status()

Sync packages with renv.lock

Description

Internal function that resolves inconsistencies between installed packages and renv.lock by restoring then snapshotting.

Usage

renv_sync(prompt = FALSE)

Arguments

Value

Invisibly returns TRUE on success

Update packages

Description

Internal wrapper around renv::update(). Use packages_update() instead.

Usage

renv_update(packages = NULL)

Arguments

Value

Invisibly returns TRUE on success

Reset a Framework template back to the packaged default

Description

Reset a Framework template back to the packaged default

Usage

reset_framework_template(name)

Arguments

Value

Invisibly returns the file path of the reset template.

List saved results from the framework database

Description

Retrieves a list of all saved results (tables, figures, models, reports, notebooks) that have been tracked via the save_* functions.

Usage

result_list(type = NULL, public = NULL)

Arguments

Value

A data frame with columns: name, type, public, comment, hash, created_at, updated_at. Returns an empty data frame if no results found or database unavailable.

Examples

if (FALSE) {
# List all results
result_list()

# List only tables
result_list(type = "table")

# List only public figures
result_list(type = "figure", public = TRUE)
}

Save a figure to the outputs directory

Description

Saves a ggplot2 plot or base R graphics to the configured figures directory. The directory is created lazily on first use.

Usage

save_figure(
  plot = NULL,
  name,
  format = "png",
  width = 8,
  height = 6,
  dpi = 300,
  public = FALSE,
  overwrite = TRUE,
  ...
)

Arguments

Value

The path to the saved file (invisibly)

Examples

if (FALSE) {
# Save a ggplot
p <- ggplot(mtcars, aes(mpg, hp)) + geom_point()
save_figure(p, "mpg_vs_hp")

# Save as PDF for publication
save_figure(p, "mpg_vs_hp", format = "pdf", width = 10, height = 8)

# Save to public directory
save_figure(p, "summary_plot", public = TRUE)
}

Save a model to the outputs directory

Description

Saves a fitted model object to the configured models directory. The directory is created lazily on first use.

Usage

save_model(model, name, public = FALSE, overwrite = TRUE, ...)

Arguments

Value

The path to the saved file (invisibly)

Examples

if (FALSE) {
# Fit and save a model
model <- lm(mpg ~ hp + wt, data = mtcars)
save_model(model, "mpg_regression")
}

Save a rendered notebook to the outputs directory

Description

Renders a Quarto or R Markdown notebook and saves the output to the configured notebooks output directory. The directory is created lazily on first use.

Usage

save_notebook(
  file,
  name = NULL,
  format = "html",
  public = FALSE,
  overwrite = TRUE,
  embed_resources = TRUE,
  ...
)

Arguments

Value

The path to the saved file (invisibly)

Examples

if (FALSE) {
# Render and save a notebook
save_notebook("notebooks/analysis.qmd")

# Save with a custom name
save_notebook("notebooks/analysis.qmd", name = "final_analysis")

# Render to PDF
save_notebook("notebooks/analysis.qmd", format = "pdf")

# Save to public directory (for sensitive projects)
save_notebook("notebooks/analysis.qmd", public = TRUE)
}

Save a report to the outputs directory

Description

Copies or moves a rendered report (HTML, PDF, etc.) to the configured reports directory. The directory is created lazily on first use.

Usage

save_report(file, name = NULL, public = FALSE, overwrite = TRUE, move = FALSE)

Arguments

Value

The path to the saved file (invisibly)

Examples

if (FALSE) {
# Save a rendered HTML report
save_report("notebooks/analysis.html", "final_analysis")

# Save to public directory
save_report("notebooks/summary.pdf", "public_summary", public = TRUE)
}

Save a table to the outputs directory

Description

Saves a data frame or tibble to the configured tables directory. The directory is created lazily on first use.

Usage

save_table(data, name, format = "csv", public = FALSE, overwrite = TRUE, ...)

Arguments

Value

The path to the saved file (invisibly)

Examples

if (FALSE) {
# Save a simple table
save_table(my_results, "regression_results")

# Save as Excel
save_table(my_results, "regression_results", format = "xlsx")

# Save to public directory (for sensitive projects)
save_table(summary_stats, "summary", public = TRUE)
}

Initialize and load the project environment

Description

The primary entry point for working with Framework projects. Call this at the start of every notebook or script to set up your environment with all configured packages, functions, and settings.

Usage

scaffold(config_file = NULL)

Arguments

Details

scaffold() performs the following steps in order:

1. Standardizes working directory - Finds and sets the project root, even when called from notebooks in subdirectories

2. Loads environment variables - Reads secrets from .env file

3. Loads configuration - Parses settings.yml for project settings

4. Sets random seed - For reproducibility (if seed is configured)

5. Installs packages - Any missing packages from the packages list

6. Loads packages - Attaches all configured packages

7. Sources functions - Loads all .R files from ⁠functions/⁠ directory

After scaffold() completes, you have access to:

• All packages listed in settings.yml

• All functions from your ⁠functions/⁠ directory

• Settings via settings("key") helper function

• Database connections configured in your project

Value

Invisibly returns NULL. The main effects are side effects: loading packages, sourcing functions, and creating the config object.

Project Discovery

When called without arguments, scaffold() searches for a Framework project by:

• Looking for settings.yml or config.yml in current and parent directories

• Checking for .Rproj or .code-workspace files with nearby settings

• Recognizing common Framework subdirectories (notebooks/, scripts/, etc.)

This means you can call scaffold() from any subdirectory within your project.

Configuration

The settings.yml file controls what scaffold() loads. Key settings include:

• packages: List of R packages to install and load

• seed: Random seed for reproducibility

• directories: Custom directory paths

• connections: Database connection configurations

See Also

• project_create() to create a new Framework project

• standardize_wd() for just the working directory standardization

• settings() to access configuration values after scaffolding

Examples

if (FALSE) {
# At the top of every notebook or script:
library(framework)
scaffold()

# Now you can use your configured packages and functions
# Access settings via the settings() helper:
settings("directories.notebooks")
settings("seed")
}

Capture and Save Data to File

Description

Saves data to a file in various formats based on the object type and specified format. If no name is provided, uses the name of the object passed in. If no location is provided, uses the scratch directory from the configuration.

Usage

scratch_capture(x, name = NULL, to = NULL, location = NULL, n = Inf)

Arguments

Value

The input object x invisibly.

Examples

if (FALSE) {
# Save a character vector as text
scratch_capture(c("hello", "world"))

# Save a data frame as TSV
scratch_capture(mtcars)

# Save an R object as RDS
scratch_capture(list(a = 1, b = 2), to = "rds")
}

Clean up the scratch directory by deleting all files

Description

Clean up the scratch directory by deleting all files

Usage

scratch_clean()

Value

Invisibly returns NULL. Called for side effect of removing scratch files.

Get settings value by dot-notation key

Description

Framework's primary configuration helper that supports both flat and hierarchical key access using dot notation. Automatically checks common locations for directory settings. Pretty-prints nested structures in interactive sessions.

Usage

settings(key = NULL, default = NULL, settings_file = NULL)

Arguments

Details

For directory settings, the function checks multiple locations:

• Direct: settings("notebooks") checks directories$notebooks, then options$notebook_dir

• Explicit: settings("directories.notebooks") checks only directories$notebooks

File Discovery:

• Checks settings.yml first (Framework's preferred convention)

• Falls back to settings.yml if settings.yml not found

• You can override with explicit settings_file parameter

Output Behavior:

• Interactive sessions: Pretty-prints nested lists/structures and returns invisibly

• Non-interactive (scripts): Returns raw value without printing

• Simple values: Always returned directly without modification

Value

The settings value, or default if not found. In interactive sessions, nested structures are pretty-printed and returned invisibly.

Examples

if (FALSE) {
# Get notebook directory (checks both locations)
settings("notebooks")

# Get explicit nested setting
settings("directories.notebooks")
settings("connections.db.host")

# Get entire section
settings("directories")  # Returns all directory settings
settings("connections")  # Returns all connection settings

# View entire settings
settings()  # Returns full configuration

# With default value
settings("missing_key", default = "fallback")
}

Read project settings

Description

Reads the project settings from settings.yml or config.yml with environment-aware merging and split file resolution. Auto-discovers the settings file if not specified.

Usage

settings_read(settings_file = NULL, environment = NULL)

Arguments

Value

The settings as a list

Write project settings

Description

Writes the project settings to settings.yml or config files

Usage

settings_write(settings, settings_file = NULL, section = NULL)

Arguments

Value

Invisibly returns NULL.

Setup Framework (First-Time Configuration)

Description

Initializes Framework's global configuration and launches the GUI for first-time setup. This is the recommended entry point for new users.

Usage

setup(port = 8080, browse = TRUE)

Arguments

Details

Use this function after installing Framework to:

• Set your author name and email

• Configure default packages for new projects

• Set IDE preferences (VS Code, RStudio)

• Configure other global defaults

Value

Invisibly returns the plumber server object

See Also

gui() for launching the GUI without initialization check

Examples

if (FALSE) {
# First-time setup
framework::setup()
}

Standardize Working Directory for Framework Projects

Description

This function helps standardize the working directory when working with framework projects, especially useful in Quarto/RMarkdown documents that may be rendered from subdirectories.

Usage

standardize_wd(project_root = NULL)

Arguments

Details

The function looks for common framework project indicators:

• settings.yml or settings.yml file

• .Rprofile file

• Being in common subdirectories (scratch, work)

It sets both the regular working directory and knitr's root.dir option if knitr is available.

Value

Invisibly returns the standardized project root path.

Examples

if (FALSE) {
library(framework)
standardize_wd()
scaffold()
}

Show Framework project status

Description

Displays comprehensive information about the current Framework project including:

• Framework package version

• Project configuration

• Git status

• AI assistant configuration

• Git hooks status

• Package dependencies

• Directory structure

Usage

status()

Value

No return value, called for side effect of printing project status.

Examples

if (FALSE) {
status()
}

Test storage connection

Description

Validates that S3/storage credentials and bucket access are working.

Usage

storage_test(connection = NULL)

Arguments

Value

Logical. TRUE if connection is valid.

Examples

if (FALSE) {
# Test default storage connection
storage_test()

# Test specific connection
storage_test("my_s3_backup")
}

List Available Stubs

Description

Shows all available stub templates that can be used with make_notebook().

Usage

stubs_list(type = NULL)

Arguments

Value

Data frame with columns: name, type, source (user/framework)

Examples

if (FALSE) {
# List all stubs
stubs_list()

# List only Quarto stubs
stubs_list("quarto")

# List only script stubs
stubs_list("script")
}

Get Path to Stub Templates Directory

Description

Returns the path to the user's stubs directory, or the framework stubs directory if no user stubs exist.

Usage

stubs_path(which = "auto")

Arguments

Value

Character path to stubs directory

Examples

if (FALSE) {
# Get active stubs directory
stubs_path()

# Get framework stubs directory
stubs_path("framework")

# Get user stubs directory
stubs_path("user")
}

Publish Stub Templates for Customization

Description

Copies framework stub templates to your project's ⁠stubs/⁠ directory, allowing you to customize them. Similar to Laravel's ⁠artisan vendor:publish⁠ command.

Usage

stubs_publish(type = "all", overwrite = FALSE, stubs = NULL)

Arguments

Details

Stub Customization Workflow

1. Publish stubs to your project: stubs_publish()

2. Edit stubs in ⁠stubs/⁠ directory to match your preferences

3. Use make_notebook() or make_script() - your custom stubs are used automatically

Stub Naming Convention

Stubs follow this naming pattern:

• Notebooks: ⁠stubs/notebook-{name}.qmd⁠ or ⁠stubs/notebook-{name}.Rmd⁠

• Scripts: ⁠stubs/script-{name}.R⁠

Framework searches user stubs first, then falls back to built-in stubs.

Available Placeholders

Stubs can use these placeholders:

• {filename} - File name without extension

• {date} - Current date (YYYY-MM-DD)

Value

Invisible list of published file paths

See Also

make_notebook(), make_script(), stubs_list(), stubs_path()

Examples

if (FALSE) {
# Publish all stubs
stubs_publish()

# Publish only notebook stubs
stubs_publish("notebooks")

# Publish specific stub
stubs_publish(stubs = "default")

# Overwrite existing stubs
stubs_publish(overwrite = TRUE)
}

View data in an interactive browser viewer

Description

Opens an interactive, browser-based viewer for R objects. This is the primary function for viewing data frames, plots, lists, and other R objects with enhanced formatting.

Usage

view(x, title = NULL, max_rows = 5000)

Arguments

Value

Invisibly returns NULL. Opens a browser window.

Examples

if (FALSE) {
# View a data frame
view(mtcars)

# View with a title
view(iris, title = "Iris Dataset")

# View a ggplot
library(ggplot2)
p <- ggplot(mtcars, aes(mpg, hp)) + geom_point()
view(p)
}

Create an enhanced view of R objects in the browser

Description

Opens an interactive, browser-based viewer for R objects with syntax highlighting, tabbed interfaces, and enhanced data table support. Handles data frames, plots, lists, functions, and more with appropriate rendering for each type.

Usage

view_create(x, title = NULL, max_rows = 5000)

Arguments

Value

Invisibly returns NULL. Function is called for its side effect of opening a browser window with the rendered view.

View data with enhanced browser-based interface

Description

Opens an interactive, browser-based viewer for R objects with search, filtering, sorting, pagination, and export capabilities (CSV/Excel). Provides a rich DataTables interface for data frames and enhanced views for plots, lists, and other R objects. This is the recommended function for exploring data in detail.

Usage

view_detail(x, title = NULL, max_rows = 5000)

Arguments

Details

Unlike R's built-in View(), this function:

• Works consistently across all IDEs (VS Code, RStudio, Positron, terminal)

• Provides search and column filtering

• Allows export to CSV and Excel

• Offers sorting and pagination

• Respects IDE-native viewers (doesn't override them)

Value

Invisibly returns NULL. Function is called for its side effect of opening a browser window with the rendered view.

See Also

view

Overwrite a Framework template with new contents

Description

Overwrite a Framework template with new contents

Usage

write_framework_template(name, contents)

Arguments

Value

Invisibly returns the file path of the written template.

Write global Framework configuration

Description

Write global Framework configuration

Usage

write_frameworkrc(config)

Arguments

Value

Invisibly returns NULL