---
title: "Internal Functions Guide for Developers"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Internal Functions Guide for Developers}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

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

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

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

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

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

```r
# 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:**
```r
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.

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

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

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

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

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

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

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

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

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

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

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