---
title: "Getting started with infuser"
author: "Bart Smeets"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

> Note: this is a copy of the README file.

```infuser``` is a simple and very basic templating engine for R. It replaces parameters within templates with specified values. Templates can be either contained in a string or in a file.

## Installation

```{r, eval=FALSE}
install.packages("infuser")
```

If you want to use the most up-to-date version, install using ```devtools::install_github```.

```{r, eval=FALSE}
devtools::install_github("Bart6114/infuser")
```

## Hello World

A simple Hello World example that makes use of the `magrittr` piping workflow.

```{r}
library(infuser)
library(magrittr)

"Hello {{var1}}!" %>%
  infuse(var1="world")
```

## Usage

### Working with character strings as templates

Let's have a look at an example string.

```{r}
my_sql<-"SELECT * FROM Customers
WHERE Year = {{year}}
AND Month = {{month|3}};"
```

Here the variable parameters are enclosed by ```{{``` and ```}}``` characters. See ```?infuse``` to use your own specification.

From now on, we suppose the character string ```my_sql```  is our template. To show the parameters requested by the template you can run the following.

```{r, results='hide'}
library(infuser)
variables_requested(my_sql, verbose = TRUE)
```

To fill in the template simply provide the requested parameters.

```{r}
  infuse(my_sql, year=2016, month=8)
```

You can also provide a named list with the requested parameters.

```{r}
my_list<- 
  list(year=2016,
       month=8)

infuse(my_sql, my_list)
```

If a default value is available in the template, it will be used if the parameter is not specified.

```{r}
infuse(my_sql, year=2016)
```

### Working with text files as templates

Just like we're using a string here, a text file can be used. An example text file can be found in the package as follows:

```{r}
example_file<-
  system.file("extdata", "sql1.sql", package="infuser")

example_file
```

Again, we can check which parameters are requested by the template.

```{r, results='hide'}
variables_requested(example_file, verbose = TRUE)
```

And provide their values.

```{r}
infuse(example_file, year = 2016, month = 12)
```

### Infusing vectors

It is quite easy to infuse a vector.

```{r}
years <- c(2013,2014,2015)
sql_string <- "SELECT * FROM T1 WHERE Year IN ({{years}})"

infuse(sql_string, years=years)
```

You can also specify the collapse character.

```{r}
infuse(sql_string, years=years, collapse_char = ";")
```



### Processing / transforming your inputs

A ```transform_function``` can be specified in the ```infuse``` command. This allows for pre-processing of the parameter values before inserting them in the template.

What we don't want to happen is the following:

```{r}
sql<-"INSERT INTO Students (Name) VALUES ({{name}})"
name <- "Robert'); DROP TABLE Students;--"

infuse(sql, name = name)
```

Yikes! A way to solve this is to specify your own custom transform function.

```{r}
my_transform_function<-function(v){
  # replace single quotes with double quotes
  v<-gsub("'", "''", v)
  # encloses the string in single quotes
  v<-paste0("'",v,"'")
  
  return(v)
}

infuse(sql, name = name, transform_function = my_transform_function)
```

Of course you can also use functions from other packages. Specifically for SQL I advise you to take a look at the `dbplyr::build_sql` function.


```{r}
infuse(sql, name = name, transform_function = dbplyr::build_sql)
```
