---
title: "Getting started with the config package"
output:
  rmarkdown::html_vignette:
    css:
    - !expr system.file("rmarkdown/templates/html_vignette/resources/vignette.css", package = "rmarkdown")
    - ../man/fragments/codeblock.css
vignette: >
  %\VignetteIndexEntry{Getting started with the config package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
# knitr::opts_chunk$set(eval = TRUE, results = 'hide')
Sys.setenv(R_CONFIG_ACTIVE = "default")
```

```{r child="../man/fragments/knitr_with_config_hooks.Rmd", include = FALSE}
```

## Overview

The `config` package makes it easy to manage environment specific configuration values. For example, you might want to use distinct values for development, testing, and production environments.


## Usage

Configurations are defined using a [YAML](https://yaml.org/about.html) text file and are read by default from a file named **config.yml** in the current working directory (or parent directories if no config file is found in the initially specified directory).

Configuration files include default values as well as values for arbitrary other named configurations, for example:


```{yaml output.var="config_yaml"}
default:
  trials: 5
  dataset: "data-sampled.csv"
  
production:
  trials: 30
  dataset: "data.csv"
```

To read configuration values you call the `config::get` function, which returns a list containing all of the values for the currently active configuration:

```{r, with_config=TRUE, config_yml="config_yaml"}
config <- config::get()
config$trials
config$dataset
```

You can also read a single value from the configuration as follows:

```{r, with_config=TRUE, config_yml="config_yaml"}
config::get("trials")
config::get("dataset")
```

The `get` function takes an optional `config` argument which determines which configuration to read values from (the "default" configuration is used if none is specified). 

## Configurations

You can specify which configuration is currently active by setting the `R_CONFIG_ACTIVE` environment variable. The `R_CONFIG_ACTIVE` variable is typically set within a site-wide `Renviron` or `Rprofile` (see [R Startup](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) for details on these files).

```{r, with_config=TRUE, config_yml="config_yaml"}
# set the active configuration globally via Renviron.site or Rprofile.site
Sys.setenv(R_CONFIG_ACTIVE = "production")

# read configuration value (will return 30 from the "production" config)
config::get("trials")
```

You can check whether a particular configuration is active using the `config::is_active` function:

```{r, with_config=TRUE, config_yml="config_yaml"}
config::is_active("production")
```

```{r}
Sys.setenv(R_CONFIG_ACTIVE = "default")
```

## Configuration Files

By default configuration data is read from a file named **config.yml** within the current working directory (or parent directories if no config file is found in the initially specified directory). 

You can use the `file` argument of `config::get` to read from an alternate location. For example:

```{r, eval=FALSE}
config <- config::get(file = "conf/config.yml")
```

If you don't want to ever scan parent directories for configuration files then you can specify `use_parent = FALSE`:

```{r, eval=FALSE}
config <- config::get(file = "conf/config.yml", use_parent = FALSE)
```




```{r child="../man/fragments/no_attach.Rmd"}
```