# 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

## Database Structure Navigation

### `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

1. Error Handling: Most internal functions assume valid inputs. Always validate before calling.

2. Path Operations: Use dot notation consistently (e.g., “category.subcategory.item”)

3. Database Modifications: Always use `modify_nested_entry()` rather than direct list manipulation

4. File I/O: Use the provided read/write functions to ensure format compatibility

5. Testing: Internal functions should be tested indirectly through their exported wrappers

# Contributing New Internal Functions

When adding new internal functions:

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