---
title: "Advanced Usage of rconf: A Detailed Guide"
author: "Yaoxiang Li"
date: "2017-12-09"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Advanced Usage of rconf: A Detailed Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


# Introduction

*rconf* is a minimal and lightweight configuration tool for R that parses basic YAML configuration files without any external dependencies. This vignette provides a detailed guide on using rconf for various scenarios—from basic configuration loading to advanced techniques such as dynamic configuration selection and merging configurations.

## Basic Usage

The simplest way to use *rconf* is to load a configuration file and extract settings. For example, assume you have a configuration file stored in the package’s `inst/extdata` directory. You can load it as follows:

```{r}
library(rconf)

# Load the default configuration from the sample file in extdata.
cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"))
print(cfg)
```

The returned list `cfg` will contain keys such as `raw_data_dir`, `sample_metadata`, and analysis parameters defined in your YAML file.

## Working with Multiple Configurations

Your YAML file can contain multiple configuration sets (e.g., `default`, `development`, `production`). For example, consider the following YAML snippet:

```yaml

default:
  raw_data_dir: "/data/proteomics/raw"
  processed_data_dir: "/data/proteomics/processed"
  sample_metadata: "/data/proteomics/metadata/samples.csv"
  normalization_method: "median"

development:
  raw_data_dir: "/data/dev/proteomics/raw"
  processed_data_dir: "/data/dev/proteomics/processed"
  sample_metadata: "/data/dev/proteomics/metadata/samples_dev.csv"
  normalization_method: "quantile"

```
You can load a specific configuration by passing the desired configuration name:

```{r}
# Load the 'development' configuration
dev_cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"), 
                      config_name = "development")
print(dev_cfg$raw_data_dir)

```

## Advanced Parsing Features

The `rconf` parser supports the following:

- Inline Comments:
  Any text following a space and a hash ( #) is removed from the value.
  For example:
  
```yaml
file_type: bam       # options: bam or bed
```

yields a value of `"bam"`.

Inline Arrays:
  Arrays specified inline are flattened into atomic vectors. For example:
  
```yaml
state_numbers: [25, 30, 35]
``` 

is parsed into the numeric vector `c(25, 30, 35)`.

Nested Keys:
  Indentation is used to create nested lists. For example:
  
```yaml
plot:
  output_dir: "results/plots"
  format: "png"
```
results in a `list` plot with elements: `output_dir` and `format`.


## Overriding and Merging Configurations
Because `rconf` returns a list, you can easily override configuration values at runtime. For instance:

```{r}
# Load default configuration
cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"))

# Override a parameter
cfg$normalization_method <- "z-score"
print(cfg$normalization_method)

```

## Merging Configurations
You can also merge multiple configurations. For example, if you have a `development` configuration and want to override specific parameters with values from the `default` configuration, you can do so as follows:
```{r}
base_cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"), config_name = "default")
dev_cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"), config_name = "development")
combined_cfg <- merge_configs(base_cfg, dev_cfg)
print(combined_cfg)
```

## Dynamic Configuration Selection

If your project needs to choose configurations dynamically (e.g., based on an environment variable), you can create a helper function:

```{r}
select_config <- function() {
  env <- Sys.getenv("APP_ENV", unset = "default")
  cfg <- get_config(system.file("extdata", "config.yml", package = "rconf"), config_name = env)
  cfg
}

# Example usage:
Sys.setenv(APP_ENV = "development")
current_cfg <- select_config()
print(current_cfg)

```

## Troubleshooting
- Empty or Missing Values:
  Ensure that your YAML file does not contain only comments or blank lines; otherwise, rconf will return an empty list.
  
- Parsing Errors:
  Double-check your YAML syntax (e.g., colon-separated key-value pairs, consistent indentation). The parser assumes a 2-space indentation for nested keys.
  
- Overriding Behavior:
  When merging configurations, note that nested lists are replaced rather than deeply merged. Use a custom merge function if you require deep merging.