Internal Functions Guide for Developers

Introduction

This vignette documents the internal functions of the boilerplate package. These functions are not exported but are essential for understanding the package’s architecture and contributing to its development.

Core Database Operations

`get_nested_folder()`

Retrieves a nested folder from the database using dot notation paths.

# Internal function in utilities.R
get_nested_folder(db, path)

Parameters: - db: The database list structure - path: Dot-separated path (e.g., “methods.statistical.lmtp”)

Returns: The nested content at the specified path, or NULL if not found

Usage: This function is the core navigation mechanism used by most exported functions to traverse the hierarchical database structure.

`modify_nested_entry()`

Adds, updates, or removes entries in nested database structures.

# Internal function in utilities.R
modify_nested_entry(db, path, value, overwrite = FALSE, remove = FALSE)

Parameters: - db: The database to modify - path: Dot-separated path to the entry - value: New value (ignored if removing) - overwrite: Whether to overwrite existing entries - remove: Whether to remove the entry

Returns: Modified database

Usage: Core function for all database modification operations. Used by boilerplate_add_entry(), boilerplate_update_entry(), and boilerplate_remove_entry().

Database Utilities

`sort_db_recursive()`

Recursively sorts database entries alphabetically by key.

# Internal function in utilities.R
sort_db_recursive(db)

Parameters: - db: Database to sort

Returns: Sorted database

Usage: Ensures consistent ordering of database entries for reproducibility and easier navigation.

`merge_recursive_lists()`

Deep merges two list structures, handling conflicts.

# Internal function in utilities.R
merge_recursive_lists(old_list, new_list, overwrite = FALSE)

Parameters: - old_list: Base list structure - new_list: List to merge in - overwrite: How to handle conflicts

Returns: Merged list

Usage: Used in database merging operations and imports.

Template System

`apply_template_vars()`

Substitutes template variables in text using {{variable}} syntax.

# Internal function in utilities.R
apply_template_vars(text, vars_list, category = NULL)

Parameters: - text: Text containing {{variables}} - vars_list: Named list of variable substitutions - category: Optional category for section-specific variables

Returns: Text with variables substituted

Usage: Core of the template system. Handles both global and section-specific variable substitution.

Example:

text <- "We analysed {{n}} participants using {{method}}."
vars <- list(n = 100, method = "regression")
apply_template_vars(text, vars)
# Returns: "We analysed 100 participants using regression."

File I/O Operations

`get_db_file_path()`

Constructs standardised file paths for database files.

# Internal function in utilities.R
get_db_file_path(category, path_data, timestamp = TRUE)

Parameters: - category: Database category (e.g., “methods”, “measures”) - path_data: Base path for data storage - timestamp: Whether to include timestamp

Returns: Standardised file path

Usage: Ensures consistent file naming across the package.

`read_boilerplate_db()`

Reads database from JSON or RDS format.

# Internal function in json-support.R
read_boilerplate_db(file)

Parameters: - file: Path to database file

Returns: Database structure

Usage: Handles both legacy RDS and modern JSON formats transparently.

`write_boilerplate_db()`

Writes database to JSON or RDS format.

# Internal function in json-support.R
write_boilerplate_db(db, file, format = c("auto", "json", "rds"))

Parameters: - db: Database to write - file: Output file path - format: Output format

Returns: Invisible NULL

Usage: Handles format selection and data preparation for serialisation.

Default Databases

`get_default_db()`

Generic function to retrieve any default database.

# Internal function in default-databases.R
get_default_db(type)

Parameters: - type: Database type (methods, measures, results, etc.)

Returns: Default database structure

Usage: Provides starter content for new databases.

Category-specific getters

get_default_methods_db(): Default methods content
get_default_measures_db(): Default measures content
get_default_results_db(): Default results content
get_default_discussion_db(): Default discussion content
get_default_appendix_db(): Default appendix content
get_default_template_db(): Default template variables

JSON Support Functions

`standardise_json_structure()`

Ensures JSON structure matches expected RDS format.

# Internal function in json-support.R
standardise_json_structure(json_data, db_type)

Parameters: - json_data: Raw JSON data - db_type: Type of database

Returns: Standardised structure

Usage: Handles format differences between JSON and RDS representations.

`clean_for_json()`

Prepares R objects for JSON serialisation.

# Internal function in migration-utilities.R
clean_for_json(obj)

Parameters: - obj: R object to clean

Returns: JSON-compatible object

Usage: Removes NULL values and ensures JSON compatibility.

Bibliography Support

`parse_bibtex_keys()`

Extracts citation keys from BibTeX files.

# Internal function in bibliography-support.R
parse_bibtex_keys(bib_file)

Parameters: - bib_file: Path to .bib file

Returns: Character vector of citation keys

Usage: Used for reference validation.

`extract_citation_keys()`

Finds citation references in text.

# Internal function in bibliography-support.R
extract_citation_keys(text)

Parameters: - text: Text to search

Returns: Character vector of citation keys found

Usage: Extracts @key style citations from markdown text.

Migration Utilities

`detect_database_type()`

Determines database type from filename or structure.

# Internal function in migration-utilities.R
detect_database_type(file_or_db)

Parameters: - file_or_db: Filename or database object

Returns: Database type string

Usage: Enables automatic type detection during migrations.

`migrate_to_unified_json()`

Migrates separate JSON files to unified format.

# Internal function in json-support.R
migrate_to_unified_json(input_dir, output_file)

Parameters: - input_dir: Directory with separate JSON files - output_file: Output unified JSON file

Returns: Invisible TRUE on success

Usage: Consolidates multiple JSON files into single unified database.

Measures-Specific Functions

`transform_label()`

Transforms measure labels using mapping rules.

# Internal function in generate-measures.R
transform_label(label, transformations)

Parameters: - label: Original label - transformations: Named list of transformations

Returns: Transformed label

Usage: Applies standardised transformations to measure labels.

Best Practices for Using Internal Functions

Error Handling: Most internal functions assume valid inputs. Always validate before calling.
Path Operations: Use dot notation consistently (e.g., “category.subcategory.item”)
Database Modifications: Always use modify_nested_entry() rather than direct list manipulation
File I/O: Use the provided read/write functions to ensure format compatibility
Testing: Internal functions should be tested indirectly through their exported wrappers

Contributing New Internal Functions

When adding new internal functions:

Document with roxygen2 comments including @noRd
Include parameter descriptions and return value
Add examples in comments
Ensure the function is truly internal (not user-facing)
Consider adding unit tests via exported function tests
Update this vignette if the function is important for contributors

Introduction

Core Database Operations

Database Structure Navigation

get_nested_folder()

modify_nested_entry()

Database Utilities

sort_db_recursive()

merge_recursive_lists()

Template System

apply_template_vars()

File I/O Operations

get_db_file_path()

read_boilerplate_db()

write_boilerplate_db()