Internal Functions Guide for Developers

Introduction

The internal functions in boilerplate define how the package navigates databases, writes files, and generates text. This vignette documents those non-exported functions for contributors who need to understand the package architecture.

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 format.

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

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()